VFSモジュールには3つの主要なコンポーネントがある:

この構造がVFSサブシステムに対して最初に適用された間、ローダブルモジュールを サポートするすべてのSamba3サブシステムにまたがって、現在共通的に使われる。実際、ある1つの モジュールは異なったオペレーションテーブルを分離された 初期化関数を通して公開することで、異なったサブシステムに対しての 数多くのインタフェースを提供できる。

初期化関数は、Samba動作時にモジュールを登録するのに使われる。 Sambaの内部構造体とAPIは、日時が経つにつれ変化し、各リリースバージョンは、VFSの開発作業の ために増加したVFSインタフェースバージョンを持つか、任意のSambaの構造体が、バイナリ 非互換の方式で変更される。VFSモジュールがコンパイルされるとき、Samba環境のVFS インタフェースバージョンはモジュールのバイナリオブジェクト中に埋め込まれ、それは モジュールのロード時にSambaコアによってチェックされる。もしも、モジュールによって 通知されるVFSインタフェース番号が、Sambaコアが認識するものと一致しない場合、バージョンの 不一致が検出され、(変更された)Samba構造体をアクセスするときに、メモリ破壊の可能性を 防ぐために、モジュールはロードされない。

それ故、初期化関数はVFS登録関数 smb_register_vfs()に 3つのパラメーターを渡す。

オペレーションテーブルは、モジュール内のどの関数が、特定の VFS操作に対応しているかと、どのようにそれらの関数を、残りのVFSサブシステムと協調 させるかを定義する。各オペレーションは以下の方法で実行できる:

基本的に、transparent, opaqueと loggerという3つのタイプがある。Splitterと scannerは、開発者を混乱させるかもしれない(そして、我々の 経験が示すように、彼らは全く混乱している)が、この分割はモジュールの動作の性質を よりよく提示するはずである。これまでの所、開発されたほとんどのモジュールは、 transparentを伴いopaqueが一般的な、3つのタイプのどれかである。 Most of modules developed so far are either one of those three fundamental types with transparent and opaque being prevalent.

各VFS操作は、操作の呼び出しを簡単にさせるための、vfs_op_type、関数ポインターと vfs_ops構造体中のハンドルポインターと、treeマクロを持つ( include/vfs.h と include/vfs_macros.hを参照のこと)。

typedef enum _vfs_op_type {
	SMB_VFS_OP_NOOP = -1,

	...

	/* File operations */

	SMB_VFS_OP_OPEN,
	SMB_VFS_OP_CLOSE,
	SMB_VFS_OP_READ,
	SMB_VFS_OP_WRITE,
	SMB_VFS_OP_LSEEK,
	SMB_VFS_OP_SENDFILE,

	...

	SMB_VFS_OP_LAST
} vfs_op_type;

この構造体は関数とすべての操作のためのハンドルポインターを含む。

struct vfs_ops {
	struct vfs_fn_pointers {
		...
		
		/* File operations */
		
		int (*open)(struct vfs_handle_struct *handle,
			struct connection_struct *conn,
			const char *fname, int flags, mode_t mode);
		int (*close)(struct vfs_handle_struct *handle,
			struct files_struct *fsp, int fd);
		ssize_t (*read)(struct vfs_handle_struct *handle, 
			struct files_struct *fsp, int fd, void *data, size_t n);
		ssize_t (*write)(struct vfs_handle_struct *handle, 
			struct files_struct *fsp, int fd, 
			const void *data, size_t n);
		SMB_OFF_T (*lseek)(struct vfs_handle_struct *handle, 
			struct files_struct *fsp, int fd, 
			SMB_OFF_T offset, int whence);
		ssize_t (*sendfile)(struct vfs_handle_struct *handle, 
			int tofd, files_struct *fsp, int fromfd, 
			const DATA_BLOB *header, SMB_OFF_T offset, size_t count);

		...
	} ops;
	
	struct vfs_handles_pointers {
		...
		
		/* File operations */
		
		struct vfs_handle_struct *open;
		struct vfs_handle_struct *close;
		struct vfs_handle_struct *read;
		struct vfs_handle_struct *write;
		struct vfs_handle_struct *lseek;
		struct vfs_handle_struct *sendfile;
		
		...
	} handles;
};

このマクロは任意のvfs操作を呼び出すために*使われるべきである*。 直接conn->vfs.ops.*を呼び出しては*いけない!!!*

...
	
/* File operations */
#define SMB_VFS_OPEN(conn, fname, flags, mode) \
	((conn)->vfs.ops.open((conn)->vfs.handles.open,\
	 (conn), (fname), (flags), (mode)))
#define SMB_VFS_CLOSE(fsp, fd) \
	((fsp)->conn->vfs.ops.close(\
	(fsp)->conn->vfs.handles.close, (fsp), (fd)))
#define SMB_VFS_PREAD(fsp, fd, data, n, off) \
	((fsp)->conn->vfs.ops.read(\
	(fsp)->conn->vfs.handles.read,\
	 (fsp), (fd), (data), (n), (off)))
