The Samba-Bugzilla – Attachment 7 Details for
Bug 90
vfs interface docs not in CVS
Home
|
New
|
Browse
|
Search
|
[?]
|
Reports
|
Requests
|
Help
|
New Account
|
Log In
[x]
|
Forgot Password
Login:
[x]
[patch]
vfs.xml file as patch needs formating (to make pdf's look nicer)
vfs-xml-02.diff (text/plain), 23.97 KB, created by
Stefan Metzmacher
on 2003-05-19 04:07:17 UTC
(
hide
)
Description:
vfs.xml file as patch needs formating (to make pdf's look nicer)
Filename:
MIME Type:
Creator:
Stefan Metzmacher
Created:
2003-05-19 04:07:17 UTC
Size:
23.97 KB
patch
obsolete
>diff -Npur --exclude=CVS --exclude=*.bak --exclude=*.o --exclude=*.po --exclude=*.so --exclude=.#* --exclude=Makefile --exclude=stamp-h --exclude=configure --exclude=findsmb --exclude=*proto*.h --exclude=build_env.h --exclude=tdbsam2_parse_info.h --exclude=config.* --exclude=bin --exclude=*.configure --exclude=autom4te.cache --exclude=build_options.c* 3_0/docs/docbook/devdoc/vfs.xml 3_0-vfs/docs/docbook/devdoc/vfs.xml >--- 3_0/docs/docbook/devdoc/vfs.xml Thu Jan 1 01:00:00 1970 >+++ 3_0-vfs/docs/docbook/devdoc/vfs.xml Mon May 19 12:46:34 2003 >@@ -0,0 +1,786 @@ >+<chapter id="vfs"> >+<chapterinfo> >+ <author> >+ <firstname>Stefan</firstname><surname>Metzmacher</surname> >+ <affiliation> >+ <address><email>metze@metzemix.de</email></address> >+ </affiliation> >+ </author> >+ <pubdate> 27 April 2003 </pubdate> >+</chapterinfo> >+ >+<title>VFS Modules</title> >+ >+<sect1> >+<title>The Samba (Posix) VFS layer</title> >+ >+<sect2> >+<title>The general interface</title> >+ >+<para> >+Each VFS operation has a vfs_op_type, a function pointer and a handle pointer in the >+struct vfs_ops and tree macros to make it easier to call the operations. >+(Take a look at <filename>include/vfs.h</filename> and <filename>include/vfs_macros.h</filename>.) >+</para> >+ >+<para><programlisting> >+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; >+</programlisting></para> >+ >+<para>This struct contains the function and handle pointers for all operations.<programlisting> >+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; >+}; >+</programlisting></para> >+ >+<para> >+This macros SHOULD be used to call any vfs operation. >+DO NOT ACCESS conn->vfs.ops.* directly !!! >+<programlisting> >+... >+ >+/* 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_READ(fsp, fd, data, n) \ >+ ((fsp)->conn->vfs.ops.read(\ >+ (fsp)->conn->vfs.handles.read,\ >+ (fsp), (fd), (data), (n))) >+#define SMB_VFS_WRITE(fsp, fd, data, n) \ >+ ((fsp)->conn->vfs.ops.write(\ >+ (fsp)->conn->vfs.handles.write,\ >+ (fsp), (fd), (data), (n))) >+#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))) >+ >+... >+</programlisting></para> >+ >+</sect2> >+ >+<sect2> >+<title>Possible VFS operation layers</title> >+ >+<para> >+These values are used by the VFS subsystem when building the conn->vfs >+and conn->vfs_opaque structs for a connection with multiple VFS modules. >+Internally, Samba differentiates only opaque and transparent layers at this process. >+Other types are used for providing better diagnosing facilities. >+</para> >+ >+<para> >+Most modules will provide transparent layers. Opaque layer is for modules >+which implement actual file system calls (like DB-based VFS). For example, >+default POSIX VFS which is built in into Samba is an opaque VFS module. >+</para> >+ >+<para> >+Other layer types (logger, splitter, scanner) were designed to provide different >+degree of transparency and for diagnosing VFS module behaviour. >+</para> >+ >+<para> >+Each module can implement several layers at the same time provided that only >+one layer is used per each operation. >+</para> >+ >+<para><programlisting> >+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; >+</programlisting></para> >+ >+</sect2> >+ >+</sect1> >+ >+<sect1> >+<title>The Interaction between the Samba VFS subsystem and the modules</title> >+ >+<sect2> >+<title>Initialization and registration</title> >+ >+<para> >+As each Samba module a VFS module should have a >+<programlisting>NTSTATUS vfs_example_init(void);</programlisting> function if it's staticly linked to samba or >+<programlisting>NTSTATUS init_module(void);</programlisting> function if it's a shared module. >+</para> >+ >+<para> >+This should be the only non static function inside the module. >+Global variables should also be static! >+</para> >+ >+<para> >+The module should register its functions via the >+<programlisting> >+NTSTATUS smb_register_vfs(int version, const char *name, vfs_op_tuple *vfs_op_tuples); >+</programlisting> function. >+</para> >+ >+<variablelist> >+ >+<varlistentry><term>version</term> >+<listitem><para>should be filled with SMB_VFS_INTERFACE_VERSION</para></listitem> >+</varlistentry> >+ >+<varlistentry><term>name</term> >+<listitem><para>this is the name witch can be listed in the >+<command>vfs objects</command> parameter to use this module.</para></listitem> >+</varlistentry> >+ >+<varlistentry><term>vfs_op_tuples</term> >+<listitem><para> >+this is an array of vfs_op_tuple's. >+(vfs_op_tuples is descripted in details below.) >+</para></listitem> >+</varlistentry> >+ >+</variablelist> >+ >+<para> >+For each operation the module wants to provide it has a entry in the >+vfs_op_tuple array. >+</para> >+ >+<programlisting> >+typedef struct _vfs_op_tuple { >+ void* op; >+ vfs_op_type type; >+ vfs_op_layer layer; >+} vfs_op_tuple; >+</programlisting> >+ >+<variablelist> >+ >+<varlistentry><term>op</term> >+<listitem><para>the function pointer to the specified function.</para></listitem> >+</varlistentry> >+ >+<varlistentry><term>type</term> >+<listitem><para>the vfs_op_type of the function to specified witch operation the function provides.</para></listitem> >+</varlistentry> >+ >+<varlistentry><term>layer</term> >+<listitem><para>the vfs_op_layer in witch the function operates.</para></listitem> >+</varlistentry> >+ >+</variablelist> >+ >+<para>A simple example:</para> >+ >+<programlisting> >+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 */ >+ {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); >+} >+</programlisting> >+ >+</sect2> >+ >+<sect2> >+<title>How the Modules handle per connection data</title> >+ >+<para>Each VFS function has as first parameter a pointer to the modules vfs_handle_struct. >+</para> >+ >+<programlisting> >+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; >+</programlisting> >+ >+<variablelist> >+ >+<varlistentry><term>param</term> >+<listitem><para>this is the module parameter specified in the <command>vfs objects</command> parameter.</para> >+<para>e.g. for 'vfs objects = example:test' param would be "test".</para></listitem> >+</varlistentry> >+ >+<varlistentry><term>vfs_next</term> >+<listitem><para>This vfs_ops struct contains the information for calling the next module operations. >+Use the vfs_next_* macros to call a next module operations and >+don't access handle->vfs_next.ops.* directly!</para></listitem> >+</varlistentry> >+ >+<varlistentry><term>conn</term> >+<listitem><para>This is a pointer back to the connection_struct to witch the handle belongs.</para></listitem> >+</varlistentry> >+ >+<varlistentry><term>data</term> >+<listitem><para>This is a pointer for holding module private data. >+You can alloc data with connection life time on the handle->conn->mem_ctx TALLOC_CTX. >+But you can also manage the memory allocation yourself.</para></listitem> >+</varlistentry> >+ >+<varlistentry><term>free_data</term> >+<listitem><para>This is a function pointer to a function that free's the module private data. >+If you talloc your private data on the TALLOC_CTX handle->conn->mem_ctx, >+you can set this function pointer to NULL.</para></listitem> >+</varlistentry> >+ >+</variablelist> >+ >+<para>Some usefull MACROS for handle private data. >+</para> >+ >+<programlisting> >+#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); \ >+ } \ >+} >+</programlisting> >+ >+<para>How SMB_VFS_LAYER_TRANSPARENT functions can call the SMB_VFS_LAYER_OPAQUE functions.</para> >+ >+<para>The easiest way to do this is to use the SMB_VFS_OPAQUE_* macros. >+</para> >+ >+<programlisting> >+... >+/* 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))) >+... >+</programlisting> >+ >+<para>How SMB_VFS_LAYER_TRANSPARENT functions can call the next modules functions.</para> >+ >+<para>The easiest way to do this is to use the SMB_VFS_NEXT_* macros. >+</para> >+ >+<programlisting> >+... >+/* 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))) >+... >+</programlisting> >+ >+</sect2> >+ >+</sect1> >+ >+<sect1> >+<title>Upgrading to the New VFS Interface</title> >+ >+<sect2> >+<title>Upgrading from 2.2.* and 3.0aplha modules</title> >+ >+<orderedlist> >+<listitem><para> >+Add "vfs_handle_struct *handle, " as first parameter to all vfs operation functions. >+e.g. example_connect(connection_struct *conn, const char *service, const char *user); >+-> example_connect(vfs_handle_struct *handle, connection_struct *conn, const char *service, const char *user); >+</para></listitem> >+ >+<listitem><para> >+Replace "default_vfs_ops." with "vfs_next_". >+e.g. default_vfs_ops.connect(conn, service, user); >+-> vfs_next_connect(conn, service, user); >+</para> >+ >+<listitem><para> >+Uppercase all "vfs_next_*" functions. >+e.g. vfs_next_connect(conn, service, user); >+-> SMB_VFS_NEXT_CONNECT(conn, service, user); >+</para></listitem> >+ >+<listitem><para> >+Add "handle, " as first parameter to all SMB_VFS_NEXT_*() calls. >+e.g. SMB_VFS_NEXT_CONNECT(conn, service, user); >+-> SMB_VFS_NEXT_CONNECT(handle, conn, service, user); >+</para></listitem> >+ >+<listitem><para> >+(Only for 2.2.* modules) >+Convert the old struct vfs_ops example_ops to >+a vfs_op_tuple example_op_tuples[] array. >+e.g. >+<programlisting> >+struct vfs_ops example_ops = { >+ /* Disk operations */ >+ example_connect, /* connect */ >+ example_disconnect, /* disconnect */ >+ NULL, /* disk free * >+ /* Directory operations */ >+ NULL, /* opendir */ >+ NULL, /* readdir */ >+ NULL, /* mkdir */ >+ NULL, /* rmdir */ >+ NULL, /* closedir */ >+ /* File operations */ >+ NULL, /* open */ >+ NULL, /* close */ >+ NULL, /* read */ >+ NULL, /* write */ >+ NULL, /* lseek */ >+ NULL, /* sendfile */ >+ NULL, /* rename */ >+ NULL, /* fsync */ >+ example_stat, /* stat */ >+ example_fstat, /* fstat */ >+ example_lstat, /* lstat */ >+ NULL, /* unlink */ >+ NULL, /* chmod */ >+ NULL, /* fchmod */ >+ NULL, /* chown */ >+ NULL, /* fchown */ >+ NULL, /* chdir */ >+ NULL, /* getwd */ >+ NULL, /* utime */ >+ NULL, /* ftruncate */ >+ NULL, /* lock */ >+ NULL, /* symlink */ >+ NULL, /* readlink */ >+ NULL, /* link */ >+ NULL, /* mknod */ >+ NULL, /* realpath */ >+ NULL, /* fget_nt_acl */ >+ NULL, /* get_nt_acl */ >+ NULL, /* fset_nt_acl */ >+ NULL, /* set_nt_acl */ >+ >+ NULL, /* chmod_acl */ >+ NULL, /* fchmod_acl */ >+ >+ NULL, /* sys_acl_get_entry */ >+ NULL, /* sys_acl_get_tag_type */ >+ NULL, /* sys_acl_get_permset */ >+ NULL, /* sys_acl_get_qualifier */ >+ NULL, /* sys_acl_get_file */ >+ NULL, /* sys_acl_get_fd */ >+ NULL, /* sys_acl_clear_perms */ >+ NULL, /* sys_acl_add_perm */ >+ NULL, /* sys_acl_to_text */ >+ NULL, /* sys_acl_init */ >+ NULL, /* sys_acl_create_entry */ >+ NULL, /* sys_acl_set_tag_type */ >+ NULL, /* sys_acl_set_qualifier */ >+ NULL, /* sys_acl_set_permset */ >+ NULL, /* sys_acl_valid */ >+ NULL, /* sys_acl_set_file */ >+ NULL, /* sys_acl_set_fd */ >+ NULL, /* sys_acl_delete_def_file */ >+ NULL, /* sys_acl_get_perm */ >+ NULL, /* sys_acl_free_text */ >+ NULL, /* sys_acl_free_acl */ >+ NULL /* sys_acl_free_qualifier */ >+}; >+</programlisting> >+-> >+<programlisting> >+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_fstat), SMB_VFS_OP_FSTAT, SMB_VFS_LAYER_TRANSPARENT}, >+ {SMB_VFS_OP(example_stat), SMB_VFS_OP_STAT, SMB_VFS_LAYER_TRANSPARENT}, >+ {SMB_VFS_OP(example_lstat), SMB_VFS_OP_LSTAT, SMB_VFS_LAYER_TRANSPARENT}, >+ >+ {NULL, SMB_VFS_OP_NOOP, SMB_VFS_LAYER_NOOP} >+}; >+</programlisting> >+</para></listitem> >+ >+<listitem><para> >+Move the example_op_tuples[] array to the end of the file. >+</para></listitem> >+ >+<listitem><para> >+Add the init_module() function at the end of the file. >+e.g. >+<programlisting> >+NTSTATUS init_module(void) >+{ >+ return smb_register_vfs(SMB_VFS_INTERFACE_VERSION,"example",example_op_tuples); >+} >+</programlisting> >+</para></listitem> >+ >+<listitem><para> >+Check if your vfs_init() function does more then just prepare the vfs_ops structs or >+remember the struct smb_vfs_handle_struct. >+- If NOT you can remove the vfs_init() function. >+- If YES decide if you want to move the code to the example_connect() operation or to the init_module(). >+ And then remove vfs_init(). >+ e.g. >+ - a debug class registration should go into init_module(). >+ - the allocation of private data should go to example_connect(). >+</para></listitem> >+ >+<listitem><para> >+(Only for 3.0aplha* modules) >+Check if your vfs_done() function contains needed code. >+- If NOT you can remove the vfs_done() function. >+- If YES decide if you can move the code to the example_disconnect() operation. >+ Otherwise register a SMB_EXIT_EVENT with smb_register_exit_event(); >+ (Described in the MODULES section of the Samba-Developer-HOWTO.) >+ And then remove vfs_done(). >+ e.g. the freeing of private data should go to example_disconnect(). >+</para></listitem> >+ >+<listitem><para> >+Check if you have any global variables left. >+- Decide if it wouldn't be better to have this data on a connection basis. >+ - If NOT leave them as they are. >+ (e.g. this could be the variable for the private debug class.) >+ - If YES pack all this data into a struct. >+ You can use handle->data to point to such a struct on a >+ per connection basis. >+ >+ e.g. if you have such a struct: >+<programlisting> >+struct example_privates { >+ char *some_string; >+ int db_connection; >+}; >+</programlisting> >+1st way of doing it: >+<programlisting> >+static int example_connect(vfs_handle_struct *handle, >+ connection_struct *conn, const char *service, >+ const char* user) >+{ >+ struct example_privates *data = NULL; >+ >+ /* alloc our private data */ >+ data = (struct example_privates *)talloc_zero(conn->mem_ctx, sizeof(struct example_privates)); >+ if (!data) { >+ DEBUG(0,("talloc_zero() failed\n")); >+ return -1; >+ } >+ >+ /* init out private data */ >+ data->some_string = talloc_strdup(conn->mem_ctx,"test"); >+ if (!data->some_string) { >+ DEBUG(0,("talloc_strdup() failed\n")); >+ return -1; >+ } >+ >+ data->db_connection = open_db_conn(); >+ >+ /* and now store the private data pointer in handle->data >+ * we don't need to specify a free_function here because >+ * we use the connection TALLOC context. >+ * (return -1 if something failed.) >+ */ >+ VFS_HANDLE_SET_DATA(handle, data, NULL, struct example_privates, return -1); >+ >+ return SMB_VFS_NEXT_CONNECT(handle,conn,service,user); >+} >+ >+static int example_close(vfs_handle_struct *handle, files_struct *fsp, int fd) >+{ >+ struct example_privates *data = NULL; >+ >+ /* get the pointer to our private data >+ * return -1 if something failed >+ */ >+ VFS_HANDLE_GET_DATA(handle, data, struct example_privates, return -1); >+ >+ /* do something here...*/ >+ DEBUG(0,("some_string: %s\n",data->some_string)); >+ >+ return SMB_VFS_NEXT_CLOSE(handle, fsp, fd); >+} >+</programlisting> >+2nd way of doing it: >+<programlisting> >+static void free_example_privates(void **datap) >+{ >+ struct example_privates *data = (struct example_privates *)*datap; >+ >+ SAFE_FREE(data->some_string); >+ SAFE_FREE(data); >+ >+ datap = NULL; >+ >+ return; >+} >+ >+static int example_connect(vfs_handle_struct *handle, >+ connection_struct *conn, const char *service, >+ const char* user) >+{ >+ struct example_privates *data = NULL; >+ >+ /* alloc our private data */ >+ data = (struct example_privates *)malloc(sizeof(struct example_privates)); >+ if (!data) { >+ DEBUG(0,("malloc() failed\n")); >+ return -1; >+ } >+ >+ /* init out private data */ >+ data->some_string = strdup(conn->mem_ctx,"test"); >+ if (!data->some_string) { >+ DEBUG(0,("strdup() failed\n")); >+ return -1; >+ } >+ >+ data->db_connection = open_db_conn(); >+ >+ /* and now store the private data pointer in handle->data >+ * we need to specify a free_function because we used malloc() and strdup(). >+ * (return -1 if something failed.) >+ */ >+ VFS_HANDLE_SET_DATA(handle, data, NULL, struct example_privates, return -1); >+ >+ return SMB_VFS_NEXT_CONNECT(handle,conn,service,user); >+} >+ >+static int example_close(vfs_handle_struct *handle, files_struct *fsp, int fd) >+{ >+ struct example_privates *data = NULL; >+ >+ /* get the pointer to our private data >+ * return -1 if something failed >+ */ >+ VFS_HANDLE_GET_DATA(handle, data, struct example_privates, return -1); >+ >+ /* do something here...*/ >+ DEBUG(0,("some_string: %s\n",data->some_string)); >+ >+ return SMB_VFS_NEXT_CLOSE(handle, fsp, fd); >+} >+</programlisting> >+</para></listitem> >+ >+<listitem><para> >+To make it easy to build 3rd party modules it would be usefull to provide >+configure.in, (configure), install.sh and Makefile.in with the module. >+(Take a look at the example in <filename>examples/VFS</filename>.) >+ >+The configure script accept --with-samba-source to specify the path to >+the samba source tree. >+It also accept --enable-developer witch let the compiler give you more warnings. >+ >+The idea is that you can extend this configure.in and Makefile.in scripts >+for your module. >+</para></listitem> >+ >+<listitem><para> >+Compiling & Testing... >+- configure --enable-developer ... >+- make >+- Try to fiy all compiler warnings >+- make >+- Testing, Testing, Testing ... >+</para></listitem> >+</orderedlist> >+</sect2> >+ >+</sect1> >+ >+<sect1> >+<title>Some Notes</title> >+ >+<sect2> >+<title>Implement TRANSPARENT functions</title> >+ >+<para> >+Avoid to functions loke this: >+ >+<programlisting> >+static int example_close(vfs_handle_struct *handle, files_struct *fsp, int fd) >+{ >+ return SMB_VFS_NEXT_CLOSE(handle, fsp, fd); >+} >+</programlisting> >+ >+Overload only the functions you really need to! >+</para> >+ >+</sect2> >+ >+<sect2> >+<title>Implement OPAQUE functions</title> >+ >+<para> >+If you want just implement only a better version of a >+default samba opaque function >+(e.g. like a disk_free() function for a speciall filesystem) >+it's ok to just overload this specific function. >+</para> >+ >+<para> >+If you want to implement a database filesystem or >+something different from a posix filesystem. >+Make sure that you overload every vfs operation!!! >+</para> >+<para> >+Functions your FS didn't support should be overloaded by something like this: >+e.g. for a readonly filesystem. >+</para> >+ >+<programlisting> >+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; >+} >+</programlisting> >+ >+</sect2> >+ >+</sect1> >+ >+</chapter>
You cannot view the attachment while viewing its details because your browser does not support IFRAMEs.
View the attachment on a separate page
.
View Attachment As Raw
Actions:
View
Attachments on
bug 90
: 7