1 /*=====================================================================
2 Unix SMB/Netbios implementation.
3 SMB client library API definitions
4 Copyright (C) Andrew Tridgell 1998
5 Copyright (C) Richard Sharpe 2000
6 Copyright (C) John Terpsra 2000
7 Copyright (C) Tom Jansen (Ninja ISD) 2002
8 Copyright (C) Derrell Lipman 2003-2008
11 This program is free software; you can redistribute it and/or modify
12 it under the terms of the GNU General Public License as published by
13 the Free Software Foundation; either version 3 of the License, or
14 (at your option) any later version.
16 This program is distributed in the hope that it will be useful,
17 but WITHOUT ANY WARRANTY; without even the implied warranty of
18 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 GNU General Public License for more details.
21 You should have received a copy of the GNU General Public License
22 along with this program; if not, see <http://www.gnu.org/licenses/>.
23 =====================================================================*/
25 #ifndef SMBCLIENT_H_INCLUDED
26 #define SMBCLIENT_H_INCLUDED
28 #undef DEPRECATED_SMBC_INTERFACE
29 #if ! defined(__LIBSMBCLIENT_INTERNAL__) && defined(__GNUC__)
30 # define DEPRECATED_SMBC_INTERFACE __attribute__ ((deprecated))
32 # define DEPRECATED_SMBC_INTERFACE
39 /*-------------------------------------------------------------------*/
40 /* The following are special comments to instruct DOXYGEN (automated
43 /** \defgroup libsmbclient
45 /** \defgroup structure Data Structures Type and Constants
46 * \ingroup libsmbclient
47 * Data structures, types, and constants
49 /** \defgroup callback Callback function types
50 * \ingroup libsmbclient
53 /** \defgroup file File Functions
54 * \ingroup libsmbclient
55 * Functions used to access individual file contents
57 /** \defgroup directory Directory Functions
58 * \ingroup libsmbclient
59 * Functions used to access directory entries
61 /** \defgroup attribute Attributes Functions
62 * \ingroup libsmbclient
63 * Functions used to view or change file and directory attributes
65 /** \defgroup print Print Functions
66 * \ingroup libsmbclient
67 * Functions used to access printing functionality
69 /** \defgroup misc Miscellaneous Functions
70 * \ingroup libsmbclient
71 * Functions that don't fit in to other categories
73 /*-------------------------------------------------------------------*/
75 /* Make sure we have the following includes for now ... */
76 #include <sys/types.h>
78 #include <sys/statvfs.h>
83 #define SMBC_BASE_FD 10000 /* smallest file descriptor returned */
85 #define SMBC_WORKGROUP 1
87 #define SMBC_FILE_SHARE 3
88 #define SMBC_PRINTER_SHARE 4
89 #define SMBC_COMMS_SHARE 5
90 #define SMBC_IPC_SHARE 6
96 * Structure that represents a directory entry.
105 SMBC_PRINTER_SHARE=4,
111 unsigned int smbc_type;
113 /** Length of this smbc_dirent in bytes
116 /** The length of the comment string in bytes (does not include
119 unsigned int commentlen;
120 /** Points to the null terminated comment string
123 /** The length of the name string in bytes (does not include
126 unsigned int namelen;
127 /** Points to the null terminated name string
132 /**@ingroup structure
133 * Structure that represents all attributes of a directory entry.
136 struct libsmb_file_info
143 * DOS attributes of file
155 * Birth/Create time of file (if supported by system)
156 * Otherwise the value will be 0
158 struct timespec btime_ts;
160 * Modified time for the file
162 struct timespec mtime_ts;
164 * Access time for the file
166 struct timespec atime_ts;
168 * Change time for the file
170 struct timespec ctime_ts;
182 * Logging callback function
184 typedef void (*smbc_debug_callback_fn)(void *private_ptr, int level, const char *msg);
187 * Flags for smbc_setxattr()
188 * Specify a bitwise OR of these, or 0 to add or replace as necessary
190 #define SMBC_XATTR_FLAG_CREATE 0x1 /* fail if attr already exists */
191 #define SMBC_XATTR_FLAG_REPLACE 0x2 /* fail if attr does not exist */
195 * Mappings of the DOS mode bits, as returned by smbc_getxattr() when the
196 * attribute name "system.dos_attr.mode" (or "system.dos_attr.*" or
197 * "system.*") is specified.
199 #define SMBC_DOS_MODE_READONLY 0x01
200 #define SMBC_DOS_MODE_HIDDEN 0x02
201 #define SMBC_DOS_MODE_SYSTEM 0x04
202 #define SMBC_DOS_MODE_VOLUME_ID 0x08
203 #define SMBC_DOS_MODE_DIRECTORY 0x10
204 #define SMBC_DOS_MODE_ARCHIVE 0x20
207 * Valid values for the option "open_share_mode", when calling
208 * smbc_setOptionOpenShareMode()
210 typedef enum smbc_share_mode
212 SMBC_SHAREMODE_DENY_DOS = 0,
213 SMBC_SHAREMODE_DENY_ALL = 1,
214 SMBC_SHAREMODE_DENY_WRITE = 2,
215 SMBC_SHAREMODE_DENY_READ = 3,
216 SMBC_SHAREMODE_DENY_NONE = 4,
217 SMBC_SHAREMODE_DENY_FCB = 7
222 * Values for option SMB Encryption Level, as set and retrieved with
223 * smbc_setOptionSmbEncryptionLevel() and smbc_getOptionSmbEncryptionLevel()
225 typedef enum smbc_smb_encrypt_level
227 SMBC_ENCRYPTLEVEL_NONE = 0,
228 SMBC_ENCRYPTLEVEL_REQUEST = 1,
229 SMBC_ENCRYPTLEVEL_REQUIRE = 2
230 } smbc_smb_encrypt_level;
234 * Capabilities set in the f_flag field of struct statvfs, from
235 * smbc_statvfs(). These may be OR-ed together to reflect a full set of
236 * available capabilities.
238 typedef enum smbc_vfs_feature
240 /* Defined by POSIX or in Linux include files (low-order bits) */
241 SMBC_VFS_FEATURE_RDONLY = (1 << 0),
243 /* Specific to libsmbclient (high-order bits) */
244 SMBC_VFS_FEATURE_DFS = (1 << 28),
245 SMBC_VFS_FEATURE_CASE_INSENSITIVE = (1 << 29),
246 SMBC_VFS_FEATURE_NO_UNIXCIFS = (1 << 30)
249 typedef int smbc_bool;
253 # define ENOATTR ENOENT /* No such attribute */
259 /**@ingroup structure
260 * Structure that represents a print job.
264 struct print_job_info
266 /** numeric ID of the print job
270 /** represents print job priority (lower numbers mean higher priority)
272 unsigned short priority;
274 /** Size of the print job
278 /** Name of the user that owns the print job
282 /** Name of the print job. This will have no name if an anonymous print
283 * file was opened. Ie smb://server/printer
287 /** Time the print job was spooled
291 #endif /* _CLIENT_H */
294 /**@ingroup structure
297 typedef struct _SMBCSRV SMBCSRV;
299 /**@ingroup structure
300 * File or directory handle
302 typedef struct _SMBCFILE SMBCFILE;
304 /**@ingroup structure
305 * File or directory handle
307 typedef struct _SMBCCTX SMBCCTX;
311 * Flags for SMBCCTX->flags
313 * NEW CODE SHOULD NOT DIRECTLY MANIPULATE THE CONTEXT STRUCTURE.
315 * smbc_setOptionUseKerberos()
316 * smbc_getOptionUseKerberos()
317 * smbc_setOptionFallbackAfterKerberos()
318 * smbc_getOptionFallbackAFterKerberos()
319 * smbc_setOptionNoAutoAnonymousLogin()
320 * smbc_getOptionNoAutoAnonymousLogin()
321 * smbc_setOptionUseCCache()
322 * smbc_getOptionUseCCache()
324 # define SMB_CTX_FLAG_USE_KERBEROS (1 << 0)
325 # define SMB_CTX_FLAG_FALLBACK_AFTER_KERBEROS (1 << 1)
326 # define SMBCCTX_FLAG_NO_AUTO_ANONYMOUS_LOGON (1 << 2)
327 # define SMB_CTX_FLAG_USE_CCACHE (1 << 3)
332 * Authentication callback function type (traditional method)
334 * Type for the the authentication function called by the library to
335 * obtain authentication credentials
337 * For kerberos support the function should just be called without
338 * prompting the user for credentials. Which means a simple 'return'
339 * should work. Take a look at examples/libsmbclient/get_auth_data_fn.h
340 * and examples/libsmbclient/testbrowse.c.
342 * @param srv Server being authenticated to
344 * @param shr Share being authenticated to
346 * @param wg Pointer to buffer containing a "hint" for the
347 * workgroup to be authenticated. Should be filled in
348 * with the correct workgroup if the hint is wrong.
350 * @param wglen The size of the workgroup buffer in bytes
352 * @param un Pointer to buffer containing a "hint" for the
353 * user name to be use for authentication. Should be
354 * filled in with the correct workgroup if the hint is
357 * @param unlen The size of the username buffer in bytes
359 * @param pw Pointer to buffer containing to which password
362 * @param pwlen The size of the password buffer in bytes
365 typedef void (*smbc_get_auth_data_fn)(const char *srv,
369 char *pw, int pwlen);
371 * Authentication callback function type (method that includes context)
373 * Type for the the authentication function called by the library to
374 * obtain authentication credentials
376 * For kerberos support the function should just be called without
377 * prompting the user for credentials. Which means a simple 'return'
378 * should work. Take a look at examples/libsmbclient/get_auth_data_fn.h
379 * and examples/libsmbclient/testbrowse.c.
381 * @param c Pointer to the smb context
383 * @param srv Server being authenticated to
385 * @param shr Share being authenticated to
387 * @param wg Pointer to buffer containing a "hint" for the
388 * workgroup to be authenticated. Should be filled in
389 * with the correct workgroup if the hint is wrong.
391 * @param wglen The size of the workgroup buffer in bytes
393 * @param un Pointer to buffer containing a "hint" for the
394 * user name to be use for authentication. Should be
395 * filled in with the correct workgroup if the hint is
398 * @param unlen The size of the username buffer in bytes
400 * @param pw Pointer to buffer containing to which password
403 * @param pwlen The size of the password buffer in bytes
406 typedef void (*smbc_get_auth_data_with_context_fn)(SMBCCTX *c,
411 char *pw, int pwlen);
415 * Print job info callback function type.
417 * @param i pointer to print job information structure
420 typedef void (*smbc_list_print_job_fn)(struct print_job_info *i);
424 * Check if a server is still good
426 * @param c pointer to smb context
428 * @param srv pointer to server to check
430 * @return 0 when connection is good. 1 on error.
433 typedef int (*smbc_check_server_fn)(SMBCCTX * c, SMBCSRV *srv);
436 * Remove a server if unused
438 * @param c pointer to smb context
440 * @param srv pointer to server to remove
442 * @return 0 on success. 1 on failure.
445 typedef int (*smbc_remove_unused_server_fn)(SMBCCTX * c, SMBCSRV *srv);
449 * Add a server to the cache system
451 * @param c pointer to smb context
453 * @param srv pointer to server to add
455 * @param server server name
457 * @param share share name
459 * @param workgroup workgroup used to connect
461 * @param username username used to connect
463 * @return 0 on success. 1 on failure.
466 typedef int (*smbc_add_cached_srv_fn) (SMBCCTX * c, SMBCSRV *srv,
467 const char * server, const char * share,
468 const char * workgroup, const char * username);
471 * Look up a server in the cache system
473 * @param c pointer to smb context
475 * @param server server name to match
477 * @param share share name to match
479 * @param workgroup workgroup to match
481 * @param username username to match
483 * @return pointer to SMBCSRV on success. NULL on failure.
486 typedef SMBCSRV * (*smbc_get_cached_srv_fn) (SMBCCTX * c, const char * server,
487 const char * share, const char * workgroup,
488 const char * username);
491 * Check if a server is still good
493 * @param c pointer to smb context
495 * @param srv pointer to server to remove
497 * @return 0 when found and removed. 1 on failure.
500 typedef int (*smbc_remove_cached_srv_fn)(SMBCCTX * c, SMBCSRV *srv);
504 * Try to remove all servers from the cache system and disconnect
506 * @param c pointer to smb context
508 * @return 0 when found and removed. 1 on failure.
511 typedef int (*smbc_purge_cached_fn) (SMBCCTX * c);
515 /*****************************************
516 * Getters and setters for CONFIGURATION *
517 *****************************************/
519 /** Get the debug level */
521 smbc_getDebug(SMBCCTX *c);
523 /** Set the debug level */
525 smbc_setDebug(SMBCCTX *c, int debug);
528 * set log callback function to capture logs from libsmbclient, this
529 * is applied at global level
532 smbc_setLogCallback(SMBCCTX *c, void *private_ptr,
533 smbc_debug_callback_fn fn);
535 /** set configuration file, this is applied at global level */
537 smbc_setConfiguration(SMBCCTX *c, const char *file);
539 /** Get the netbios name used for making connections */
541 smbc_getNetbiosName(SMBCCTX *c);
543 /** Set the netbios name used for making connections */
545 smbc_setNetbiosName(SMBCCTX *c, char * netbios_name);
547 /** Get the workgroup used for making connections */
549 smbc_getWorkgroup(SMBCCTX *c);
551 /** Set the workgroup used for making connections */
552 void smbc_setWorkgroup(SMBCCTX *c, char * workgroup);
554 /** Get the username used for making connections */
556 smbc_getUser(SMBCCTX *c);
558 /** Set the username used for making connections */
560 smbc_setUser(SMBCCTX *c, const char *user);
563 * Get the timeout used for waiting on connections and response data
567 smbc_getTimeout(SMBCCTX *c);
570 * Set the timeout used for waiting on connections and response data
574 smbc_setTimeout(SMBCCTX *c, int timeout);
578 * Get the TCP port used to connect (0 means default).
581 smbc_getPort(SMBCCTX *c);
584 * Set the TCP port used to connect (0 means default).
587 smbc_setPort(SMBCCTX *c, uint16_t port);
591 /***********************************
592 * Getters and setters for OPTIONS *
593 ***********************************/
595 /** Get whether to log to standard error instead of standard output */
597 smbc_getOptionDebugToStderr(SMBCCTX *c);
599 /** Set whether to log to standard error instead of standard output */
601 smbc_setOptionDebugToStderr(SMBCCTX *c, smbc_bool b);
604 * Get whether to use new-style time attribute names, e.g. WRITE_TIME rather
605 * than the old-style names such as M_TIME. This allows also setting/getting
606 * CREATE_TIME which was previously unimplemented. (Note that the old C_TIME
607 * was supposed to be CHANGE_TIME but was confused and sometimes referred to
611 smbc_getOptionFullTimeNames(SMBCCTX *c);
614 * Set whether to use new-style time attribute names, e.g. WRITE_TIME rather
615 * than the old-style names such as M_TIME. This allows also setting/getting
616 * CREATE_TIME which was previously unimplemented. (Note that the old C_TIME
617 * was supposed to be CHANGE_TIME but was confused and sometimes referred to
621 smbc_setOptionFullTimeNames(SMBCCTX *c, smbc_bool b);
624 * Get the share mode to use for files opened with SMBC_open_ctx(). The
625 * default is SMBC_SHAREMODE_DENY_NONE.
628 smbc_getOptionOpenShareMode(SMBCCTX *c);
631 * Set the share mode to use for files opened with SMBC_open_ctx(). The
632 * default is SMBC_SHAREMODE_DENY_NONE.
635 smbc_setOptionOpenShareMode(SMBCCTX *c, smbc_share_mode share_mode);
637 /** Retrieve a previously saved user data handle */
639 smbc_getOptionUserData(SMBCCTX *c);
641 /** Save a user data handle */
643 smbc_setOptionUserData(SMBCCTX *c, void *user_data);
645 /** Get the encoded value for encryption level. */
646 smbc_smb_encrypt_level
647 smbc_getOptionSmbEncryptionLevel(SMBCCTX *c);
649 /** Set the encoded value for encryption level. */
651 smbc_setOptionSmbEncryptionLevel(SMBCCTX *c, smbc_smb_encrypt_level level);
654 * Get whether to treat file names as case-sensitive if we can't determine
655 * when connecting to the remote share whether the file system is case
656 * sensitive. This defaults to FALSE since it's most likely that if we can't
657 * retrieve the file system attributes, it's a very old file system that does
658 * not support case sensitivity.
661 smbc_getOptionCaseSensitive(SMBCCTX *c);
664 * Set whether to treat file names as case-sensitive if we can't determine
665 * when connecting to the remote share whether the file system is case
666 * sensitive. This defaults to FALSE since it's most likely that if we can't
667 * retrieve the file system attributes, it's a very old file system that does
668 * not support case sensitivity.
671 smbc_setOptionCaseSensitive(SMBCCTX *c, smbc_bool b);
675 * Get from how many local master browsers should the list of workgroups be
676 * retrieved. It can take up to 12 minutes or longer after a server becomes a
677 * local master browser, for it to have the entire browse list (the list of
678 * workgroups/domains) from an entire network. Since a client never knows
679 * which local master browser will be found first, the one which is found
680 * first and used to retrieve a browse list may have an incomplete or empty
681 * browse list. By requesting the browse list from multiple local master
682 * browsers, a more complete list can be generated. For small networks (few
683 * workgroups), it is recommended that this value be set to 0, causing the
684 * browse lists from all found local master browsers to be retrieved and
685 * merged. For networks with many workgroups, a suitable value for this
686 * variable is probably somewhere around 3. (Default: 3).
689 smbc_getOptionBrowseMaxLmbCount(SMBCCTX *c);
692 * Set from how many local master browsers should the list of workgroups be
693 * retrieved. It can take up to 12 minutes or longer after a server becomes a
694 * local master browser, for it to have the entire browse list (the list of
695 * workgroups/domains) from an entire network. Since a client never knows
696 * which local master browser will be found first, the one which is found
697 * first and used to retrieve a browse list may have an incomplete or empty
698 * browse list. By requesting the browse list from multiple local master
699 * browsers, a more complete list can be generated. For small networks (few
700 * workgroups), it is recommended that this value be set to 0, causing the
701 * browse lists from all found local master browsers to be retrieved and
702 * merged. For networks with many workgroups, a suitable value for this
703 * variable is probably somewhere around 3. (Default: 3).
706 smbc_setOptionBrowseMaxLmbCount(SMBCCTX *c, int count);
709 * Get whether to url-encode readdir entries.
711 * There is a difference in the desired return strings from
712 * smbc_readdir() depending upon whether the filenames are to
713 * be displayed to the user, or whether they are to be
714 * appended to the path name passed to smbc_opendir() to call
715 * a further smbc_ function (e.g. open the file with
716 * smbc_open()). In the former case, the filename should be
717 * in "human readable" form. In the latter case, the smbc_
718 * functions expect a URL which must be url-encoded. Those
719 * functions decode the URL. If, for example, smbc_readdir()
720 * returned a file name of "abc%20def.txt", passing a path
721 * with this file name attached to smbc_open() would cause
722 * smbc_open to attempt to open the file "abc def.txt" since
723 * the %20 is decoded into a space.
725 * Set this option to True if the names returned by
726 * smbc_readdir() should be url-encoded such that they can be
727 * passed back to another smbc_ call. Set it to False if the
728 * names returned by smbc_readdir() are to be presented to the
731 * For backwards compatibility, this option defaults to False.
734 smbc_getOptionUrlEncodeReaddirEntries(SMBCCTX *c);
737 * Set whether to url-encode readdir entries.
739 * There is a difference in the desired return strings from
740 * smbc_readdir() depending upon whether the filenames are to
741 * be displayed to the user, or whether they are to be
742 * appended to the path name passed to smbc_opendir() to call
743 * a further smbc_ function (e.g. open the file with
744 * smbc_open()). In the former case, the filename should be
745 * in "human readable" form. In the latter case, the smbc_
746 * functions expect a URL which must be url-encoded. Those
747 * functions decode the URL. If, for example, smbc_readdir()
748 * returned a file name of "abc%20def.txt", passing a path
749 * with this file name attached to smbc_open() would cause
750 * smbc_open to attempt to open the file "abc def.txt" since
751 * the %20 is decoded into a space.
753 * Set this option to True if the names returned by
754 * smbc_readdir() should be url-encoded such that they can be
755 * passed back to another smbc_ call. Set it to False if the
756 * names returned by smbc_readdir() are to be presented to the
759 * For backwards compatibility, this option defaults to False.
762 smbc_setOptionUrlEncodeReaddirEntries(SMBCCTX *c, smbc_bool b);
765 * Get whether to use the same connection for all shares on a server.
767 * Some Windows versions appear to have a limit to the number
768 * of concurrent SESSIONs and/or TREE CONNECTions. In
769 * one-shot programs (i.e. the program runs and then quickly
770 * ends, thereby shutting down all connections), it is
771 * probably reasonable to establish a new connection for each
772 * share. In long-running applications, the limitation can be
773 * avoided by using only a single connection to each server,
774 * and issuing a new TREE CONNECT when the share is accessed.
777 smbc_getOptionOneSharePerServer(SMBCCTX *c);
780 * Set whether to use the same connection for all shares on a server.
782 * Some Windows versions appear to have a limit to the number
783 * of concurrent SESSIONs and/or TREE CONNECTions. In
784 * one-shot programs (i.e. the program runs and then quickly
785 * ends, thereby shutting down all connections), it is
786 * probably reasonable to establish a new connection for each
787 * share. In long-running applications, the limitation can be
788 * avoided by using only a single connection to each server,
789 * and issuing a new TREE CONNECT when the share is accessed.
792 smbc_setOptionOneSharePerServer(SMBCCTX *c, smbc_bool b);
794 /** Get whether to enable use of kerberos */
796 smbc_getOptionUseKerberos(SMBCCTX *c);
798 /** Set whether to enable use of kerberos */
800 smbc_setOptionUseKerberos(SMBCCTX *c, smbc_bool b);
802 /** Get whether to fallback after kerberos */
804 smbc_getOptionFallbackAfterKerberos(SMBCCTX *c);
806 /** Set whether to fallback after kerberos */
808 smbc_setOptionFallbackAfterKerberos(SMBCCTX *c, smbc_bool b);
810 /** Get whether to automatically select anonymous login */
812 smbc_getOptionNoAutoAnonymousLogin(SMBCCTX *c);
814 /** Set whether to automatically select anonymous login */
816 smbc_setOptionNoAutoAnonymousLogin(SMBCCTX *c, smbc_bool b);
818 /** Get whether to enable use of the winbind ccache */
820 smbc_getOptionUseCCache(SMBCCTX *c);
822 /** Set whether to enable use of the winbind ccache */
824 smbc_setOptionUseCCache(SMBCCTX *c, smbc_bool b);
826 /** Get indication that the password supplied is the NT hash */
828 smbc_getOptionUseNTHash(SMBCCTX *c);
830 /** Set indication that the password supplied is the NT hash */
832 smbc_setOptionUseNTHash(SMBCCTX *c, smbc_bool b);
836 /*************************************
837 * Getters and setters for FUNCTIONS *
838 *************************************/
840 /** Get the function for obtaining authentication data */
841 smbc_get_auth_data_fn smbc_getFunctionAuthData(SMBCCTX *c);
843 /** Set the function for obtaining authentication data */
844 void smbc_setFunctionAuthData(SMBCCTX *c, smbc_get_auth_data_fn fn);
846 /** Get the new-style authentication function which includes the context. */
847 smbc_get_auth_data_with_context_fn
848 smbc_getFunctionAuthDataWithContext(SMBCCTX *c);
850 /** Set the new-style authentication function which includes the context. */
852 smbc_setFunctionAuthDataWithContext(SMBCCTX *c,
853 smbc_get_auth_data_with_context_fn fn);
855 /** Get the function for checking if a server is still good */
856 smbc_check_server_fn smbc_getFunctionCheckServer(SMBCCTX *c);
858 /** Set the function for checking if a server is still good */
859 void smbc_setFunctionCheckServer(SMBCCTX *c, smbc_check_server_fn fn);
861 /** Get the function for removing a server if unused */
862 smbc_remove_unused_server_fn smbc_getFunctionRemoveUnusedServer(SMBCCTX *c);
864 /** Set the function for removing a server if unused */
865 void smbc_setFunctionRemoveUnusedServer(SMBCCTX *c,
866 smbc_remove_unused_server_fn fn);
868 /** Get the function for adding a cached server */
869 smbc_add_cached_srv_fn smbc_getFunctionAddCachedServer(SMBCCTX *c);
871 /** Set the function for adding a cached server */
872 void smbc_setFunctionAddCachedServer(SMBCCTX *c, smbc_add_cached_srv_fn fn);
874 /** Get the function for server cache lookup */
875 smbc_get_cached_srv_fn smbc_getFunctionGetCachedServer(SMBCCTX *c);
877 /** Set the function for server cache lookup */
878 void smbc_setFunctionGetCachedServer(SMBCCTX *c, smbc_get_cached_srv_fn fn);
880 /** Get the function for server cache removal */
881 smbc_remove_cached_srv_fn smbc_getFunctionRemoveCachedServer(SMBCCTX *c);
883 /** Set the function for server cache removal */
884 void smbc_setFunctionRemoveCachedServer(SMBCCTX *c,
885 smbc_remove_cached_srv_fn fn);
888 * Get the function for server cache purging. This function tries to
889 * remove all cached servers (e.g. on disconnect)
891 smbc_purge_cached_fn smbc_getFunctionPurgeCachedServers(SMBCCTX *c);
894 * Set the function for server cache purging. This function tries to
895 * remove all cached servers (e.g. on disconnect)
897 void smbc_setFunctionPurgeCachedServers(SMBCCTX *c,
898 smbc_purge_cached_fn fn);
900 /** Get the function to store private data of the server cache */
901 struct smbc_server_cache * smbc_getServerCacheData(SMBCCTX *c);
903 /** Set the function to store private data of the server cache */
904 void smbc_setServerCacheData(SMBCCTX *c, struct smbc_server_cache * cache);
908 /*****************************************************************
909 * Callable functions for files. *
910 * Each callable has a function signature typedef, a declaration *
911 * for the getter, and a declaration for the setter. *
912 *****************************************************************/
914 typedef SMBCFILE * (*smbc_open_fn)(SMBCCTX *c,
918 smbc_open_fn smbc_getFunctionOpen(SMBCCTX *c);
919 void smbc_setFunctionOpen(SMBCCTX *c, smbc_open_fn fn);
921 typedef SMBCFILE * (*smbc_creat_fn)(SMBCCTX *c,
924 smbc_creat_fn smbc_getFunctionCreat(SMBCCTX *c);
925 void smbc_setFunctionCreat(SMBCCTX *c, smbc_creat_fn);
927 typedef ssize_t (*smbc_read_fn)(SMBCCTX *c,
931 smbc_read_fn smbc_getFunctionRead(SMBCCTX *c);
932 void smbc_setFunctionRead(SMBCCTX *c, smbc_read_fn fn);
934 typedef ssize_t (*smbc_write_fn)(SMBCCTX *c,
938 smbc_write_fn smbc_getFunctionWrite(SMBCCTX *c);
939 void smbc_setFunctionWrite(SMBCCTX *c, smbc_write_fn fn);
941 typedef off_t (*smbc_splice_fn)(SMBCCTX *c,
945 int (*splice_cb)(off_t n, void *priv),
947 smbc_splice_fn smbc_getFunctionSplice(SMBCCTX *c);
948 void smbc_setFunctionSplice(SMBCCTX *c, smbc_splice_fn fn);
950 typedef int (*smbc_unlink_fn)(SMBCCTX *c,
952 smbc_unlink_fn smbc_getFunctionUnlink(SMBCCTX *c);
953 void smbc_setFunctionUnlink(SMBCCTX *c, smbc_unlink_fn fn);
955 typedef int (*smbc_rename_fn)(SMBCCTX *ocontext,
959 smbc_rename_fn smbc_getFunctionRename(SMBCCTX *c);
960 void smbc_setFunctionRename(SMBCCTX *c, smbc_rename_fn fn);
962 typedef off_t (*smbc_lseek_fn)(SMBCCTX *c,
966 smbc_lseek_fn smbc_getFunctionLseek(SMBCCTX *c);
967 void smbc_setFunctionLseek(SMBCCTX *c, smbc_lseek_fn fn);
969 typedef int (*smbc_stat_fn)(SMBCCTX *c,
972 smbc_stat_fn smbc_getFunctionStat(SMBCCTX *c);
973 void smbc_setFunctionStat(SMBCCTX *c, smbc_stat_fn fn);
975 typedef int (*smbc_fstat_fn)(SMBCCTX *c,
978 smbc_fstat_fn smbc_getFunctionFstat(SMBCCTX *c);
979 void smbc_setFunctionFstat(SMBCCTX *c, smbc_fstat_fn fn);
981 typedef int (*smbc_statvfs_fn)(SMBCCTX *c,
984 smbc_statvfs_fn smbc_getFunctionStatVFS(SMBCCTX *c);
985 void smbc_setFunctionStatVFS(SMBCCTX *c, smbc_statvfs_fn fn);
987 typedef int (*smbc_fstatvfs_fn)(SMBCCTX *c,
990 smbc_fstatvfs_fn smbc_getFunctionFstatVFS(SMBCCTX *c);
991 void smbc_setFunctionFstatVFS(SMBCCTX *c, smbc_fstatvfs_fn fn);
993 typedef int (*smbc_ftruncate_fn)(SMBCCTX *c,
996 smbc_ftruncate_fn smbc_getFunctionFtruncate(SMBCCTX *c);
997 void smbc_setFunctionFtruncate(SMBCCTX *c, smbc_ftruncate_fn fn);
999 typedef int (*smbc_close_fn)(SMBCCTX *c,
1001 smbc_close_fn smbc_getFunctionClose(SMBCCTX *c);
1002 void smbc_setFunctionClose(SMBCCTX *c, smbc_close_fn fn);
1006 /*****************************************************************
1007 * Callable functions for directories. *
1008 * Each callable has a function signature typedef, a declaration *
1009 * for the getter, and a declaration for the setter. *
1010 *****************************************************************/
1012 typedef SMBCFILE * (*smbc_opendir_fn)(SMBCCTX *c,
1014 smbc_opendir_fn smbc_getFunctionOpendir(SMBCCTX *c);
1015 void smbc_setFunctionOpendir(SMBCCTX *c, smbc_opendir_fn fn);
1017 typedef int (*smbc_closedir_fn)(SMBCCTX *c,
1019 smbc_closedir_fn smbc_getFunctionClosedir(SMBCCTX *c);
1020 void smbc_setFunctionClosedir(SMBCCTX *c, smbc_closedir_fn fn);
1022 typedef struct smbc_dirent * (*smbc_readdir_fn)(SMBCCTX *c,
1024 smbc_readdir_fn smbc_getFunctionReaddir(SMBCCTX *c);
1025 void smbc_setFunctionReaddir(SMBCCTX *c, smbc_readdir_fn fn);
1027 typedef const struct libsmb_file_info * (*smbc_readdirplus_fn)(SMBCCTX *c,
1029 smbc_readdirplus_fn smbc_getFunctionReaddirPlus(SMBCCTX *c);
1030 void smbc_setFunctionReaddirPlus(SMBCCTX *c, smbc_readdirplus_fn fn);
1032 typedef int (*smbc_getdents_fn)(SMBCCTX *c,
1034 struct smbc_dirent *dirp,
1036 smbc_getdents_fn smbc_getFunctionGetdents(SMBCCTX *c);
1037 void smbc_setFunctionGetdents(SMBCCTX *c, smbc_getdents_fn fn);
1039 typedef int (*smbc_mkdir_fn)(SMBCCTX *c,
1042 smbc_mkdir_fn smbc_getFunctionMkdir(SMBCCTX *c);
1043 void smbc_setFunctionMkdir(SMBCCTX *c, smbc_mkdir_fn fn);
1045 typedef int (*smbc_rmdir_fn)(SMBCCTX *c,
1047 smbc_rmdir_fn smbc_getFunctionRmdir(SMBCCTX *c);
1048 void smbc_setFunctionRmdir(SMBCCTX *c, smbc_rmdir_fn fn);
1050 typedef off_t (*smbc_telldir_fn)(SMBCCTX *c,
1052 smbc_telldir_fn smbc_getFunctionTelldir(SMBCCTX *c);
1053 void smbc_setFunctionTelldir(SMBCCTX *c, smbc_telldir_fn fn);
1055 typedef int (*smbc_lseekdir_fn)(SMBCCTX *c,
1058 smbc_lseekdir_fn smbc_getFunctionLseekdir(SMBCCTX *c);
1059 void smbc_setFunctionLseekdir(SMBCCTX *c, smbc_lseekdir_fn fn);
1061 typedef int (*smbc_fstatdir_fn)(SMBCCTX *c,
1064 smbc_fstatdir_fn smbc_getFunctionFstatdir(SMBCCTX *c);
1065 void smbc_setFunctionFstatdir(SMBCCTX *c, smbc_fstatdir_fn fn);
1067 #define SMBC_NOTIFY_ACTION_ADDED 1
1068 #define SMBC_NOTIFY_ACTION_REMOVED 2
1069 #define SMBC_NOTIFY_ACTION_MODIFIED 3
1070 #define SMBC_NOTIFY_ACTION_OLD_NAME 4
1071 #define SMBC_NOTIFY_ACTION_NEW_NAME 5
1072 #define SMBC_NOTIFY_ACTION_ADDED_STREAM 6
1073 #define SMBC_NOTIFY_ACTION_REMOVED_STREAM 7
1074 #define SMBC_NOTIFY_ACTION_MODIFIED_STREAM 8
1076 struct smbc_notify_callback_action {
1078 const char *filename;
1081 typedef int (*smbc_notify_callback_fn)(
1082 const struct smbc_notify_callback_action *actions,
1083 size_t num_actions, void *private_data);
1085 typedef int (*smbc_notify_fn)(SMBCCTX *c, SMBCFILE *dir, smbc_bool recursive,
1086 uint32_t completion_filter,
1087 unsigned callback_timeout_ms,
1088 smbc_notify_callback_fn cb, void *private_data);
1089 smbc_notify_fn smbc_getFunctionNotify(SMBCCTX *c);
1090 void smbc_setFunctionNotify(SMBCCTX *c, smbc_notify_fn fn);
1093 /*****************************************************************
1094 * Callable functions applicable to both files and directories. *
1095 * Each callable has a function signature typedef, a declaration *
1096 * for the getter, and a declaration for the setter. *
1097 *****************************************************************/
1099 typedef int (*smbc_chmod_fn)(SMBCCTX *c,
1102 smbc_chmod_fn smbc_getFunctionChmod(SMBCCTX *c);
1103 void smbc_setFunctionChmod(SMBCCTX *c, smbc_chmod_fn fn);
1105 typedef int (*smbc_utimes_fn)(SMBCCTX *c,
1107 struct timeval *tbuf);
1108 smbc_utimes_fn smbc_getFunctionUtimes(SMBCCTX *c);
1109 void smbc_setFunctionUtimes(SMBCCTX *c, smbc_utimes_fn fn);
1111 typedef int (*smbc_setxattr_fn)(SMBCCTX *context,
1117 smbc_setxattr_fn smbc_getFunctionSetxattr(SMBCCTX *c);
1118 void smbc_setFunctionSetxattr(SMBCCTX *c, smbc_setxattr_fn fn);
1120 typedef int (*smbc_getxattr_fn)(SMBCCTX *context,
1125 smbc_getxattr_fn smbc_getFunctionGetxattr(SMBCCTX *c);
1126 void smbc_setFunctionGetxattr(SMBCCTX *c, smbc_getxattr_fn fn);
1128 typedef int (*smbc_removexattr_fn)(SMBCCTX *context,
1131 smbc_removexattr_fn smbc_getFunctionRemovexattr(SMBCCTX *c);
1132 void smbc_setFunctionRemovexattr(SMBCCTX *c, smbc_removexattr_fn fn);
1134 typedef int (*smbc_listxattr_fn)(SMBCCTX *context,
1138 smbc_listxattr_fn smbc_getFunctionListxattr(SMBCCTX *c);
1139 void smbc_setFunctionListxattr(SMBCCTX *c, smbc_listxattr_fn fn);
1143 /*****************************************************************
1144 * Callable functions for printing. *
1145 * Each callable has a function signature typedef, a declaration *
1146 * for the getter, and a declaration for the setter. *
1147 *****************************************************************/
1149 typedef int (*smbc_print_file_fn)(SMBCCTX *c_file,
1152 const char *printq);
1153 smbc_print_file_fn smbc_getFunctionPrintFile(SMBCCTX *c);
1154 void smbc_setFunctionPrintFile(SMBCCTX *c, smbc_print_file_fn fn);
1156 typedef SMBCFILE * (*smbc_open_print_job_fn)(SMBCCTX *c,
1158 smbc_open_print_job_fn smbc_getFunctionOpenPrintJob(SMBCCTX *c);
1159 void smbc_setFunctionOpenPrintJob(SMBCCTX *c,
1160 smbc_open_print_job_fn fn);
1162 typedef int (*smbc_list_print_jobs_fn)(SMBCCTX *c,
1164 smbc_list_print_job_fn fn);
1165 smbc_list_print_jobs_fn smbc_getFunctionListPrintJobs(SMBCCTX *c);
1166 void smbc_setFunctionListPrintJobs(SMBCCTX *c,
1167 smbc_list_print_jobs_fn fn);
1169 typedef int (*smbc_unlink_print_job_fn)(SMBCCTX *c,
1172 smbc_unlink_print_job_fn smbc_getFunctionUnlinkPrintJob(SMBCCTX *c);
1173 void smbc_setFunctionUnlinkPrintJob(SMBCCTX *c,
1174 smbc_unlink_print_job_fn fn);
1178 * Create a new SBMCCTX (a context).
1180 * Must be called before the context is passed to smbc_context_init()
1182 * @return The given SMBCCTX pointer on success, NULL on error with errno set:
1183 * - ENOMEM Out of memory
1185 * @see smbc_free_context(), smbc_init_context()
1187 * @note Do not forget to smbc_init_context() the returned SMBCCTX pointer !
1189 SMBCCTX * smbc_new_context(void);
1192 * Delete a SBMCCTX (a context) acquired from smbc_new_context().
1194 * The context will be deleted if possible.
1196 * @param context A pointer to a SMBCCTX obtained from smbc_new_context()
1198 * @param shutdown_ctx If 1, all connections and files will be closed even if they are busy.
1201 * @return Returns 0 on succes. Returns 1 on failure with errno set:
1202 * - EBUSY Server connections are still used, Files are open or cache
1203 * could not be purged
1204 * - EBADF context == NULL
1206 * @see smbc_new_context()
1208 * @note It is advised to clean up all the contexts with shutdown_ctx set to 1
1209 * just before exit()'ing. When shutdown_ctx is 0, this function can be
1210 * use in periodical cleanup functions for example.
1212 int smbc_free_context(SMBCCTX * context, int shutdown_ctx);
1217 * @deprecated. Use smbc_setOption*() functions instead.
1220 smbc_option_set(SMBCCTX *context,
1222 ... /* option_value */);
1225 * @deprecated. Use smbc_getOption*() functions instead.
1228 smbc_option_get(SMBCCTX *context,
1232 * Initialize a SBMCCTX (a context).
1234 * Must be called before using any SMBCCTX API function
1236 * @param context A pointer to a SMBCCTX obtained from smbc_new_context()
1238 * @return A pointer to the given SMBCCTX on success,
1239 * NULL on error with errno set:
1240 * - EBADF NULL context given
1241 * - ENOMEM Out of memory
1242 * - ENOENT The smb.conf file would not load
1244 * @see smbc_new_context()
1246 * @note my_context = smbc_init_context(smbc_new_context())
1247 * is perfectly safe, but it might leak memory on
1248 * smbc_context_init() failure. Avoid this.
1249 * You'll have to call smbc_free_context() yourself
1253 SMBCCTX * smbc_init_context(SMBCCTX * context);
1256 * Initialize the samba client library.
1258 * Must be called before using any of the smbclient API function
1260 * @param fn The function that will be called to obtaion
1261 * authentication credentials.
1263 * @param debug Allows caller to set the debug level. Can be
1264 * changed in smb.conf file. Allows caller to set
1265 * debugging if no smb.conf.
1267 * @return 0 on success, < 0 on error with errno set:
1268 * - ENOMEM Out of memory
1269 * - ENOENT The smb.conf file would not load
1273 int smbc_init(smbc_get_auth_data_fn fn, int debug);
1276 * Set or retrieve the compatibility library's context pointer
1278 * @param context New context to use, or NULL. If a new context is provided,
1279 * it must have allocated with smbc_new_context() and
1280 * initialized with smbc_init_context(), followed, optionally,
1281 * by some manual changes to some of the non-internal fields.
1283 * @return The old context.
1285 * @see smbc_new_context(), smbc_init_context(), smbc_init()
1287 * @note This function may be called prior to smbc_init() to force
1288 * use of the next context without any internal calls to
1289 * smbc_new_context() or smbc_init_context(). It may also
1290 * be called after smbc_init() has already called those two
1291 * functions, to replace the existing context with a new one.
1292 * Care should be taken, in this latter case, to ensure that
1293 * the server cache and any data allocated by the
1294 * authentication functions have been freed, if necessary.
1297 SMBCCTX * smbc_set_context(SMBCCTX * new_context);
1300 * Open a file on an SMB server.
1302 * @param furl The smb url of the file to be opened.
1304 * @param flags Is one of O_RDONLY, O_WRONLY or O_RDWR which
1305 * request opening the file read-only,write-only
1306 * or read/write. flags may also be bitwise-or'd with
1307 * one or more of the following:
1308 * O_CREAT - If the file does not exist it will be
1310 * O_EXCL - When used with O_CREAT, if the file
1311 * already exists it is an error and the open will
1313 * O_TRUNC - If the file already exists it will be
1315 * O_APPEND The file is opened in append mode
1317 * @param mode mode specifies the permissions to use if a new
1318 * file is created. It is modified by the
1319 * process's umask in the usual way: the permissions
1320 * of the created file are (mode & ~umask)
1322 * Not currently use, but there for future use.
1323 * We will map this to SYSTEM, HIDDEN, etc bits
1324 * that reverses the mapping that smbc_fstat does.
1326 * @return Valid file handle, < 0 on error with errno set:
1327 * - ENOMEM Out of memory
1328 * - EINVAL if an invalid parameter passed, like no
1329 * file, or smbc_init not called.
1330 * - EEXIST pathname already exists and O_CREAT and
1332 * - EISDIR pathname refers to a directory and
1333 * the access requested involved writing.
1334 * - EACCES The requested access to the file is not
1336 * - ENODEV The requested share does not exist
1337 * - ENOTDIR A file on the path is not a directory
1338 * - ENOENT A directory component in pathname does
1343 * @note This call uses an underlying routine that may create
1344 * a new connection to the server specified in the URL.
1345 * If the credentials supplied in the URL, or via the
1346 * auth_fn in the smbc_init call, fail, this call will
1347 * try again with an empty username and password. This
1348 * often gets mapped to the guest account on some machines.
1351 int smbc_open(const char *furl, int flags, mode_t mode);
1354 * Create a file on an SMB server.
1356 * Same as calling smbc_open() with flags = O_CREAT|O_WRONLY|O_TRUNC
1358 * @param furl The smb url of the file to be created
1360 * @param mode mode specifies the permissions to use if a new
1361 * file is created. It is modified by the
1362 * process's umask in the usual way: the permissions
1363 * of the created file are (mode & ~umask)
1365 * NOTE, the above is not true. We are dealing with
1366 * an SMB server, which has no concept of a umask!
1368 * @return Valid file handle, < 0 on error with errno set:
1369 * - ENOMEM Out of memory
1370 * - EINVAL if an invalid parameter passed, like no
1371 * file, or smbc_init not called.
1372 * - EEXIST pathname already exists and O_CREAT and
1374 * - EISDIR pathname refers to a directory and
1375 * the access requested involved writing.
1376 * - EACCES The requested access to the file is not
1378 * - ENOENT A directory component in pathname does
1380 * - ENODEV The requested share does not exist.
1385 int smbc_creat(const char *furl, mode_t mode);
1388 * Read from a file using an opened file handle.
1390 * @param fd Open file handle from smbc_open() or smbc_creat()
1392 * @param buf Pointer to buffer to receive read data
1394 * @param bufsize Size of buf in bytes
1396 * @return Number of bytes read;
1398 * < 0 on error, with errno set:
1399 * - EISDIR fd refers to a directory
1400 * - EBADF fd is not a valid file descriptor or
1401 * is not open for reading.
1402 * - EINVAL fd is attached to an object which is
1403 * unsuitable for reading, or no buffer passed or
1404 * smbc_init not called.
1406 * @see smbc_open(), smbc_write()
1409 ssize_t smbc_read(int fd, void *buf, size_t bufsize);
1413 * Write to a file using an opened file handle.
1415 * @param fd Open file handle from smbc_open() or smbc_creat()
1417 * @param buf Pointer to buffer to recieve read data
1419 * @param bufsize Size of buf in bytes
1421 * @return Number of bytes written, < 0 on error with errno set:
1422 * - EISDIR fd refers to a directory.
1423 * - EBADF fd is not a valid file descriptor or
1424 * is not open for reading.
1425 * - EINVAL fd is attached to an object which is
1426 * unsuitable for reading, or no buffer passed or
1427 * smbc_init not called.
1429 * @see smbc_open(), smbc_read()
1432 ssize_t smbc_write(int fd, const void *buf, size_t bufsize);
1436 * Seek to a specific location in a file.
1438 * @param fd Open file handle from smbc_open() or smbc_creat()
1440 * @param offset Offset in bytes from whence
1442 * @param whence A location in the file:
1443 * - SEEK_SET The offset is set to offset bytes from
1444 * the beginning of the file
1445 * - SEEK_CUR The offset is set to current location
1446 * plus offset bytes.
1447 * - SEEK_END The offset is set to the size of the
1448 * file plus offset bytes.
1450 * @return Upon successful completion, lseek returns the
1451 * resulting offset location as measured in bytes
1452 * from the beginning of the file. Otherwise, a value
1453 * of (off_t)-1 is returned and errno is set to
1454 * indicate the error:
1455 * - EBADF Fildes is not an open file descriptor.
1456 * - EINVAL Whence is not a proper value or smbc_init
1459 * @todo Are all the whence values really supported?
1461 * @todo Are errno values complete and correct?
1463 off_t smbc_lseek(int fd, off_t offset, int whence);
1467 * Close an open file handle.
1469 * @param fd The file handle to close
1471 * @return 0 on success, < 0 on error with errno set:
1472 * - EBADF fd isn't a valid open file descriptor
1473 * - EINVAL smbc_init() failed or has not been called
1475 * @see smbc_open(), smbc_creat()
1477 int smbc_close(int fd);
1480 /**@ingroup directory
1481 * Unlink (delete) a file or directory.
1483 * @param furl The smb url of the file to delete
1485 * @return 0 on success, < 0 on error with errno set:
1486 * - EACCES or EPERM Write access to the directory
1487 * containing pathname is not allowed or one
1488 * of the directories in pathname did not allow
1489 * search (execute) permission
1490 * - ENOENT A directory component in pathname does
1492 * - EINVAL NULL was passed in the file param or
1493 * smbc_init not called.
1494 * - EACCES You do not have access to the file
1495 * - ENOMEM Insufficient kernel memory was available
1497 * @see smbc_rmdir()s
1499 * @todo Are errno values complete and correct?
1501 int smbc_unlink(const char *furl);
1504 /**@ingroup directory
1505 * Rename or move a file or directory.
1507 * @param ourl The original smb url (source url) of file or
1508 * directory to be moved
1510 * @param nurl The new smb url (destination url) of the file
1511 * or directory after the move. Currently nurl must
1512 * be on the same share as ourl.
1514 * @return 0 on success, < 0 on error with errno set:
1515 * - EISDIR nurl is an existing directory, but ourl is
1517 * - EEXIST nurl is a non-empty directory,
1518 * i.e., contains entries other than "." and ".."
1519 * - EINVAL The new url contained a path prefix
1520 * of the old, or, more generally, an attempt was
1521 * made to make a directory a subdirectory of itself
1522 * or smbc_init not called.
1523 * - ENOTDIR A component used as a directory in ourl
1524 * or nurl path is not, in fact, a directory. Or,
1525 * ourl is a directory, and newpath exists but is not
1527 * - EACCES or EPERM Write access to the directory
1528 * containing ourl or nurl is not allowed for the
1529 * process's effective uid, or one of the
1530 * directories in ourl or nurl did not allow search
1531 * (execute) permission, or ourl was a directory
1532 * and did not allow write permission.
1533 * - ENOENT A directory component in ourl or nurl
1535 * - EXDEV Rename across shares not supported.
1536 * - ENOMEM Insufficient kernel memory was available.
1537 * - EEXIST The target file, nurl, already exists.
1540 * @todo Are we going to support copying when urls are not on the same
1541 * share? I say no... NOTE. I agree for the moment.
1544 int smbc_rename(const char *ourl, const char *nurl);
1547 /**@ingroup directory
1548 * Open a directory used to obtain directory entries.
1550 * @param durl The smb url of the directory to open
1552 * @return Valid directory handle. < 0 on error with errno set:
1553 * - EACCES Permission denied.
1554 * - EINVAL A NULL file/URL was passed, or the URL would
1555 * not parse, or was of incorrect form or smbc_init not
1557 * - ENOENT durl does not exist, or name is an
1558 * - ENOMEM Insufficient memory to complete the
1560 * - ENOTDIR name is not a directory.
1561 * - EPERM the workgroup could not be found.
1562 * - ENODEV the workgroup or server could not be found.
1564 * @see smbc_getdents(), smbc_readdir(), smbc_closedir()
1567 int smbc_opendir(const char *durl);
1570 /**@ingroup directory
1571 * Close a directory handle opened by smbc_opendir().
1573 * @param dh Directory handle to close
1575 * @return 0 on success, < 0 on error with errno set:
1576 * - EBADF dh is an invalid directory handle
1578 * @see smbc_opendir()
1580 int smbc_closedir(int dh);
1583 /**@ingroup directory
1584 * Get multiple directory entries.
1586 * smbc_getdents() reads as many dirent structures from the an open
1587 * directory handle into a specified memory area as will fit.
1589 * @param dh Valid directory as returned by smbc_opendir()
1591 * @param dirp pointer to buffer that will receive the directory
1594 * @param count The size of the dirp buffer in bytes
1596 * @returns If any dirents returned, return will indicate the
1597 * total size. If there were no more dirents available,
1598 * 0 is returned. < 0 indicates an error.
1599 * - EBADF Invalid directory handle
1600 * - EINVAL Result buffer is too small or smbc_init
1602 * - ENOENT No such directory.
1603 * @see , smbc_dirent, smbc_readdir(), smbc_open()
1605 * @todo Are errno values complete and correct?
1607 * @todo Add example code so people know how to parse buffers.
1609 int smbc_getdents(unsigned int dh, struct smbc_dirent *dirp, int count);
1612 /**@ingroup directory
1613 * Get a single directory entry.
1615 * @param dh Valid directory as returned by smbc_opendir()
1617 * @return A pointer to a smbc_dirent structure, or NULL if an
1618 * error occurs or end-of-directory is reached:
1619 * - EBADF Invalid directory handle
1620 * - EINVAL smbc_init() failed or has not been called
1622 * @see smbc_dirent, smbc_getdents(), smbc_open()
1624 struct smbc_dirent* smbc_readdir(unsigned int dh);
1626 /**@ingroup directory
1627 * Works similar as smbc_readdir but returns more information about file.
1629 * @param dh Valid directory as returned by smbc_opendir()
1631 * @return A const pointer to a libsmb_file_info structure,
1632 * or NULL if an error occurs or end-of-directory is reached:
1633 * - EBADF Invalid directory handle
1634 * - EINVAL smbc_init() failed or has not been called
1636 * @see smbc_open(), smbc_readdir()
1638 const struct libsmb_file_info *smbc_readdirplus(unsigned int dh);
1641 /**@ingroup directory
1642 * Get the current directory offset.
1644 * smbc_telldir() may be used in conjunction with smbc_readdir() and
1647 * @param dh Valid directory as returned by smbc_opendir()
1649 * @return The current location in the directory stream or -1
1650 * if an error occur. The current location is not
1651 * an offset. Becuase of the implementation, it is a
1652 * handle that allows the library to find the entry
1654 * - EBADF dh is not a valid directory handle
1655 * - EINVAL smbc_init() failed or has not been called
1656 * - ENOTDIR if dh is not a directory
1658 * @see smbc_readdir()
1661 off_t smbc_telldir(int dh);
1664 /**@ingroup directory
1665 * lseek on directories.
1667 * smbc_lseekdir() may be used in conjunction with smbc_readdir() and
1668 * smbc_telldir(). (rewind by smbc_lseekdir(fd, NULL))
1670 * @param fd Valid directory as returned by smbc_opendir()
1672 * @param offset The offset (as returned by smbc_telldir). Can be
1673 * NULL, in which case we will rewind
1675 * @return 0 on success, -1 on failure
1676 * - EBADF dh is not a valid directory handle
1677 * - ENOTDIR if dh is not a directory
1678 * - EINVAL offset did not refer to a valid dirent or
1679 * smbc_init not called.
1681 * @see smbc_telldir()
1684 * @todo In what does the reture and errno values mean?
1686 int smbc_lseekdir(int fd, off_t offset);
1688 /**@ingroup directory
1689 * Create a directory.
1691 * @param durl The url of the directory to create
1693 * @param mode Specifies the permissions to use. It is modified
1694 * by the process's umask in the usual way: the
1695 * permissions of the created file are (mode & ~umask).
1697 * @return 0 on success, < 0 on error with errno set:
1698 * - EEXIST directory url already exists
1699 * - EACCES The parent directory does not allow write
1700 * permission to the process, or one of the directories
1701 * - ENOENT A directory component in pathname does not
1703 * - EINVAL NULL durl passed or smbc_init not called.
1704 * - ENOMEM Insufficient memory was available.
1709 int smbc_mkdir(const char *durl, mode_t mode);
1712 /**@ingroup directory
1713 * Remove a directory.
1715 * @param durl The smb url of the directory to remove
1717 * @return 0 on success, < 0 on error with errno set:
1718 * - EACCES or EPERM Write access to the directory
1719 * containing pathname was not allowed.
1720 * - EINVAL durl is NULL or smbc_init not called.
1721 * - ENOENT A directory component in pathname does not
1723 * - ENOTEMPTY directory contains entries.
1724 * - ENOMEM Insufficient kernel memory was available.
1726 * @see smbc_mkdir(), smbc_unlink()
1728 * @todo Are errno values complete and correct?
1730 int smbc_rmdir(const char *durl);
1732 /**@ingroup directory
1733 * Request directory notifications
1735 * @param dh Valid directory as returned by smbc_opendir()
1737 * @param recursive Are changes in subdirectories wanted?
1739 * @param completion_filter Bitwise-or of the SMBC_NOTIFY_CHANGE_*
1740 * events that are interesting
1742 * @param callback_timeout_ms If set to non-zero, interval in milliseconds
1743 * that "cb" will be called with 0 actions.
1744 * This gives "cb" the chance to cancel the
1747 * @param cb Callback functions taking events. If "cb"
1748 * returns nonzero, smbc_notify will return.
1750 * @param private_data Pointer given to "cb"
1752 * @return 0 on success, -1 on error with errno set
1754 * @see smbc_opendir(), smbc_closedir()
1757 #define SMBC_NOTIFY_CHANGE_FILE_NAME 0x001
1758 #define SMBC_NOTIFY_CHANGE_DIR_NAME 0x002
1759 #define SMBC_NOTIFY_CHANGE_ATTRIBUTES 0x004
1760 #define SMBC_NOTIFY_CHANGE_SIZE 0x008
1761 #define SMBC_NOTIFY_CHANGE_LAST_WRITE 0x010
1762 #define SMBC_NOTIFY_CHANGE_LAST_ACCESS 0x020
1763 #define SMBC_NOTIFY_CHANGE_CREATION 0x040
1764 #define SMBC_NOTIFY_CHANGE_EA 0x080
1765 #define SMBC_NOTIFY_CHANGE_SECURITY 0x100
1766 #define SMBC_NOTIFY_CHANGE_STREAM_NAME 0x200
1767 #define SMBC_NOTIFY_CHANGE_STREAM_SIZE 0x400
1768 #define SMBC_NOTIFY_CHANGE_STREAM_WRITE 0x800
1770 int smbc_notify(int dh, smbc_bool recursive, uint32_t completion_filter,
1771 unsigned callback_timeout_ms,
1772 smbc_notify_callback_fn cb, void *private_data);
1774 /**@ingroup attribute
1775 * Get information about a file or directory.
1777 * @param url The smb url to get information for
1779 * @param st pointer to a buffer that will be filled with
1780 * standard Unix struct stat information.
1782 * @return 0 on success, < 0 on error with errno set:
1783 * - ENOENT A component of the path file_name does not
1785 * - EINVAL a NULL url was passed or smbc_init not called.
1786 * - EACCES Permission denied.
1787 * - ENOMEM Out of memory
1788 * - ENOTDIR The target dir, url, is not a directory.
1793 int smbc_stat(const char *url, struct stat *st);
1796 /**@ingroup attribute
1797 * Get file information via an file descriptor.
1799 * @param fd Open file handle from smbc_open() or smbc_creat()
1801 * @param st pointer to a buffer that will be filled with
1802 * standard Unix struct stat information.
1804 * @return 0 on success, < 0 on error with errno set:
1805 * - EBADF filedes is bad.
1806 * - EACCES Permission denied.
1807 * - EBADF fd is not a valid file descriptor
1808 * - EINVAL Problems occurred in the underlying routines
1809 * or smbc_init not called.
1810 * - ENOMEM Out of memory
1812 * @see smbc_stat(), Unix stat()
1815 int smbc_fstat(int fd, struct stat *st);
1818 /**@ingroup attribute
1819 * Get file system information for a specified path.
1821 * @param url The smb url to get information for
1823 * @param st pointer to a buffer that will be filled with
1824 * standard Unix struct statvfs information.
1826 * @return 0 on success, < 0 on error with errno set:
1827 * - EBADF filedes is bad.
1828 * - EACCES Permission denied.
1829 * - EBADF fd is not a valid file descriptor
1830 * - EINVAL Problems occurred in the underlying routines
1831 * or smbc_init not called.
1832 * - ENOMEM Out of memory
1834 * @see Unix fstatvfs()
1838 smbc_statvfs(char *url,
1839 struct statvfs *st);
1841 /**@ingroup attribute
1842 * Get file system information via an file descriptor.
1844 * @param fd Open file handle from smbc_open(), smbc_creat(),
1847 * @param st pointer to a buffer that will be filled with
1848 * standard Unix struct statvfs information.
1850 * @return 0 on success, < 0 on error with errno set:
1851 * - EBADF filedes is bad.
1852 * - EACCES Permission denied.
1853 * - EBADF fd is not a valid file descriptor
1854 * - EINVAL Problems occurred in the underlying routines
1855 * or smbc_init not called.
1856 * - ENOMEM Out of memory
1858 * @see Unix fstatvfs()
1862 smbc_fstatvfs(int fd,
1863 struct statvfs *st);
1866 /**@ingroup attribute
1867 * Truncate a file given a file descriptor
1869 * @param fd Open file handle from smbc_open() or smbc_creat()
1871 * @param size size to truncate the file to
1873 * @return 0 on success, < 0 on error with errno set:
1874 * - EBADF filedes is bad.
1875 * - EACCES Permission denied.
1876 * - EBADF fd is not a valid file descriptor
1877 * - EINVAL Problems occurred in the underlying routines
1878 * or smbc_init not called.
1879 * - ENOMEM Out of memory
1881 * @see , Unix ftruncate()
1884 int smbc_ftruncate(int fd, off_t size);
1887 /**@ingroup attribute
1888 * Change the permissions of a file.
1890 * @param url The smb url of the file or directory to change
1893 * @param mode The permissions to set:
1894 * - Put good explaination of permissions here!
1896 * @return 0 on success, < 0 on error with errno set:
1897 * - EPERM The effective UID does not match the owner
1898 * of the file, and is not zero
1899 * - ENOENT The file does not exist.
1900 * - ENOMEM Insufficient was available.
1901 * - ENOENT file or directory does not exist
1903 * @todo Actually implement this fuction?
1905 * @todo Are errno values complete and correct?
1907 int smbc_chmod(const char *url, mode_t mode);
1910 * @ingroup attribute
1911 * Change the last modification time on a file
1913 * @param url The smb url of the file or directory to change
1914 * the modification time of
1916 * @param tbuf An array of two timeval structures which contains,
1917 * respectively, the desired access and modification times.
1918 * NOTE: Only the tv_sec field off each timeval structure is
1919 * used. The tv_usec (microseconds) portion is ignored.
1921 * @return 0 on success, < 0 on error with errno set:
1922 * - EINVAL The client library is not properly initialized
1923 * - EPERM Permission was denied.
1926 int smbc_utimes(const char *url, struct timeval *tbuf);
1930 * @ingroup attribute
1931 * Change the last modification time on a file
1933 * @param url The smb url of the file or directory to change
1934 * the modification time of
1936 * @param utbuf A pointer to a utimebuf structure which contains the
1937 * desired access and modification times.
1939 * @return 0 on success, < 0 on error with errno set:
1940 * - EINVAL The client library is not properly initialized
1941 * - ENOMEM No memory was available for internal needs
1942 * - EPERM Permission was denied.
1945 int smbc_utime(const char *fname, struct utimbuf *utbuf);
1948 /**@ingroup attribute
1949 * Set extended attributes for a file. This is used for modifying a file's
1950 * security descriptor (i.e. owner, group, and access control list)
1952 * @param url The smb url of the file or directory to set extended
1955 * @param name The name of an attribute to be changed. Names are of
1956 * one of the following forms:
1958 * system.nt_sec_desc.<attribute name>
1959 * system.nt_sec_desc.*
1960 * system.nt_sec_desc.*+
1962 * where <attribute name> is one of:
1970 * acl+:<name or sid>
1972 * In the forms "system.nt_sec_desc.*" and
1973 * "system.nt_sec_desc.*+", the asterisk and plus signs are
1974 * literal, i.e. the string is provided exactly as shown, and
1975 * the value parameter should contain a complete security
1976 * descriptor with name:value pairs separated by tabs,
1977 * commas, or newlines (not spaces!).
1979 * The plus sign ('+') indicates that SIDs should be mapped
1980 * to names. Without the plus sign, SIDs are not mapped;
1981 * rather they are simply converted to a string format.
1983 * @param value The value to be assigned to the specified attribute name.
1984 * This buffer should contain only the attribute value if the
1985 * name was of the "system.nt_sec_desc.<attribute_name>"
1986 * form. If the name was of the "system.nt_sec_desc.*" form
1987 * then a complete security descriptor, with name:value pairs
1988 * separated by tabs, commas, or newlines (not spaces!),
1989 * should be provided in this value buffer. A complete
1990 * security descriptor will contain one or more entries
1991 * selected from the following:
1993 * REVISION:<revision number>
1994 * OWNER:<sid or name>
1995 * GROUP:<sid or name>
1996 * ACL:<sid or name>:<type>/<flags>/<mask>
1998 * The revision of the ACL specifies the internal Windows NT
1999 * ACL revision for the security descriptor. If not specified
2000 * it defaults to 1. Using values other than 1 may cause
2001 * strange behaviour.
2003 * The owner and group specify the owner and group sids for
2004 * the object. If the attribute name (either '*+' with a
2005 * complete security descriptor, or individual 'owner+' or
2006 * 'group+' attribute names) ended with a plus sign, the
2007 * specified name is resolved to a SID value, using the
2008 * server on which the file or directory resides. Otherwise,
2009 * the value should be provided in SID-printable format as
2010 * S-1-x-y-z, and is used directly. The <sid or name>
2011 * associated with the ACL: attribute should be provided
2014 * @param size The number of the bytes of data in the value buffer
2016 * @param flags A bit-wise OR of zero or more of the following:
2017 * SMBC_XATTR_FLAG_CREATE -
2018 * fail if the named attribute already exists
2019 * SMBC_XATTR_FLAG_REPLACE -
2020 * fail if the attribute does not already exist
2022 * If neither flag is specified, the specified attributes
2023 * will be added or replace existing attributes of the same
2024 * name, as necessary.
2026 * @return 0 on success, < 0 on error with errno set:
2027 * - EINVAL The client library is not properly initialized
2028 * or one of the parameters is not of a correct
2030 * - ENOMEM No memory was available for internal needs
2031 * - EEXIST If the attribute already exists and the flag
2032 * SMBC_XATTR_FLAG_CREAT was specified
2033 * - ENOATTR If the attribute does not exist and the flag
2034 * SMBC_XATTR_FLAG_REPLACE was specified
2035 * - EPERM Permission was denied.
2036 * - ENOTSUP The referenced file system does not support
2037 * extended attributes
2039 * @note Attribute names are compared in a case-insensitive
2040 * fashion. All of the following are equivalent, although
2041 * the all-lower-case name is the preferred format:
2042 * system.nt_sec_desc.owner
2043 * SYSTEM.NT_SEC_DESC.OWNER
2044 * sYsTeM.nt_sEc_desc.owNER
2047 int smbc_setxattr(const char *url,
2054 /**@ingroup attribute
2055 * Set extended attributes for a file. This is used for modifying a file's
2056 * security descriptor (i.e. owner, group, and access control list). The
2057 * POSIX function which this maps to would act on a symbolic link rather than
2058 * acting on what the symbolic link points to, but with no symbolic links in
2059 * SMB file systems, this function is functionally identical to
2062 * @param url The smb url of the file or directory to set extended
2065 * @param name The name of an attribute to be changed. Names are of
2066 * one of the following forms:
2068 * system.nt_sec_desc.<attribute name>
2069 * system.nt_sec_desc.*
2070 * system.nt_sec_desc.*+
2072 * where <attribute name> is one of:
2080 * acl+:<name or sid>
2082 * In the forms "system.nt_sec_desc.*" and
2083 * "system.nt_sec_desc.*+", the asterisk and plus signs are
2084 * literal, i.e. the string is provided exactly as shown, and
2085 * the value parameter should contain a complete security
2086 * descriptor with name:value pairs separated by tabs,
2087 * commas, or newlines (not spaces!).
2089 * The plus sign ('+') indicates that SIDs should be mapped
2090 * to names. Without the plus sign, SIDs are not mapped;
2091 * rather they are simply converted to a string format.
2093 * @param value The value to be assigned to the specified attribute name.
2094 * This buffer should contain only the attribute value if the
2095 * name was of the "system.nt_sec_desc.<attribute_name>"
2096 * form. If the name was of the "system.nt_sec_desc.*" form
2097 * then a complete security descriptor, with name:value pairs
2098 * separated by tabs, commas, or newlines (not spaces!),
2099 * should be provided in this value buffer. A complete
2100 * security descriptor will contain one or more entries
2101 * selected from the following:
2103 * REVISION:<revision number>
2104 * OWNER:<sid or name>
2105 * GROUP:<sid or name>
2106 * ACL:<sid or name>:<type>/<flags>/<mask>
2108 * The revision of the ACL specifies the internal Windows NT
2109 * ACL revision for the security descriptor. If not specified
2110 * it defaults to 1. Using values other than 1 may cause
2111 * strange behaviour.
2113 * The owner and group specify the owner and group sids for
2114 * the object. If the attribute name (either '*+' with a
2115 * complete security descriptor, or individual 'owner+' or
2116 * 'group+' attribute names) ended with a plus sign, the
2117 * specified name is resolved to a SID value, using the
2118 * server on which the file or directory resides. Otherwise,
2119 * the value should be provided in SID-printable format as
2120 * S-1-x-y-z, and is used directly. The <sid or name>
2121 * associated with the ACL: attribute should be provided
2124 * @param size The number of the bytes of data in the value buffer
2126 * @param flags A bit-wise OR of zero or more of the following:
2127 * SMBC_XATTR_FLAG_CREATE -
2128 * fail if the named attribute already exists
2129 * SMBC_XATTR_FLAG_REPLACE -
2130 * fail if the attribute does not already exist
2132 * If neither flag is specified, the specified attributes
2133 * will be added or replace existing attributes of the same
2134 * name, as necessary.
2136 * @return 0 on success, < 0 on error with errno set:
2137 * - EINVAL The client library is not properly initialized
2138 * or one of the parameters is not of a correct
2140 * - ENOMEM No memory was available for internal needs
2141 * - EEXIST If the attribute already exists and the flag
2142 * SMBC_XATTR_FLAG_CREAT was specified
2143 * - ENOATTR If the attribute does not exist and the flag
2144 * SMBC_XATTR_FLAG_REPLACE was specified
2145 * - EPERM Permission was denied.
2146 * - ENOTSUP The referenced file system does not support
2147 * extended attributes
2149 * @note Attribute names are compared in a case-insensitive
2150 * fashion. All of the following are equivalent, although
2151 * the all-lower-case name is the preferred format:
2152 * system.nt_sec_desc.owner
2153 * SYSTEM.NT_SEC_DESC.OWNER
2154 * sYsTeM.nt_sEc_desc.owNER
2157 int smbc_lsetxattr(const char *url,
2164 /**@ingroup attribute
2165 * Set extended attributes for a file. This is used for modifying a file's
2166 * security descriptor (i.e. owner, group, and access control list)
2168 * @param fd A file descriptor associated with an open file (as
2169 * previously returned by smbc_open(), to get extended
2172 * @param name The name of an attribute to be changed. Names are of
2173 * one of the following forms:
2175 * system.nt_sec_desc.<attribute name>
2176 * system.nt_sec_desc.*
2177 * system.nt_sec_desc.*+
2179 * where <attribute name> is one of:
2187 * acl+:<name or sid>
2189 * In the forms "system.nt_sec_desc.*" and
2190 * "system.nt_sec_desc.*+", the asterisk and plus signs are
2191 * literal, i.e. the string is provided exactly as shown, and
2192 * the value parameter should contain a complete security
2193 * descriptor with name:value pairs separated by tabs,
2194 * commas, or newlines (not spaces!).
2196 * The plus sign ('+') indicates that SIDs should be mapped
2197 * to names. Without the plus sign, SIDs are not mapped;
2198 * rather they are simply converted to a string format.
2200 * @param value The value to be assigned to the specified attribute name.
2201 * This buffer should contain only the attribute value if the
2202 * name was of the "system.nt_sec_desc.<attribute_name>"
2203 * form. If the name was of the "system.nt_sec_desc.*" form
2204 * then a complete security descriptor, with name:value pairs
2205 * separated by tabs, commas, or newlines (not spaces!),
2206 * should be provided in this value buffer. A complete
2207 * security descriptor will contain one or more entries
2208 * selected from the following:
2210 * REVISION:<revision number>
2211 * OWNER:<sid or name>
2212 * GROUP:<sid or name>
2213 * ACL:<sid or name>:<type>/<flags>/<mask>
2215 * The revision of the ACL specifies the internal Windows NT
2216 * ACL revision for the security descriptor. If not specified
2217 * it defaults to 1. Using values other than 1 may cause
2218 * strange behaviour.
2220 * The owner and group specify the owner and group sids for
2221 * the object. If the attribute name (either '*+' with a
2222 * complete security descriptor, or individual 'owner+' or
2223 * 'group+' attribute names) ended with a plus sign, the
2224 * specified name is resolved to a SID value, using the
2225 * server on which the file or directory resides. Otherwise,
2226 * the value should be provided in SID-printable format as
2227 * S-1-x-y-z, and is used directly. The <sid or name>
2228 * associated with the ACL: attribute should be provided
2231 * @param size The number of the bytes of data in the value buffer
2233 * @param flags A bit-wise OR of zero or more of the following:
2234 * SMBC_XATTR_FLAG_CREATE -
2235 * fail if the named attribute already exists
2236 * SMBC_XATTR_FLAG_REPLACE -
2237 * fail if the attribute does not already exist
2239 * If neither flag is specified, the specified attributes
2240 * will be added or replace existing attributes of the same
2241 * name, as necessary.
2243 * @return 0 on success, < 0 on error with errno set:
2244 * - EINVAL The client library is not properly initialized
2245 * or one of the parameters is not of a correct
2247 * - ENOMEM No memory was available for internal needs
2248 * - EEXIST If the attribute already exists and the flag
2249 * SMBC_XATTR_FLAG_CREAT was specified
2250 * - ENOATTR If the attribute does not exist and the flag
2251 * SMBC_XATTR_FLAG_REPLACE was specified
2252 * - EPERM Permission was denied.
2253 * - ENOTSUP The referenced file system does not support
2254 * extended attributes
2256 * @note Attribute names are compared in a case-insensitive
2257 * fashion. All of the following are equivalent, although
2258 * the all-lower-case name is the preferred format:
2259 * system.nt_sec_desc.owner
2260 * SYSTEM.NT_SEC_DESC.OWNER
2261 * sYsTeM.nt_sEc_desc.owNER
2264 int smbc_fsetxattr(int fd,
2271 /**@ingroup attribute
2272 * Get extended attributes for a file.
2274 * @param url The smb url of the file or directory to get extended
2277 * @param name The name of an attribute to be retrieved. Names are of
2278 * one of the following forms:
2280 * system.nt_sec_desc.<attribute name>
2281 * system.nt_sec_desc.*
2282 * system.nt_sec_desc.*+
2284 * where <attribute name> is one of:
2292 * acl+:<name or sid>
2294 * In the forms "system.nt_sec_desc.*" and
2295 * "system.nt_sec_desc.*+", the asterisk and plus signs are
2296 * literal, i.e. the string is provided exactly as shown, and
2297 * the value parameter will return a complete security
2298 * descriptor with name:value pairs separated by tabs,
2299 * commas, or newlines (not spaces!).
2301 * The plus sign ('+') indicates that SIDs should be mapped
2302 * to names. Without the plus sign, SIDs are not mapped;
2303 * rather they are simply converted to a string format.
2305 * @param value A pointer to a buffer in which the value of the specified
2306 * attribute will be placed (unless size is zero).
2308 * @param size The size of the buffer pointed to by value. This parameter
2309 * may also be zero, in which case the size of the buffer
2310 * required to hold the attribute value will be returned,
2311 * but nothing will be placed into the value buffer.
2313 * @return 0 on success, < 0 on error with errno set:
2314 * - EINVAL The client library is not properly initialized
2315 * or one of the parameters is not of a correct
2317 * - ENOMEM No memory was available for internal needs
2318 * - EEXIST If the attribute already exists and the flag
2319 * SMBC_XATTR_FLAG_CREAT was specified
2320 * - ENOATTR If the attribute does not exist and the flag
2321 * SMBC_XATTR_FLAG_REPLACE was specified
2322 * - EPERM Permission was denied.
2323 * - ENOTSUP The referenced file system does not support
2324 * extended attributes
2327 int smbc_getxattr(const char *url,
2333 /**@ingroup attribute
2334 * Get extended attributes for a file. The POSIX function which this maps to
2335 * would act on a symbolic link rather than acting on what the symbolic link
2336 * points to, but with no symbolic links in SMB file systems, this function
2337 * is functionally identical to smbc_getxattr().
2339 * @param url The smb url of the file or directory to get extended
2342 * @param name The name of an attribute to be retrieved. Names are of
2343 * one of the following forms:
2345 * system.nt_sec_desc.<attribute name>
2346 * system.nt_sec_desc.*
2347 * system.nt_sec_desc.*+
2349 * where <attribute name> is one of:
2357 * acl+:<name or sid>
2359 * In the forms "system.nt_sec_desc.*" and
2360 * "system.nt_sec_desc.*+", the asterisk and plus signs are
2361 * literal, i.e. the string is provided exactly as shown, and
2362 * the value parameter will return a complete security
2363 * descriptor with name:value pairs separated by tabs,
2364 * commas, or newlines (not spaces!).
2366 * The plus sign ('+') indicates that SIDs should be mapped
2367 * to names. Without the plus sign, SIDs are not mapped;
2368 * rather they are simply converted to a string format.
2370 * @param value A pointer to a buffer in which the value of the specified
2371 * attribute will be placed (unless size is zero).
2373 * @param size The size of the buffer pointed to by value. This parameter
2374 * may also be zero, in which case the size of the buffer
2375 * required to hold the attribute value will be returned,
2376 * but nothing will be placed into the value buffer.
2378 * @return 0 on success, < 0 on error with errno set:
2379 * - EINVAL The client library is not properly initialized
2380 * or one of the parameters is not of a correct
2382 * - ENOMEM No memory was available for internal needs
2383 * - EEXIST If the attribute already exists and the flag
2384 * SMBC_XATTR_FLAG_CREAT was specified
2385 * - ENOATTR If the attribute does not exist and the flag
2386 * SMBC_XATTR_FLAG_REPLACE was specified
2387 * - EPERM Permission was denied.
2388 * - ENOTSUP The referenced file system does not support
2389 * extended attributes
2392 int smbc_lgetxattr(const char *url,
2398 /**@ingroup attribute
2399 * Get extended attributes for a file.
2401 * @param fd A file descriptor associated with an open file (as
2402 * previously returned by smbc_open(), to get extended
2405 * @param name The name of an attribute to be retrieved. Names are of
2406 * one of the following forms:
2408 * system.nt_sec_desc.<attribute name>
2409 * system.nt_sec_desc.*
2410 * system.nt_sec_desc.*+
2412 * where <attribute name> is one of:
2420 * acl+:<name or sid>
2422 * In the forms "system.nt_sec_desc.*" and
2423 * "system.nt_sec_desc.*+", the asterisk and plus signs are
2424 * literal, i.e. the string is provided exactly as shown, and
2425 * the value parameter will return a complete security
2426 * descriptor with name:value pairs separated by tabs,
2427 * commas, or newlines (not spaces!).
2429 * The plus sign ('+') indicates that SIDs should be mapped
2430 * to names. Without the plus sign, SIDs are not mapped;
2431 * rather they are simply converted to a string format.
2433 * @param value A pointer to a buffer in which the value of the specified
2434 * attribute will be placed (unless size is zero).
2436 * @param size The size of the buffer pointed to by value. This parameter
2437 * may also be zero, in which case the size of the buffer
2438 * required to hold the attribute value will be returned,
2439 * but nothing will be placed into the value buffer.
2441 * @return 0 on success, < 0 on error with errno set:
2442 * - EINVAL The client library is not properly initialized
2443 * or one of the parameters is not of a correct
2445 * - ENOMEM No memory was available for internal needs
2446 * - EEXIST If the attribute already exists and the flag
2447 * SMBC_XATTR_FLAG_CREAT was specified
2448 * - ENOATTR If the attribute does not exist and the flag
2449 * SMBC_XATTR_FLAG_REPLACE was specified
2450 * - EPERM Permission was denied.
2451 * - ENOTSUP The referenced file system does not support
2452 * extended attributes
2455 int smbc_fgetxattr(int fd,
2461 /**@ingroup attribute
2462 * Remove extended attributes for a file. This is used for modifying a file's
2463 * security descriptor (i.e. owner, group, and access control list)
2465 * @param url The smb url of the file or directory to remove the extended
2468 * @param name The name of an attribute to be removed. Names are of
2469 * one of the following forms:
2471 * system.nt_sec_desc.<attribute name>
2472 * system.nt_sec_desc.*
2473 * system.nt_sec_desc.*+
2475 * where <attribute name> is one of:
2483 * acl+:<name or sid>
2485 * In the forms "system.nt_sec_desc.*" and
2486 * "system.nt_sec_desc.*+", the asterisk and plus signs are
2487 * literal, i.e. the string is provided exactly as shown, and
2488 * the value parameter will return a complete security
2489 * descriptor with name:value pairs separated by tabs,
2490 * commas, or newlines (not spaces!).
2492 * The plus sign ('+') indicates that SIDs should be mapped
2493 * to names. Without the plus sign, SIDs are not mapped;
2494 * rather they are simply converted to a string format.
2496 * @return 0 on success, < 0 on error with errno set:
2497 * - EINVAL The client library is not properly initialized
2498 * - ENOMEM No memory was available for internal needs
2499 * - EPERM Permission was denied.
2500 * - ENOTSUP The referenced file system does not support
2501 * extended attributes
2504 int smbc_removexattr(const char *url,
2508 /**@ingroup attribute
2509 * Remove extended attributes for a file. This is used for modifying a file's
2510 * security descriptor (i.e. owner, group, and access control list) The POSIX
2511 * function which this maps to would act on a symbolic link rather than acting
2512 * on what the symbolic link points to, but with no symbolic links in SMB file
2513 * systems, this function is functionally identical to smbc_removexattr().
2515 * @param url The smb url of the file or directory to remove the extended
2518 * @param name The name of an attribute to be removed. Names are of
2519 * one of the following forms:
2521 * system.nt_sec_desc.<attribute name>
2522 * system.nt_sec_desc.*
2523 * system.nt_sec_desc.*+
2525 * where <attribute name> is one of:
2533 * acl+:<name or sid>
2535 * In the forms "system.nt_sec_desc.*" and
2536 * "system.nt_sec_desc.*+", the asterisk and plus signs are
2537 * literal, i.e. the string is provided exactly as shown, and
2538 * the value parameter will return a complete security
2539 * descriptor with name:value pairs separated by tabs,
2540 * commas, or newlines (not spaces!).
2542 * The plus sign ('+') indicates that SIDs should be mapped
2543 * to names. Without the plus sign, SIDs are not mapped;
2544 * rather they are simply converted to a string format.
2546 * @return 0 on success, < 0 on error with errno set:
2547 * - EINVAL The client library is not properly initialized
2548 * - ENOMEM No memory was available for internal needs
2549 * - EPERM Permission was denied.
2550 * - ENOTSUP The referenced file system does not support
2551 * extended attributes
2554 int smbc_lremovexattr(const char *url,
2558 /**@ingroup attribute
2559 * Remove extended attributes for a file. This is used for modifying a file's
2560 * security descriptor (i.e. owner, group, and access control list)
2562 * @param fd A file descriptor associated with an open file (as
2563 * previously returned by smbc_open(), to get extended
2566 * @param name The name of an attribute to be removed. Names are of
2567 * one of the following forms:
2569 * system.nt_sec_desc.<attribute name>
2570 * system.nt_sec_desc.*
2571 * system.nt_sec_desc.*+
2573 * where <attribute name> is one of:
2581 * acl+:<name or sid>
2583 * In the forms "system.nt_sec_desc.*" and
2584 * "system.nt_sec_desc.*+", the asterisk and plus signs are
2585 * literal, i.e. the string is provided exactly as shown, and
2586 * the value parameter will return a complete security
2587 * descriptor with name:value pairs separated by tabs,
2588 * commas, or newlines (not spaces!).
2590 * The plus sign ('+') indicates that SIDs should be mapped
2591 * to names. Without the plus sign, SIDs are not mapped;
2592 * rather they are simply converted to a string format.
2594 * @return 0 on success, < 0 on error with errno set:
2595 * - EINVAL The client library is not properly initialized
2596 * - ENOMEM No memory was available for internal needs
2597 * - EPERM Permission was denied.
2598 * - ENOTSUP The referenced file system does not support
2599 * extended attributes
2602 int smbc_fremovexattr(int fd,
2606 /**@ingroup attribute
2607 * List the supported extended attribute names associated with a file
2609 * @param url The smb url of the file or directory to list the extended
2612 * @param list A pointer to a buffer in which the list of attributes for
2613 * the specified file or directory will be placed (unless
2616 * @param size The size of the buffer pointed to by list. This parameter
2617 * may also be zero, in which case the size of the buffer
2618 * required to hold all of the attribute names will be
2619 * returned, but nothing will be placed into the list buffer.
2621 * @return 0 on success, < 0 on error with errno set:
2622 * - EINVAL The client library is not properly initialized
2623 * - ENOMEM No memory was available for internal needs
2624 * - EPERM Permission was denied.
2625 * - ENOTSUP The referenced file system does not support
2626 * extended attributes
2628 * @note This function always returns all attribute names supported
2629 * by NT file systems, regardless of whether the referenced
2630 * file system supports extended attributes (e.g. a Windows
2631 * 2000 machine supports extended attributes if NTFS is used,
2632 * but not if FAT is used, and Windows 98 doesn't support
2633 * extended attributes at all. Whether this is a feature or
2634 * a bug is yet to be decided.
2636 int smbc_listxattr(const char *url,
2640 /**@ingroup attribute
2641 * List the supported extended attribute names associated with a file The
2642 * POSIX function which this maps to would act on a symbolic link rather than
2643 * acting on what the symbolic link points to, but with no symbolic links in
2644 * SMB file systems, this function is functionally identical to
2647 * @param url The smb url of the file or directory to list the extended
2650 * @param list A pointer to a buffer in which the list of attributes for
2651 * the specified file or directory will be placed (unless
2654 * @param size The size of the buffer pointed to by list. This parameter
2655 * may also be zero, in which case the size of the buffer
2656 * required to hold all of the attribute names will be
2657 * returned, but nothing will be placed into the list buffer.
2659 * @return 0 on success, < 0 on error with errno set:
2660 * - EINVAL The client library is not properly initialized
2661 * - ENOMEM No memory was available for internal needs
2662 * - EPERM Permission was denied.
2663 * - ENOTSUP The referenced file system does not support
2664 * extended attributes
2666 * @note This function always returns all attribute names supported
2667 * by NT file systems, regardless of wether the referenced
2668 * file system supports extended attributes (e.g. a Windows
2669 * 2000 machine supports extended attributes if NTFS is used,
2670 * but not if FAT is used, and Windows 98 doesn't support
2671 * extended attributes at all. Whether this is a feature or
2672 * a bug is yet to be decided.
2674 int smbc_llistxattr(const char *url,
2678 /**@ingroup attribute
2679 * List the supported extended attribute names associated with a file
2681 * @param fd A file descriptor associated with an open file (as
2682 * previously returned by smbc_open(), to get extended
2685 * @param list A pointer to a buffer in which the list of attributes for
2686 * the specified file or directory will be placed (unless
2689 * @param size The size of the buffer pointed to by list. This parameter
2690 * may also be zero, in which case the size of the buffer
2691 * required to hold all of the attribute names will be
2692 * returned, but nothing will be placed into the list buffer.
2694 * @return 0 on success, < 0 on error with errno set:
2695 * - EINVAL The client library is not properly initialized
2696 * - ENOMEM No memory was available for internal needs
2697 * - EPERM Permission was denied.
2698 * - ENOTSUP The referenced file system does not support
2699 * extended attributes
2701 * @note This function always returns all attribute names supported
2702 * by NT file systems, regardless of wether the referenced
2703 * file system supports extended attributes (e.g. a Windows
2704 * 2000 machine supports extended attributes if NTFS is used,
2705 * but not if FAT is used, and Windows 98 doesn't support
2706 * extended attributes at all. Whether this is a feature or
2707 * a bug is yet to be decided.
2709 int smbc_flistxattr(int fd,
2714 * Print a file given the name in fname. It would be a URL ...
2716 * @param fname The URL of a file on a remote SMB server that the
2717 * caller wants printed
2719 * @param printq The URL of the print share to print the file to.
2721 * @return 0 on success, < 0 on error with errno set:
2723 * - EINVAL fname or printq was NULL or smbc_init not
2725 * and errors returned by smbc_open
2728 int smbc_print_file(const char *fname, const char *printq);
2731 * Open a print file that can be written to by other calls. This simply
2732 * does an smbc_open call after checking if there is a file name on the
2733 * URI. If not, a temporary name is added ...
2735 * @param fname The URL of the print share to print to?
2737 * @returns A file handle for the print file if successful.
2738 * Returns -1 if an error ocurred and errno has the values
2739 * - EINVAL fname was NULL or smbc_init not called.
2740 * - all errors returned by smbc_open
2743 int smbc_open_print_job(const char *fname);
2746 * List the print jobs on a print share, for the moment, pass a callback
2748 * @param purl The url of the print share to list the jobs of
2750 * @param fn Callback function the receives printjob info
2752 * @return 0 on success, < 0 on error with errno set:
2753 * - EINVAL fname was NULL or smbc_init not called
2756 int smbc_list_print_jobs(const char *purl, smbc_list_print_job_fn fn);
2759 * Delete a print job
2761 * @param purl Url of the print share
2763 * @param id The id of the job to delete
2765 * @return 0 on success, < 0 on error with errno set:
2766 * - EINVAL fname was NULL or smbc_init not called
2768 * @todo what errno values are possible here?
2770 int smbc_unlink_print_job(const char *purl, int id);
2772 /**@ingroup callback
2773 * Remove a server from the cached server list it's unused.
2775 * @param context pointer to smb context
2777 * @param srv pointer to server to remove
2779 * @return On success, 0 is returned. 1 is returned if the server could not
2780 * be removed. Also useable outside libsmbclient.
2782 int smbc_remove_unused_server(SMBCCTX * context, SMBCSRV * srv);
2788 /**@ingroup directory
2789 * Convert strings of %xx to their single character equivalent.
2791 * @param dest A pointer to a buffer in which the resulting decoded
2792 * string should be placed. This may be a pointer to the
2793 * same buffer as src_segment.
2795 * @param src A pointer to the buffer containing the URL to be decoded.
2796 * Any %xx sequences herein are converted to their single
2797 * character equivalent. Each 'x' must be a valid hexadecimal
2798 * digit, or that % sequence is left undecoded.
2800 * @param max_dest_len
2801 * The size of the buffer pointed to by dest_segment.
2803 * @return The number of % sequences which could not be converted
2804 * due to lack of two following hexadecimal digits.
2810 smbc_urldecode(char *dest, char * src, size_t max_dest_len);
2817 * Convert any characters not specifically allowed in a URL into their %xx
2820 * @param dest A pointer to a buffer in which the resulting encoded
2821 * string should be placed. Unlike smbc_urldecode(), this
2822 * must be a buffer unique from src.
2824 * @param src A pointer to the buffer containing the string to be encoded.
2825 * Any character not specifically allowed in a URL is converted
2826 * into its hexadecimal value and encoded as %xx.
2828 * @param max_dest_len
2829 * The size of the buffer pointed to by dest_segment.
2831 * @returns The remaining buffer length.
2837 smbc_urlencode(char * dest, char * src, int max_dest_len);
2843 /**@ingroup directory
2844 * Return the version of the linked Samba code, and thus the version of the
2845 * libsmbclient code.
2847 * @return The version string.
2859 * Set the users credentials globally so they can be used for DFS
2860 * referrals. Probably best to use this function in the smbc_get_auth_data_fn
2863 * @param workgroup Workgroup of the user.
2865 * @param user Username of user.
2867 * @param password Password of user.
2869 * @param use_kerberos Whether to use Kerberos
2871 * @param signing_state One of these strings (all equivalents on same line):
2872 * "off", "no", "false"
2873 * "on", "yes", "true", "auto"
2874 * "force", "required", "forced"
2878 smbc_set_credentials(const char *workgroup,
2880 const char *password,
2881 smbc_bool use_kerberos,
2882 const char *signing_state);
2885 * Wrapper around smbc_set_credentials.
2886 * Used to set correct credentials that will
2887 * be used to connect to DFS target share
2892 smbc_set_credentials_with_fallback(SMBCCTX *ctx,
2893 const char *workgroup,
2895 const char *password);
2901 * Initialize for threads using the Posix Threads (pthread)
2902 * implementation. This is a built-in implementation, avoiding the need to
2903 * implement the component functions of the thread interface. If this function
2904 * is used, it is not necessary to call smbc_thread_impl().
2909 smbc_thread_posix(void);
2914 * Initialize for an arbitrary thread implementation. The caller should
2915 * provide, as parameters, pointers to functions to implement the requisite
2916 * low-level thread functionality. A function must be provided for each
2917 * parameter; none may be null.
2919 * If the thread implementation is POSIX Threads (pthreads), then the much
2920 * simpler smbc_thread_pthread() function may be used instead of this one.
2922 * @param create_mutex
2923 * Create a mutex. This function should expect three parameters: lockname,
2924 * pplock, and location. It should create a unique mutex for each unique
2925 * lockname it is provided, and return the mutex identifier in *pplock. The
2926 * location parameter can be used for debugging, as it contains the
2927 * compiler-provided __location__ of the call.
2929 * @param destroy_mutex
2930 * Destroy a mutex. This function should expect two parameters: plock and
2931 * location. It should destroy the mutex associated with the identifier
2932 * plock. The location parameter can be used for debugging, as it contains
2933 * the compiler-provided __location__ of the call.
2936 * Lock a mutex. This function should expect three parameters: plock,
2937 * lock_type, and location. The mutex aassociated with identifier plock
2938 * should be locked if lock_type is 1, and unlocked if lock_type is 2. The
2939 * location parameter can be used for debugging, as it contains the
2940 * compiler-provided __location__ of the call.
2943 * Create thread local storage. This function should expect three
2944 * parameters: keyname, ppkey, and location. It should allocate an
2945 * implementation-specific amount of memory and assign the pointer to that
2946 * allocated memory to *ppkey. The location parameter can be used for
2947 * debugging, as it contains the compiler-provided __location__ of the
2948 * call. This function should return 0 upon success, non-zero upon failure.
2950 * @param destroy_tls
2951 * Destroy thread local storage. This function should expect two parameters:
2952 * ppkey and location. The ppkey parameter points to a variable containing a
2953 * thread local storage key previously provided by the create_tls
2954 * function. The location parameter can be used for debugging, as it
2955 * contains the compiler-provided __location__ of the call.
2958 * Set a thread local storage variable's value. This function should expect
2959 * three parameters: pkey, pval, and location. The pkey parameter is a
2960 * thread local storage key previously provided by the create_tls
2961 * function. The (void *) pval parameter contains the value to be placed in
2962 * the thread local storage variable identified by pkey. The location
2963 * parameter can be used for debugging, as it contains the compiler-provided
2964 * __location__ of the call. This function should return 0 upon success;
2965 * non-zero otherwise.
2968 * Retrieve a thread local storage variable's value. This function should
2969 * expect two parameters: pkey and location. The pkey parameter is a thread
2970 * local storage key previously provided by the create_tls function, and
2971 * which has previously been used in a call to the set_tls function to
2972 * initialize a thread local storage variable. The location parameter can be
2973 * used for debugging, as it contains the compiler-provided __location__ of
2974 * the call. This function should return the (void *) value stored in the
2975 * variable identified by pkey.
2981 /* Mutex functions. */
2982 int (*create_mutex)(const char *lockname,
2984 const char *location),
2985 void (*destroy_mutex)(void *plock,
2986 const char *location),
2987 int (*lock_mutex)(void *plock,
2989 const char *location),
2991 /* Thread local storage. */
2992 int (*create_tls)(const char *keyname,
2994 const char *location),
2995 void (*destroy_tls)(void **ppkey,
2996 const char *location),
2997 int (*set_tls)(void *pkey,
2999 const char *location),
3000 void *(*get_tls)(void *pkey,
3001 const char *location)
3007 * @ingroup structure
3008 * Structure that contains a client context information
3009 * This structure is known as SMBCCTX
3011 * DO NOT DIRECTLY MANIPULATE THE CONTEXT STRUCTURE! The data in the context
3012 * structure should all be considered private to the library. It remains here
3013 * only for backward compatibility.
3015 * See the comments herein for use of the setter and getter functions which
3016 * should now be used for manipulating these values. New features, functions,
3017 * etc., are not added here but rather in _internal where they are not
3018 * directly visible to applications. This makes it much easier to maintain
3019 * ABI compatibility.
3027 * Use smbc_getDebug() and smbc_setDebug()
3029 int debug DEPRECATED_SMBC_INTERFACE;
3032 * netbios name used for making connections
3035 * Use smbc_getNetbiosName() and smbc_setNetbiosName()
3037 char * netbios_name DEPRECATED_SMBC_INTERFACE;
3040 * workgroup name used for making connections
3043 * Use smbc_getWorkgroup() and smbc_setWorkgroup()
3045 char * workgroup DEPRECATED_SMBC_INTERFACE;
3048 * username used for making connections
3051 * Use smbc_getUser() and smbc_setUser()
3053 char * user DEPRECATED_SMBC_INTERFACE;
3056 * timeout used for waiting on connections / response data (in
3060 * Use smbc_getTimeout() and smbc_setTimeout()
3062 int timeout DEPRECATED_SMBC_INTERFACE;
3065 * callable functions for files:
3066 * For usage and return values see the SMBC_* functions
3070 * Use smbc_getFunction*() and smbc_setFunction*(), e.g.
3071 * smbc_getFunctionOpen(), smbc_setFunctionUnlink(), etc.
3073 smbc_open_fn open DEPRECATED_SMBC_INTERFACE;
3074 smbc_creat_fn creat DEPRECATED_SMBC_INTERFACE;
3075 smbc_read_fn read DEPRECATED_SMBC_INTERFACE;
3076 smbc_write_fn write DEPRECATED_SMBC_INTERFACE;
3077 smbc_unlink_fn unlink DEPRECATED_SMBC_INTERFACE;
3078 smbc_rename_fn rename DEPRECATED_SMBC_INTERFACE;
3079 smbc_lseek_fn lseek DEPRECATED_SMBC_INTERFACE;
3080 smbc_stat_fn stat DEPRECATED_SMBC_INTERFACE;
3081 smbc_fstat_fn fstat DEPRECATED_SMBC_INTERFACE;
3082 #if 0 /* internal */
3083 smbc_ftruncate_fn ftruncate_fn;
3085 smbc_close_fn close_fn DEPRECATED_SMBC_INTERFACE;
3086 smbc_opendir_fn opendir DEPRECATED_SMBC_INTERFACE;
3087 smbc_closedir_fn closedir DEPRECATED_SMBC_INTERFACE;
3088 smbc_readdir_fn readdir DEPRECATED_SMBC_INTERFACE;
3089 smbc_readdirplus_fn readdirplus DEPRECATED_SMBC_INTERFACE;
3090 smbc_getdents_fn getdents DEPRECATED_SMBC_INTERFACE;
3091 smbc_mkdir_fn mkdir DEPRECATED_SMBC_INTERFACE;
3092 smbc_rmdir_fn rmdir DEPRECATED_SMBC_INTERFACE;
3093 smbc_telldir_fn telldir DEPRECATED_SMBC_INTERFACE;
3094 smbc_lseekdir_fn lseekdir DEPRECATED_SMBC_INTERFACE;
3095 smbc_fstatdir_fn fstatdir DEPRECATED_SMBC_INTERFACE;
3096 smbc_chmod_fn chmod DEPRECATED_SMBC_INTERFACE;
3097 smbc_utimes_fn utimes DEPRECATED_SMBC_INTERFACE;
3098 smbc_setxattr_fn setxattr DEPRECATED_SMBC_INTERFACE;
3099 smbc_getxattr_fn getxattr DEPRECATED_SMBC_INTERFACE;
3100 smbc_removexattr_fn removexattr DEPRECATED_SMBC_INTERFACE;
3101 smbc_listxattr_fn listxattr DEPRECATED_SMBC_INTERFACE;
3103 /* Printing-related functions */
3104 smbc_print_file_fn print_file DEPRECATED_SMBC_INTERFACE;
3105 smbc_open_print_job_fn open_print_job DEPRECATED_SMBC_INTERFACE;
3106 smbc_list_print_jobs_fn list_print_jobs DEPRECATED_SMBC_INTERFACE;
3107 smbc_unlink_print_job_fn unlink_print_job DEPRECATED_SMBC_INTERFACE;
3114 * See the comment above each field, for the getter and setter
3115 * functions that should now be used.
3117 struct _smbc_callbacks
3120 * authentication function callback: called upon auth requests
3123 * Use smbc_getFunctionAuthData(), smbc_setFunctionAuthData()
3125 smbc_get_auth_data_fn auth_fn DEPRECATED_SMBC_INTERFACE;
3128 * check if a server is still good
3131 * Use smbc_getFunctionCheckServer(),
3132 * smbc_setFunctionCheckServer()
3134 smbc_check_server_fn check_server_fn DEPRECATED_SMBC_INTERFACE;
3137 * remove a server if unused
3140 * Use smbc_getFunctionRemoveUnusedServer(),
3141 * smbc_setFunctionCheckServer()
3143 smbc_remove_unused_server_fn remove_unused_server_fn DEPRECATED_SMBC_INTERFACE;
3147 * For an example cache system see
3148 * samba/source/libsmb/libsmb_cache.c
3150 * Cache subsystem * functions follow.
3154 * server cache addition
3157 * Use smbc_getFunctionAddCachedServer(),
3158 * smbc_setFunctionAddCachedServer()
3160 smbc_add_cached_srv_fn add_cached_srv_fn DEPRECATED_SMBC_INTERFACE;
3163 * server cache lookup
3166 * Use smbc_getFunctionGetCachedServer(),
3167 * smbc_setFunctionGetCachedServer()
3169 smbc_get_cached_srv_fn get_cached_srv_fn DEPRECATED_SMBC_INTERFACE;
3172 * server cache removal
3175 * Use smbc_getFunctionRemoveCachedServer(),
3176 * smbc_setFunctionRemoveCachedServer()
3178 smbc_remove_cached_srv_fn remove_cached_srv_fn DEPRECATED_SMBC_INTERFACE;
3181 * server cache purging, try to remove all cached servers
3185 * Use smbc_getFunctionPurgeCachedServers(),
3186 * smbc_setFunctionPurgeCachedServers()
3188 smbc_purge_cached_fn purge_cached_fn DEPRECATED_SMBC_INTERFACE;
3192 * Space where the private data of the server cache used to be
3195 * Use smbc_getServerCacheData(), smbc_setServerCacheData()
3197 void * reserved DEPRECATED_SMBC_INTERFACE;
3200 * Very old configuration options.
3203 * Use one of the following functions instead:
3204 * smbc_setOptionUseKerberos()
3205 * smbc_getOptionUseKerberos()
3206 * smbc_setOptionFallbackAfterKerberos()
3207 * smbc_getOptionFallbackAfterKerberos()
3208 * smbc_setOptionNoAutoAnonymousLogin()
3209 * smbc_getOptionNoAutoAnonymousLogin()
3211 int flags DEPRECATED_SMBC_INTERFACE;
3214 * user options selections that apply to this session
3216 * NEW OPTIONS ARE NOT ADDED HERE!
3219 * To set and retrieve options, use the smbc_setOption*() and
3220 * smbc_getOption*() functions.
3222 struct _smbc_options {
3223 int browse_max_lmb_count DEPRECATED_SMBC_INTERFACE;
3224 int urlencode_readdir_entries DEPRECATED_SMBC_INTERFACE;
3225 int one_share_per_server DEPRECATED_SMBC_INTERFACE;
3226 } options DEPRECATED_SMBC_INTERFACE;
3229 * do _NOT_ touch this from your program !
3231 struct SMBC_internal_data * internal;
3235 #endif /* SMBCLIENT_H_INCLUDED */