#define SMB_VFS_PWRITE(fsp, fd, data, n, off) \
	((fsp)->conn->vfs.ops.write(\
	(fsp)->conn->vfs.handles.write,\
	 (fsp), (fd), (data), (n), (off)))
#define SMB_VFS_LSEEK(fsp, fd, offset, whence) \
	((fsp)->conn->vfs.ops.lseek(\
	(fsp)->conn->vfs.handles.lseek,\
	 (fsp), (fd), (offset), (whence)))
#define SMB_VFS_SENDFILE(tofd, fsp, fromfd, header, offset, count) \
	((fsp)->conn->vfs.ops.sendfile(\
	(fsp)->conn->vfs.handles.sendfile,\
	 (tofd), (fsp), (fromfd), (header), (offset), (count)))

...

これらの値は、複数のVFSモジュールとの接続用に、conn->vfsとconn->vfs_opaque構造体を 構築するときに、VFSサブシステムによって使われる。内部的にSambaはこのプロセスで、opaqueと transparentレイヤのみを区別する。他のタイプは、よりよい診断機能を提供するために使われる。

ほとんどのモジュールはtransparentレイヤを提供する。opaqueレイヤは、実際のファイルシステム コール(DBベースのVFSのような)を実装するモジュール用である。例えば、既定値の、Sambaに 組み込まれているPOSIX VFSはopaque VFSモジュールである。

他のレイヤタイプ(logger, splitter, scanner)は異なったtransparencyの段階を提供するためと、 診断VFSモジュールの動作のために設計された。

各モジュールは、1つのレイヤは1つの操作毎に使われる、同じ時に提供されるいくつかの レイヤを実装できる。

typedef enum _vfs_op_layer {
	SMB_VFS_LAYER_NOOP = -1,	/* - For using in VFS module to indicate end of array */
					/*   of operations description */
	SMB_VFS_LAYER_OPAQUE = 0,	/* - Final level, does not call anything beyond itself */
	SMB_VFS_LAYER_TRANSPARENT,	/* - Normal operation, calls underlying layer after */
					/*   possibly changing passed data */
	SMB_VFS_LAYER_LOGGER,		/* - Logs data, calls underlying layer, logging may not */
					/*   use Samba VFS */
	SMB_VFS_LAYER_SPLITTER,		/* - Splits operation, calls underlying layer _and_ own facility, */
					/*   then combines result */
	SMB_VFS_LAYER_SCANNER		/* - Checks data and possibly initiates additional */
					/*   file activity like logging to files _inside_ samba VFS */
} vfs_op_layer;

各SambaモジュールはVFSモジュールで、それがSambaに静的にリンクされるならば、

NTSTATUS vfs_example_init(void);

関数か、 共有モジュールならば、

NTSTATUS init_module(void);

関数を持つべきである。

これは、モジュール内部の静的でない関数のみがそうすべきである。グローバル 変数は同様に静的であるべきである!

モジュールはその関数を

NTSTATUS smb_register_vfs(int version, const char *name, vfs_op_tuple *vfs_op_tuples);

関数経由で登録すべきである。

モジュールが提供することを望む各操作のために、vfs_op_tuple入れつん中にエントリが ある。

typedef struct _vfs_op_tuple {
	void* op;
	vfs_op_type type;
	vfs_op_layer layer;
} vfs_op_tuple;

簡単な例:

static vfs_op_tuple example_op_tuples[] = {	
	{SMB_VFS_OP(example_connect),	SMB_VFS_OP_CONNECT,	SMB_VFS_LAYER_TRANSPARENT},
	{SMB_VFS_OP(example_disconnect),	SMB_VFS_OP_DISCONNECT,	SMB_VFS_LAYER_TRANSPARENT},

	{SMB_VFS_OP(example_rename),	SMB_VFS_OP_RENAME,	SMB_VFS_LAYER_OPAQUE},

	/* This indicates the end of the array */
	{SMB_VFS_OP(NULL),				SMB_VFS_OP_NOOP,	SMB_VFS_LAYER_NOOP}
};

NTSTATUS init_module(void)
{
	return smb_register_vfs(SMB_VFS_INTERFACE_VERSION, "example", example_op_tuples);
}

各VFS関数の最初のパラメーターは、vfs_handle_structモジュールへのポインターである。

typedef struct vfs_handle_struct {
	struct vfs_handle_struct  *next, *prev;
	const char *param;
	struct vfs_ops vfs_next;
	struct connection_struct *conn;
	void *data;
	void (*free_data)(void **data);
} vfs_handle_struct;

固有データを扱うための、いくつかの有益なマクロ。

#define SMB_VFS_HANDLE_GET_DATA(handle, datap, type, ret) { \
	if (!(handle)||((datap=(type *)(handle)->data)==NULL)) { \
		DEBUG(0,("%s() failed to get vfs_handle->data!\n",FUNCTION_MACRO)); \
		ret; \
	} \
}

#define SMB_VFS_HANDLE_SET_DATA(handle, datap, free_fn, type, ret) { \
	if (!(handle)) { \
		DEBUG(0,("%s() failed to set handle->data!\n",FUNCTION_MACRO)); \
		ret; \
	} else { \
		if ((handle)->free_data) { \
			(handle)->free_data(&(handle)->data); \
		} \
		(handle)->data = (void *)datap; \
		(handle)->free_data = free_fn; \
	} \
}

#define SMB_VFS_HANDLE_FREE_DATA(handle) { \
	if ((handle) && (handle)->free_data) { \
		(handle)->free_data(&(handle)->data); \
	} \
}

SMB_VFS_LAYER_TRANSPARENT関数がSMB_VFS_LAYER_OPAQUE関数を呼び出せる方式。

これを行う最も簡単な方法は、SMB_VFS_OPAQUE_*マクロを使うことである。

...
/* File operations */
#define SMB_VFS_OPAQUE_OPEN(conn, fname, flags, mode) \
	((conn)->vfs_opaque.ops.open(\
	(conn)->vfs_opaque.handles.open,\
	 (conn), (fname), (flags), (mode)))
#define SMB_VFS_OPAQUE_CLOSE(fsp, fd) \
	((fsp)->conn->vfs_opaque.ops.close(\
	(fsp)->conn->vfs_opaque.handles.close,\
	 (fsp), (fd)))
#define SMB_VFS_OPAQUE_READ(fsp, fd, data, n) \
	((fsp)->conn->vfs_opaque.ops.read(\
	(fsp)->conn->vfs_opaque.handles.read,\
	 (fsp), (fd), (data), (n)))
#define SMB_VFS_OPAQUE_WRITE(fsp, fd, data, n) \
	((fsp)->conn->vfs_opaque.ops.write(\
	(fsp)->conn->vfs_opaque.handles.write,\
	 (fsp), (fd), (data), (n)))
#define SMB_VFS_OPAQUE_LSEEK(fsp, fd, offset, whence) \
	((fsp)->conn->vfs_opaque.ops.lseek(\
	(fsp)->conn->vfs_opaque.handles.lseek,\
	 (fsp), (fd), (offset), (whence)))
#define SMB_VFS_OPAQUE_SENDFILE(tofd, fsp, fromfd, header, offset, count) \
	((fsp)->conn->vfs_opaque.ops.sendfile(\
	(fsp)->conn->vfs_opaque.handles.sendfile,\
	 (tofd), (fsp), (fromfd), (header), (offset), (count)))
...

SMB_VFS_LAYER_TRANSPARENT関数が次のモジュール関数を呼び出せる方式。

これを行う最も簡単な方法は、SMB_VFS_NEXT_*マクロを使うことである。

...
/* File operations */
#define SMB_VFS_NEXT_OPEN(handle, conn, fname, flags, mode) \
	((handle)->vfs_next.ops.open(\
	(handle)->vfs_next.handles.open,\
	 (conn), (fname), (flags), (mode)))
#define SMB_VFS_NEXT_CLOSE(handle, fsp, fd) \
	((handle)->vfs_next.ops.close(\
	(handle)->vfs_next.handles.close,\
	 (fsp), (fd)))
#define SMB_VFS_NEXT_READ(handle, fsp, fd, data, n) \
	((handle)->vfs_next.ops.read(\
	(handle)->vfs_next.handles.read,\
	 (fsp), (fd), (data), (n)))
#define SMB_VFS_NEXT_WRITE(handle, fsp, fd, data, n) \
	((handle)->vfs_next.ops.write(\
	(handle)->vfs_next.handles.write,\
	 (fsp), (fd), (data), (n)))
#define SMB_VFS_NEXT_LSEEK(handle, fsp, fd, offset, whence) \
	((handle)->vfs_next.ops.lseek(\
	(handle)->vfs_next.handles.lseek,\
	 (fsp), (fd), (offset), (whence)))
#define SMB_VFS_NEXT_SENDFILE(handle, tofd, fsp, fromfd, header, offset, count) \
	((handle)->vfs_next.ops.sendfile(\
	(handle)->vfs_next.handles.sendfile,\
	 (tofd), (fsp), (fromfd), (header), (offset), (count)))
...

以下のような関数を書くことはしない:

static int example_close(vfs_handle_struct *handle, files_struct *fsp, int fd)
{
	return SMB_VFS_NEXT_CLOSE(handle, fsp, fd);
}

真に必要とする関数のみをオーバーロードすること!

もしも、既定値のSamba opaque関数よりもよりよいバージョンを実装したいならば (たとえば、特別なファイルシステムに対するdisk_free()関数のようなもの)、 その特定の関数をオーバーロードすることは問題ない。

もしもデータベースファイルシステムあるいはposixファイルシステムから異なる 何かを実装したい場合、すべてのvfs操作をオーバーロードするようにすること!!!

使用するファイルシステムがサポートしない機能は、以下のようなものでオーバーロードすべきである: たとえば、リードオンリファイルシステムなど。

static int example_rename(vfs_handle_struct *handle, connection_struct *conn,
			char *oldname, char *newname)
{
	DEBUG(10,("function rename() not allowed on vfs 'example'\n"));
	errno = ENOSYS;
	return -1;
}