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>
84 #define SMBC_BASE_FD 10000 /* smallest file descriptor returned */
86 #define SMBC_WORKGROUP 1
88 #define SMBC_FILE_SHARE 3
89 #define SMBC_PRINTER_SHARE 4
90 #define SMBC_COMMS_SHARE 5
91 #define SMBC_IPC_SHARE 6
97 * Structure that represents a directory entry.
106 SMBC_PRINTER_SHARE=4,
112 unsigned int smbc_type
;
114 /** Length of this smbc_dirent in bytes
117 /** The length of the comment string in bytes (does not include
120 unsigned int commentlen
;
121 /** Points to the null terminated comment string
124 /** The length of the name string in bytes (does not include
127 unsigned int namelen
;
128 /** Points to the null terminated name string
133 /**@ingroup structure
134 * Structure that represents all attributes of a directory entry.
137 struct libsmb_file_info
144 * DOS attributes of file
156 * Birth/Create time of file (if supported by system)
157 * Otherwise the value will be 0
159 struct timespec btime_ts
;
161 * Modified time for the file
163 struct timespec mtime_ts
;
165 * Access time for the file
167 struct timespec atime_ts
;
169 * Change time for the file
171 struct timespec ctime_ts
;
183 * Logging callback function
185 typedef void (*smbc_debug_callback_fn
)(void *private_ptr
, int level
, const char *msg
);
188 * Flags for smbc_setxattr()
189 * Specify a bitwise OR of these, or 0 to add or replace as necessary
191 #define SMBC_XATTR_FLAG_CREATE 0x1 /* fail if attr already exists */
192 #define SMBC_XATTR_FLAG_REPLACE 0x2 /* fail if attr does not exist */
196 * Mappings of the DOS mode bits, as returned by smbc_getxattr() when the
197 * attribute name "system.dos_attr.mode" (or "system.dos_attr.*" or
198 * "system.*") is specified.
200 #define SMBC_DOS_MODE_READONLY 0x01
201 #define SMBC_DOS_MODE_HIDDEN 0x02
202 #define SMBC_DOS_MODE_SYSTEM 0x04
203 #define SMBC_DOS_MODE_VOLUME_ID 0x08
204 #define SMBC_DOS_MODE_DIRECTORY 0x10
205 #define SMBC_DOS_MODE_ARCHIVE 0x20
208 * Valid values for the option "open_share_mode", when calling
209 * smbc_setOptionOpenShareMode()
211 typedef enum smbc_share_mode
213 SMBC_SHAREMODE_DENY_DOS
= 0,
214 SMBC_SHAREMODE_DENY_ALL
= 1,
215 SMBC_SHAREMODE_DENY_WRITE
= 2,
216 SMBC_SHAREMODE_DENY_READ
= 3,
217 SMBC_SHAREMODE_DENY_NONE
= 4,
218 SMBC_SHAREMODE_DENY_FCB
= 7
223 * Values for option SMB Encryption Level, as set and retrieved with
224 * smbc_setOptionSmbEncryptionLevel() and smbc_getOptionSmbEncryptionLevel()
226 typedef enum smbc_smb_encrypt_level
228 SMBC_ENCRYPTLEVEL_DEFAULT
= -1,
229 SMBC_ENCRYPTLEVEL_NONE
= 0,
230 SMBC_ENCRYPTLEVEL_REQUEST
= 1,
231 SMBC_ENCRYPTLEVEL_REQUIRE
= 2
232 } smbc_smb_encrypt_level
;
236 * Capabilities set in the f_flag field of struct statvfs, from
237 * smbc_statvfs(). These may be OR-ed together to reflect a full set of
238 * available capabilities.
240 typedef enum smbc_vfs_feature
242 /* Defined by POSIX or in Linux include files (low-order bits) */
243 SMBC_VFS_FEATURE_RDONLY
= (1 << 0),
245 /* Specific to libsmbclient (high-order bits) */
246 SMBC_VFS_FEATURE_DFS
= (1 << 28),
247 SMBC_VFS_FEATURE_CASE_INSENSITIVE
= (1 << 29),
248 SMBC_VFS_FEATURE_NO_UNIXCIFS
= (1 << 30)
251 typedef int smbc_bool
;
255 # define ENOATTR ENOENT /* No such attribute */
261 /**@ingroup structure
262 * Structure that represents a print job.
266 struct print_job_info
268 /** numeric ID of the print job
272 /** represents print job priority (lower numbers mean higher priority)
274 unsigned short priority
;
276 /** Size of the print job
280 /** Name of the user that owns the print job
284 /** Name of the print job. This will have no name if an anonymous print
285 * file was opened. Ie smb://server/printer
289 /** Time the print job was spooled
293 #endif /* _CLIENT_H */
296 /**@ingroup structure
299 typedef struct _SMBCSRV SMBCSRV
;
301 /**@ingroup structure
302 * File or directory handle
304 typedef struct _SMBCFILE SMBCFILE
;
306 /**@ingroup structure
307 * File or directory handle
309 typedef struct _SMBCCTX SMBCCTX
;
313 * Flags for SMBCCTX->flags
315 * NEW CODE SHOULD NOT DIRECTLY MANIPULATE THE CONTEXT STRUCTURE.
317 * smbc_setOptionUseKerberos()
318 * smbc_getOptionUseKerberos()
319 * smbc_setOptionFallbackAfterKerberos()
320 * smbc_getOptionFallbackAFterKerberos()
321 * smbc_setOptionNoAutoAnonymousLogin()
322 * smbc_getOptionNoAutoAnonymousLogin()
323 * smbc_setOptionUseCCache()
324 * smbc_getOptionUseCCache()
326 # define SMB_CTX_FLAG_USE_KERBEROS (1 << 0)
327 # define SMB_CTX_FLAG_FALLBACK_AFTER_KERBEROS (1 << 1)
328 # define SMBCCTX_FLAG_NO_AUTO_ANONYMOUS_LOGON (1 << 2)
329 # define SMB_CTX_FLAG_USE_CCACHE (1 << 3)
334 * Authentication callback function type (traditional method)
336 * Type for the the authentication function called by the library to
337 * obtain authentication credentials
339 * For kerberos support the function should just be called without
340 * prompting the user for credentials. Which means a simple 'return'
341 * should work. Take a look at examples/libsmbclient/get_auth_data_fn.h
342 * and examples/libsmbclient/testbrowse.c.
344 * @param srv Server being authenticated to
346 * @param shr Share being authenticated to
348 * @param wg Pointer to buffer containing a "hint" for the
349 * workgroup to be authenticated. Should be filled in
350 * with the correct workgroup if the hint is wrong.
352 * @param wglen The size of the workgroup buffer in bytes
354 * @param un Pointer to buffer containing a "hint" for the
355 * user name to be use for authentication. Should be
356 * filled in with the correct workgroup if the hint is
359 * @param unlen The size of the username buffer in bytes
361 * @param pw Pointer to buffer containing to which password
364 * @param pwlen The size of the password buffer in bytes
367 typedef void (*smbc_get_auth_data_fn
)(const char *srv
,
371 char *pw
, int pwlen
);
373 * Authentication callback function type (method that includes context)
375 * Type for the the authentication function called by the library to
376 * obtain authentication credentials
378 * For kerberos support the function should just be called without
379 * prompting the user for credentials. Which means a simple 'return'
380 * should work. Take a look at examples/libsmbclient/get_auth_data_fn.h
381 * and examples/libsmbclient/testbrowse.c.
383 * @param c Pointer to the smb context
385 * @param srv Server being authenticated to
387 * @param shr Share being authenticated to
389 * @param wg Pointer to buffer containing a "hint" for the
390 * workgroup to be authenticated. Should be filled in
391 * with the correct workgroup if the hint is wrong.
393 * @param wglen The size of the workgroup buffer in bytes
395 * @param un Pointer to buffer containing a "hint" for the
396 * user name to be use for authentication. Should be
397 * filled in with the correct workgroup if the hint is
400 * @param unlen The size of the username buffer in bytes
402 * @param pw Pointer to buffer containing to which password
405 * @param pwlen The size of the password buffer in bytes
408 typedef void (*smbc_get_auth_data_with_context_fn
)(SMBCCTX
*c
,
413 char *pw
, int pwlen
);
417 * Print job info callback function type.
419 * @param i pointer to print job information structure
422 typedef void (*smbc_list_print_job_fn
)(struct print_job_info
*i
);
426 * Check if a server is still good
428 * @param c pointer to smb context
430 * @param srv pointer to server to check
432 * @return 0 when connection is good. 1 on error.
435 typedef int (*smbc_check_server_fn
)(SMBCCTX
* c
, SMBCSRV
*srv
);
438 * Remove a server if unused
440 * @param c pointer to smb context
442 * @param srv pointer to server to remove
444 * @return 0 on success. 1 on failure.
447 typedef int (*smbc_remove_unused_server_fn
)(SMBCCTX
* c
, SMBCSRV
*srv
);
451 * Add a server to the cache system
453 * @param c pointer to smb context
455 * @param srv pointer to server to add
457 * @param server server name
459 * @param share share name
461 * @param workgroup workgroup used to connect
463 * @param username username used to connect
465 * @return 0 on success. 1 on failure.
468 typedef int (*smbc_add_cached_srv_fn
) (SMBCCTX
* c
, SMBCSRV
*srv
,
469 const char * server
, const char * share
,
470 const char * workgroup
, const char * username
);
473 * Look up a server in the cache system
475 * @param c pointer to smb context
477 * @param server server name to match
479 * @param share share name to match
481 * @param workgroup workgroup to match
483 * @param username username to match
485 * @return pointer to SMBCSRV on success. NULL on failure.
488 typedef SMBCSRV
* (*smbc_get_cached_srv_fn
) (SMBCCTX
* c
, const char * server
,
489 const char * share
, const char * workgroup
,
490 const char * username
);
493 * Remove a cached server
495 * @param c pointer to smb context
497 * @param srv pointer to server to remove
499 * @return 0 when found and removed. 1 on failure.
502 typedef int (*smbc_remove_cached_srv_fn
)(SMBCCTX
* c
, SMBCSRV
*srv
);
506 * Try to remove all servers from the cache system and disconnect
508 * @param c pointer to smb context
510 * @return 0 when found and removed. 1 on failure.
513 typedef int (*smbc_purge_cached_fn
) (SMBCCTX
* c
);
517 /*****************************************
518 * Getters and setters for CONFIGURATION *
519 *****************************************/
521 /** Get the debug level */
523 smbc_getDebug(SMBCCTX
*c
);
525 /** Set the debug level */
527 smbc_setDebug(SMBCCTX
*c
, int debug
);
530 * set log callback function to capture logs from libsmbclient, this
531 * is applied at global level
534 smbc_setLogCallback(SMBCCTX
*c
, void *private_ptr
,
535 smbc_debug_callback_fn fn
);
537 /** set configuration file, this is applied at global level */
539 smbc_setConfiguration(SMBCCTX
*c
, const char *file
);
541 /** Get the netbios name used for making connections */
543 smbc_getNetbiosName(SMBCCTX
*c
);
545 /** Set the netbios name used for making connections */
547 smbc_setNetbiosName(SMBCCTX
*c
, const char *netbios_name
);
549 /** Get the workgroup used for making connections */
551 smbc_getWorkgroup(SMBCCTX
*c
);
553 /** Set the workgroup used for making connections */
554 void smbc_setWorkgroup(SMBCCTX
*c
, const char *workgroup
);
556 /** Get the username used for making connections */
558 smbc_getUser(SMBCCTX
*c
);
560 /** Set the username used for making connections */
562 smbc_setUser(SMBCCTX
*c
, const char *user
);
565 * Get the timeout used for waiting on connections and response data
569 smbc_getTimeout(SMBCCTX
*c
);
572 * Set the timeout used for waiting on connections and response data
576 smbc_setTimeout(SMBCCTX
*c
, int timeout
);
580 * Get the TCP port used to connect (0 means default).
583 smbc_getPort(SMBCCTX
*c
);
586 * Set the TCP port used to connect (0 means default).
589 smbc_setPort(SMBCCTX
*c
, uint16_t port
);
591 /** Get whether to enable POSIX extensions if available */
593 smbc_getOptionPosixExtensions(SMBCCTX
*c
);
595 /** Set whether to enable POSIX extensions if available */
597 smbc_setOptionPosixExtensions(SMBCCTX
*c
, smbc_bool b
);
599 /***********************************
600 * Getters and setters for OPTIONS *
601 ***********************************/
603 /** Get whether to log to standard error instead of standard output */
605 smbc_getOptionDebugToStderr(SMBCCTX
*c
);
607 /** Set whether to log to standard error instead of standard output */
609 smbc_setOptionDebugToStderr(SMBCCTX
*c
, smbc_bool b
);
612 * Get whether to use new-style time attribute names, e.g. WRITE_TIME rather
613 * than the old-style names such as M_TIME. This allows also setting/getting
614 * CREATE_TIME which was previously unimplemented. (Note that the old C_TIME
615 * was supposed to be CHANGE_TIME but was confused and sometimes referred to
619 smbc_getOptionFullTimeNames(SMBCCTX
*c
);
622 * Set whether to use new-style time attribute names, e.g. WRITE_TIME rather
623 * than the old-style names such as M_TIME. This allows also setting/getting
624 * CREATE_TIME which was previously unimplemented. (Note that the old C_TIME
625 * was supposed to be CHANGE_TIME but was confused and sometimes referred to
629 smbc_setOptionFullTimeNames(SMBCCTX
*c
, smbc_bool b
);
632 * Get the share mode to use for files opened with SMBC_open_ctx(). The
633 * default is SMBC_SHAREMODE_DENY_NONE.
636 smbc_getOptionOpenShareMode(SMBCCTX
*c
);
639 * Set the share mode to use for files opened with SMBC_open_ctx(). The
640 * default is SMBC_SHAREMODE_DENY_NONE.
643 smbc_setOptionOpenShareMode(SMBCCTX
*c
, smbc_share_mode share_mode
);
645 /** Retrieve a previously saved user data handle */
647 smbc_getOptionUserData(SMBCCTX
*c
);
649 /** Save a user data handle */
651 smbc_setOptionUserData(SMBCCTX
*c
, void *user_data
);
653 /** Get the encoded value for encryption level. */
654 smbc_smb_encrypt_level
655 smbc_getOptionSmbEncryptionLevel(SMBCCTX
*c
);
657 /** Set the encoded value for encryption level. */
659 smbc_setOptionSmbEncryptionLevel(SMBCCTX
*c
, smbc_smb_encrypt_level level
);
662 * Get whether to treat file names as case-sensitive if we can't determine
663 * when connecting to the remote share whether the file system is case
664 * sensitive. This defaults to FALSE since it's most likely that if we can't
665 * retrieve the file system attributes, it's a very old file system that does
666 * not support case sensitivity.
669 smbc_getOptionCaseSensitive(SMBCCTX
*c
);
672 * Set whether to treat file names as case-sensitive if we can't determine
673 * when connecting to the remote share whether the file system is case
674 * sensitive. This defaults to FALSE since it's most likely that if we can't
675 * retrieve the file system attributes, it's a very old file system that does
676 * not support case sensitivity.
679 smbc_setOptionCaseSensitive(SMBCCTX
*c
, smbc_bool b
);
683 * Get from how many local master browsers should the list of workgroups be
684 * retrieved. It can take up to 12 minutes or longer after a server becomes a
685 * local master browser, for it to have the entire browse list (the list of
686 * workgroups/domains) from an entire network. Since a client never knows
687 * which local master browser will be found first, the one which is found
688 * first and used to retrieve a browse list may have an incomplete or empty
689 * browse list. By requesting the browse list from multiple local master
690 * browsers, a more complete list can be generated. For small networks (few
691 * workgroups), it is recommended that this value be set to 0, causing the
692 * browse lists from all found local master browsers to be retrieved and
693 * merged. For networks with many workgroups, a suitable value for this
694 * variable is probably somewhere around 3. (Default: 3).
697 smbc_getOptionBrowseMaxLmbCount(SMBCCTX
*c
);
700 * Set from how many local master browsers should the list of workgroups be
701 * retrieved. It can take up to 12 minutes or longer after a server becomes a
702 * local master browser, for it to have the entire browse list (the list of
703 * workgroups/domains) from an entire network. Since a client never knows
704 * which local master browser will be found first, the one which is found
705 * first and used to retrieve a browse list may have an incomplete or empty
706 * browse list. By requesting the browse list from multiple local master
707 * browsers, a more complete list can be generated. For small networks (few
708 * workgroups), it is recommended that this value be set to 0, causing the
709 * browse lists from all found local master browsers to be retrieved and
710 * merged. For networks with many workgroups, a suitable value for this
711 * variable is probably somewhere around 3. (Default: 3).
714 smbc_setOptionBrowseMaxLmbCount(SMBCCTX
*c
, int count
);
717 * Get whether to url-encode readdir entries.
719 * There is a difference in the desired return strings from
720 * smbc_readdir() depending upon whether the filenames are to
721 * be displayed to the user, or whether they are to be
722 * appended to the path name passed to smbc_opendir() to call
723 * a further smbc_ function (e.g. open the file with
724 * smbc_open()). In the former case, the filename should be
725 * in "human readable" form. In the latter case, the smbc_
726 * functions expect a URL which must be url-encoded. Those
727 * functions decode the URL. If, for example, smbc_readdir()
728 * returned a file name of "abc%20def.txt", passing a path
729 * with this file name attached to smbc_open() would cause
730 * smbc_open to attempt to open the file "abc def.txt" since
731 * the %20 is decoded into a space.
733 * Set this option to True if the names returned by
734 * smbc_readdir() should be url-encoded such that they can be
735 * passed back to another smbc_ call. Set it to False if the
736 * names returned by smbc_readdir() are to be presented to the
739 * For backwards compatibility, this option defaults to False.
742 smbc_getOptionUrlEncodeReaddirEntries(SMBCCTX
*c
);
745 * Set whether to url-encode readdir entries.
747 * There is a difference in the desired return strings from
748 * smbc_readdir() depending upon whether the filenames are to
749 * be displayed to the user, or whether they are to be
750 * appended to the path name passed to smbc_opendir() to call
751 * a further smbc_ function (e.g. open the file with
752 * smbc_open()). In the former case, the filename should be
753 * in "human readable" form. In the latter case, the smbc_
754 * functions expect a URL which must be url-encoded. Those
755 * functions decode the URL. If, for example, smbc_readdir()
756 * returned a file name of "abc%20def.txt", passing a path
757 * with this file name attached to smbc_open() would cause
758 * smbc_open to attempt to open the file "abc def.txt" since
759 * the %20 is decoded into a space.
761 * Set this option to True if the names returned by
762 * smbc_readdir() should be url-encoded such that they can be
763 * passed back to another smbc_ call. Set it to False if the
764 * names returned by smbc_readdir() are to be presented to the
767 * For backwards compatibility, this option defaults to False.
770 smbc_setOptionUrlEncodeReaddirEntries(SMBCCTX
*c
, smbc_bool b
);
773 * Get whether to use the same connection for all shares on a server.
775 * Some Windows versions appear to have a limit to the number
776 * of concurrent SESSIONs and/or TREE CONNECTions. In
777 * one-shot programs (i.e. the program runs and then quickly
778 * ends, thereby shutting down all connections), it is
779 * probably reasonable to establish a new connection for each
780 * share. In long-running applications, the limitation can be
781 * avoided by using only a single connection to each server,
782 * and issuing a new TREE CONNECT when the share is accessed.
785 smbc_getOptionOneSharePerServer(SMBCCTX
*c
);
788 * Set whether to use the same connection for all shares on a server.
790 * Some Windows versions appear to have a limit to the number
791 * of concurrent SESSIONs and/or TREE CONNECTions. In
792 * one-shot programs (i.e. the program runs and then quickly
793 * ends, thereby shutting down all connections), it is
794 * probably reasonable to establish a new connection for each
795 * share. In long-running applications, the limitation can be
796 * avoided by using only a single connection to each server,
797 * and issuing a new TREE CONNECT when the share is accessed.
800 smbc_setOptionOneSharePerServer(SMBCCTX
*c
, smbc_bool b
);
802 /** Get whether to enable use of kerberos */
804 smbc_getOptionUseKerberos(SMBCCTX
*c
);
806 /** Set whether to enable use of kerberos */
808 smbc_setOptionUseKerberos(SMBCCTX
*c
, smbc_bool b
);
810 /** Get whether to fallback after kerberos */
812 smbc_getOptionFallbackAfterKerberos(SMBCCTX
*c
);
814 /** Set whether to fallback after kerberos */
816 smbc_setOptionFallbackAfterKerberos(SMBCCTX
*c
, smbc_bool b
);
818 /** Get whether to automatically select anonymous login */
820 smbc_getOptionNoAutoAnonymousLogin(SMBCCTX
*c
);
822 /** Set whether to automatically select anonymous login */
824 smbc_setOptionNoAutoAnonymousLogin(SMBCCTX
*c
, smbc_bool b
);
826 /** Get whether to enable use of the winbind ccache */
828 smbc_getOptionUseCCache(SMBCCTX
*c
);
830 /** Set whether to enable use of the winbind ccache */
832 smbc_setOptionUseCCache(SMBCCTX
*c
, smbc_bool b
);
834 /** Get indication that the password supplied is the NT hash */
836 smbc_getOptionUseNTHash(SMBCCTX
*c
);
838 /** Set indication that the password supplied is the NT hash */
840 smbc_setOptionUseNTHash(SMBCCTX
*c
, smbc_bool b
);
843 * @brief Set the 'client min protocol' and the 'client max protocol'.
845 * IMPORTANT: This overrides the values 'client min protocol' and 'client max
846 * protocol' set in the smb.conf file!
848 * @param[in] c The smbc context to use.
850 * @param[in] min_proto The minimal protocol to use or NULL for leaving it
853 * @param[in] max_proto The maximum protocol to use or NULL for leaving it
856 * @returns true for success, false otherwise
859 smbc_setOptionProtocols(SMBCCTX
*c
, const char *min_proto
, const char *max_proto
);
861 /*************************************
862 * Getters and setters for FUNCTIONS *
863 *************************************/
865 /** Get the function for obtaining authentication data */
866 smbc_get_auth_data_fn
smbc_getFunctionAuthData(SMBCCTX
*c
);
868 /** Set the function for obtaining authentication data */
869 void smbc_setFunctionAuthData(SMBCCTX
*c
, smbc_get_auth_data_fn fn
);
871 /** Get the new-style authentication function which includes the context. */
872 smbc_get_auth_data_with_context_fn
873 smbc_getFunctionAuthDataWithContext(SMBCCTX
*c
);
875 /** Set the new-style authentication function which includes the context. */
877 smbc_setFunctionAuthDataWithContext(SMBCCTX
*c
,
878 smbc_get_auth_data_with_context_fn fn
);
880 /** Get the function for checking if a server is still good */
881 smbc_check_server_fn
smbc_getFunctionCheckServer(SMBCCTX
*c
);
883 /** Set the function for checking if a server is still good */
884 void smbc_setFunctionCheckServer(SMBCCTX
*c
, smbc_check_server_fn fn
);
886 /** Get the function for removing a server if unused */
887 smbc_remove_unused_server_fn
smbc_getFunctionRemoveUnusedServer(SMBCCTX
*c
);
889 /** Set the function for removing a server if unused */
890 void smbc_setFunctionRemoveUnusedServer(SMBCCTX
*c
,
891 smbc_remove_unused_server_fn fn
);
893 /** Get the function for adding a cached server */
894 smbc_add_cached_srv_fn
smbc_getFunctionAddCachedServer(SMBCCTX
*c
);
896 /** Set the function for adding a cached server */
897 void smbc_setFunctionAddCachedServer(SMBCCTX
*c
, smbc_add_cached_srv_fn fn
);
899 /** Get the function for server cache lookup */
900 smbc_get_cached_srv_fn
smbc_getFunctionGetCachedServer(SMBCCTX
*c
);
902 /** Set the function for server cache lookup */
903 void smbc_setFunctionGetCachedServer(SMBCCTX
*c
, smbc_get_cached_srv_fn fn
);
905 /** Get the function for server cache removal */
906 smbc_remove_cached_srv_fn
smbc_getFunctionRemoveCachedServer(SMBCCTX
*c
);
908 /** Set the function for server cache removal */
909 void smbc_setFunctionRemoveCachedServer(SMBCCTX
*c
,
910 smbc_remove_cached_srv_fn fn
);
913 * Get the function for server cache purging. This function tries to
914 * remove all cached servers (e.g. on disconnect)
916 smbc_purge_cached_fn
smbc_getFunctionPurgeCachedServers(SMBCCTX
*c
);
919 * Set the function for server cache purging. This function tries to
920 * remove all cached servers (e.g. on disconnect)
922 void smbc_setFunctionPurgeCachedServers(SMBCCTX
*c
,
923 smbc_purge_cached_fn fn
);
925 /** Get the function to store private data of the server cache */
926 struct smbc_server_cache
* smbc_getServerCacheData(SMBCCTX
*c
);
928 /** Set the function to store private data of the server cache */
929 void smbc_setServerCacheData(SMBCCTX
*c
, struct smbc_server_cache
* cache
);
933 /*****************************************************************
934 * Callable functions for files. *
935 * Each callable has a function signature typedef, a declaration *
936 * for the getter, and a declaration for the setter. *
937 *****************************************************************/
939 typedef SMBCFILE
* (*smbc_open_fn
)(SMBCCTX
*c
,
943 smbc_open_fn
smbc_getFunctionOpen(SMBCCTX
*c
);
944 void smbc_setFunctionOpen(SMBCCTX
*c
, smbc_open_fn fn
);
946 typedef SMBCFILE
* (*smbc_creat_fn
)(SMBCCTX
*c
,
949 smbc_creat_fn
smbc_getFunctionCreat(SMBCCTX
*c
);
950 void smbc_setFunctionCreat(SMBCCTX
*c
, smbc_creat_fn
);
952 typedef ssize_t (*smbc_read_fn
)(SMBCCTX
*c
,
956 smbc_read_fn
smbc_getFunctionRead(SMBCCTX
*c
);
957 void smbc_setFunctionRead(SMBCCTX
*c
, smbc_read_fn fn
);
959 typedef ssize_t (*smbc_write_fn
)(SMBCCTX
*c
,
963 smbc_write_fn
smbc_getFunctionWrite(SMBCCTX
*c
);
964 void smbc_setFunctionWrite(SMBCCTX
*c
, smbc_write_fn fn
);
966 typedef off_t (*smbc_splice_fn
)(SMBCCTX
*c
,
970 int (*splice_cb
)(off_t n
, void *priv
),
972 smbc_splice_fn
smbc_getFunctionSplice(SMBCCTX
*c
);
973 void smbc_setFunctionSplice(SMBCCTX
*c
, smbc_splice_fn fn
);
975 typedef int (*smbc_unlink_fn
)(SMBCCTX
*c
,
977 smbc_unlink_fn
smbc_getFunctionUnlink(SMBCCTX
*c
);
978 void smbc_setFunctionUnlink(SMBCCTX
*c
, smbc_unlink_fn fn
);
980 typedef int (*smbc_rename_fn
)(SMBCCTX
*ocontext
,
984 smbc_rename_fn
smbc_getFunctionRename(SMBCCTX
*c
);
985 void smbc_setFunctionRename(SMBCCTX
*c
, smbc_rename_fn fn
);
987 typedef off_t (*smbc_lseek_fn
)(SMBCCTX
*c
,
991 smbc_lseek_fn
smbc_getFunctionLseek(SMBCCTX
*c
);
992 void smbc_setFunctionLseek(SMBCCTX
*c
, smbc_lseek_fn fn
);
994 typedef int (*smbc_stat_fn
)(SMBCCTX
*c
,
997 smbc_stat_fn
smbc_getFunctionStat(SMBCCTX
*c
);
998 void smbc_setFunctionStat(SMBCCTX
*c
, smbc_stat_fn fn
);
1000 typedef int (*smbc_fstat_fn
)(SMBCCTX
*c
,
1003 smbc_fstat_fn
smbc_getFunctionFstat(SMBCCTX
*c
);
1004 void smbc_setFunctionFstat(SMBCCTX
*c
, smbc_fstat_fn fn
);
1006 typedef int (*smbc_statvfs_fn
)(SMBCCTX
*c
,
1008 struct statvfs
*st
);
1009 smbc_statvfs_fn
smbc_getFunctionStatVFS(SMBCCTX
*c
);
1010 void smbc_setFunctionStatVFS(SMBCCTX
*c
, smbc_statvfs_fn fn
);
1012 typedef int (*smbc_fstatvfs_fn
)(SMBCCTX
*c
,
1014 struct statvfs
*st
);
1015 smbc_fstatvfs_fn
smbc_getFunctionFstatVFS(SMBCCTX
*c
);
1016 void smbc_setFunctionFstatVFS(SMBCCTX
*c
, smbc_fstatvfs_fn fn
);
1018 typedef int (*smbc_ftruncate_fn
)(SMBCCTX
*c
,
1021 smbc_ftruncate_fn
smbc_getFunctionFtruncate(SMBCCTX
*c
);
1022 void smbc_setFunctionFtruncate(SMBCCTX
*c
, smbc_ftruncate_fn fn
);
1024 typedef int (*smbc_close_fn
)(SMBCCTX
*c
,
1026 smbc_close_fn
smbc_getFunctionClose(SMBCCTX
*c
);
1027 void smbc_setFunctionClose(SMBCCTX
*c
, smbc_close_fn fn
);
1031 /*****************************************************************
1032 * Callable functions for directories. *
1033 * Each callable has a function signature typedef, a declaration *
1034 * for the getter, and a declaration for the setter. *
1035 *****************************************************************/
1037 typedef SMBCFILE
* (*smbc_opendir_fn
)(SMBCCTX
*c
,
1039 smbc_opendir_fn
smbc_getFunctionOpendir(SMBCCTX
*c
);
1040 void smbc_setFunctionOpendir(SMBCCTX
*c
, smbc_opendir_fn fn
);
1042 typedef int (*smbc_closedir_fn
)(SMBCCTX
*c
,
1044 smbc_closedir_fn
smbc_getFunctionClosedir(SMBCCTX
*c
);
1045 void smbc_setFunctionClosedir(SMBCCTX
*c
, smbc_closedir_fn fn
);
1047 typedef struct smbc_dirent
* (*smbc_readdir_fn
)(SMBCCTX
*c
,
1049 smbc_readdir_fn
smbc_getFunctionReaddir(SMBCCTX
*c
);
1050 void smbc_setFunctionReaddir(SMBCCTX
*c
, smbc_readdir_fn fn
);
1052 typedef const struct libsmb_file_info
* (*smbc_readdirplus_fn
)(SMBCCTX
*c
,
1054 smbc_readdirplus_fn
smbc_getFunctionReaddirPlus(SMBCCTX
*c
);
1055 void smbc_setFunctionReaddirPlus(SMBCCTX
*c
, smbc_readdirplus_fn fn
);
1057 typedef const struct libsmb_file_info
* (*smbc_readdirplus2_fn
)(SMBCCTX
*c
,
1060 smbc_readdirplus2_fn
smbc_getFunctionReaddirPlus2(SMBCCTX
*c
);
1061 void smbc_setFunctionReaddirPlus2(SMBCCTX
*c
, smbc_readdirplus2_fn fn
);
1063 typedef int (*smbc_getdents_fn
)(SMBCCTX
*c
,
1065 struct smbc_dirent
*dirp
,
1067 smbc_getdents_fn
smbc_getFunctionGetdents(SMBCCTX
*c
);
1068 void smbc_setFunctionGetdents(SMBCCTX
*c
, smbc_getdents_fn fn
);
1070 typedef int (*smbc_mkdir_fn
)(SMBCCTX
*c
,
1073 smbc_mkdir_fn
smbc_getFunctionMkdir(SMBCCTX
*c
);
1074 void smbc_setFunctionMkdir(SMBCCTX
*c
, smbc_mkdir_fn fn
);
1076 typedef int (*smbc_rmdir_fn
)(SMBCCTX
*c
,
1078 smbc_rmdir_fn
smbc_getFunctionRmdir(SMBCCTX
*c
);
1079 void smbc_setFunctionRmdir(SMBCCTX
*c
, smbc_rmdir_fn fn
);
1081 typedef off_t (*smbc_telldir_fn
)(SMBCCTX
*c
,
1083 smbc_telldir_fn
smbc_getFunctionTelldir(SMBCCTX
*c
);
1084 void smbc_setFunctionTelldir(SMBCCTX
*c
, smbc_telldir_fn fn
);
1086 typedef int (*smbc_lseekdir_fn
)(SMBCCTX
*c
,
1089 smbc_lseekdir_fn
smbc_getFunctionLseekdir(SMBCCTX
*c
);
1090 void smbc_setFunctionLseekdir(SMBCCTX
*c
, smbc_lseekdir_fn fn
);
1092 typedef int (*smbc_fstatdir_fn
)(SMBCCTX
*c
,
1095 smbc_fstatdir_fn
smbc_getFunctionFstatdir(SMBCCTX
*c
);
1096 void smbc_setFunctionFstatdir(SMBCCTX
*c
, smbc_fstatdir_fn fn
);
1098 #define SMBC_NOTIFY_ACTION_ADDED 1
1099 #define SMBC_NOTIFY_ACTION_REMOVED 2
1100 #define SMBC_NOTIFY_ACTION_MODIFIED 3
1101 #define SMBC_NOTIFY_ACTION_OLD_NAME 4
1102 #define SMBC_NOTIFY_ACTION_NEW_NAME 5
1103 #define SMBC_NOTIFY_ACTION_ADDED_STREAM 6
1104 #define SMBC_NOTIFY_ACTION_REMOVED_STREAM 7
1105 #define SMBC_NOTIFY_ACTION_MODIFIED_STREAM 8
1107 struct smbc_notify_callback_action
{
1109 const char *filename
;
1112 typedef int (*smbc_notify_callback_fn
)(
1113 const struct smbc_notify_callback_action
*actions
,
1114 size_t num_actions
, void *private_data
);
1116 typedef int (*smbc_notify_fn
)(SMBCCTX
*c
, SMBCFILE
*dir
, smbc_bool recursive
,
1117 uint32_t completion_filter
,
1118 unsigned callback_timeout_ms
,
1119 smbc_notify_callback_fn cb
, void *private_data
);
1120 smbc_notify_fn
smbc_getFunctionNotify(SMBCCTX
*c
);
1121 void smbc_setFunctionNotify(SMBCCTX
*c
, smbc_notify_fn fn
);
1124 /*****************************************************************
1125 * Callable functions applicable to both files and directories. *
1126 * Each callable has a function signature typedef, a declaration *
1127 * for the getter, and a declaration for the setter. *
1128 *****************************************************************/
1130 typedef int (*smbc_chmod_fn
)(SMBCCTX
*c
,
1133 smbc_chmod_fn
smbc_getFunctionChmod(SMBCCTX
*c
);
1134 void smbc_setFunctionChmod(SMBCCTX
*c
, smbc_chmod_fn fn
);
1136 typedef int (*smbc_utimes_fn
)(SMBCCTX
*c
,
1138 struct timeval
*tbuf
);
1139 smbc_utimes_fn
smbc_getFunctionUtimes(SMBCCTX
*c
);
1140 void smbc_setFunctionUtimes(SMBCCTX
*c
, smbc_utimes_fn fn
);
1142 typedef int (*smbc_setxattr_fn
)(SMBCCTX
*context
,
1148 smbc_setxattr_fn
smbc_getFunctionSetxattr(SMBCCTX
*c
);
1149 void smbc_setFunctionSetxattr(SMBCCTX
*c
, smbc_setxattr_fn fn
);
1151 typedef int (*smbc_getxattr_fn
)(SMBCCTX
*context
,
1156 smbc_getxattr_fn
smbc_getFunctionGetxattr(SMBCCTX
*c
);
1157 void smbc_setFunctionGetxattr(SMBCCTX
*c
, smbc_getxattr_fn fn
);
1159 typedef int (*smbc_removexattr_fn
)(SMBCCTX
*context
,
1162 smbc_removexattr_fn
smbc_getFunctionRemovexattr(SMBCCTX
*c
);
1163 void smbc_setFunctionRemovexattr(SMBCCTX
*c
, smbc_removexattr_fn fn
);
1165 typedef int (*smbc_listxattr_fn
)(SMBCCTX
*context
,
1169 smbc_listxattr_fn
smbc_getFunctionListxattr(SMBCCTX
*c
);
1170 void smbc_setFunctionListxattr(SMBCCTX
*c
, smbc_listxattr_fn fn
);
1174 /*****************************************************************
1175 * Callable functions for printing. *
1176 * Each callable has a function signature typedef, a declaration *
1177 * for the getter, and a declaration for the setter. *
1178 *****************************************************************/
1180 typedef int (*smbc_print_file_fn
)(SMBCCTX
*c_file
,
1183 const char *printq
);
1184 smbc_print_file_fn
smbc_getFunctionPrintFile(SMBCCTX
*c
);
1185 void smbc_setFunctionPrintFile(SMBCCTX
*c
, smbc_print_file_fn fn
);
1187 typedef SMBCFILE
* (*smbc_open_print_job_fn
)(SMBCCTX
*c
,
1189 smbc_open_print_job_fn
smbc_getFunctionOpenPrintJob(SMBCCTX
*c
);
1190 void smbc_setFunctionOpenPrintJob(SMBCCTX
*c
,
1191 smbc_open_print_job_fn fn
);
1193 typedef int (*smbc_list_print_jobs_fn
)(SMBCCTX
*c
,
1195 smbc_list_print_job_fn fn
);
1196 smbc_list_print_jobs_fn
smbc_getFunctionListPrintJobs(SMBCCTX
*c
);
1197 void smbc_setFunctionListPrintJobs(SMBCCTX
*c
,
1198 smbc_list_print_jobs_fn fn
);
1200 typedef int (*smbc_unlink_print_job_fn
)(SMBCCTX
*c
,
1203 smbc_unlink_print_job_fn
smbc_getFunctionUnlinkPrintJob(SMBCCTX
*c
);
1204 void smbc_setFunctionUnlinkPrintJob(SMBCCTX
*c
,
1205 smbc_unlink_print_job_fn fn
);
1209 * Create a new SBMCCTX (a context).
1211 * Must be called before the context is passed to smbc_context_init()
1213 * @return The given SMBCCTX pointer on success, NULL on error with errno set:
1214 * - ENOMEM Out of memory
1216 * @see smbc_free_context(), smbc_init_context()
1218 * @note Do not forget to smbc_init_context() the returned SMBCCTX pointer !
1220 SMBCCTX
* smbc_new_context(void);
1223 * Delete a SBMCCTX (a context) acquired from smbc_new_context().
1225 * The context will be deleted if possible.
1227 * @param context A pointer to a SMBCCTX obtained from smbc_new_context()
1229 * @param shutdown_ctx If 1, all connections and files will be closed even if they are busy.
1232 * @return Returns 0 on success. Returns 1 on failure with errno set:
1233 * - EBUSY Server connections are still used, Files are open or cache
1234 * could not be purged
1235 * - EBADF context == NULL
1237 * @see smbc_new_context()
1239 * @note It is advised to clean up all the contexts with shutdown_ctx set to 1
1240 * just before exit()'ing. When shutdown_ctx is 0, this function can be
1241 * use in periodical cleanup functions for example.
1243 int smbc_free_context(SMBCCTX
* context
, int shutdown_ctx
);
1248 * @deprecated. Use smbc_setOption*() functions instead.
1251 smbc_option_set(SMBCCTX
*context
,
1253 ... /* option_value */);
1256 * @deprecated. Use smbc_getOption*() functions instead.
1259 smbc_option_get(SMBCCTX
*context
,
1263 * Initialize a SBMCCTX (a context).
1265 * Must be called before using any SMBCCTX API function
1267 * @param context A pointer to a SMBCCTX obtained from smbc_new_context()
1269 * @return A pointer to the given SMBCCTX on success,
1270 * NULL on error with errno set:
1271 * - EBADF NULL context given
1272 * - ENOMEM Out of memory
1273 * - ENOENT The smb.conf file would not load
1275 * @see smbc_new_context()
1277 * @note my_context = smbc_init_context(smbc_new_context())
1278 * is perfectly safe, but it might leak memory on
1279 * smbc_context_init() failure. Avoid this.
1280 * You'll have to call smbc_free_context() yourself
1284 SMBCCTX
* smbc_init_context(SMBCCTX
* context
);
1287 * Initialize the samba client library.
1289 * @deprecated use smbc_init_context()
1290 * @see smbc_init_context()
1292 DEPRECATED_SMBC_INTERFACE
1293 int smbc_init(smbc_get_auth_data_fn fn
, int debug
);
1296 * Set or retrieve the compatibility library's context pointer
1298 * @param context New context to use, or NULL. If a new context is provided,
1299 * it must have allocated with smbc_new_context() and
1300 * initialized with smbc_init_context(), followed, optionally,
1301 * by some manual changes to some of the non-internal fields.
1303 * @return The old context.
1305 * @see smbc_new_context(), smbc_init_context(), smbc_init()
1307 * @note This function may be called prior to smbc_init() to force
1308 * use of the next context without any internal calls to
1309 * smbc_new_context() or smbc_init_context(). It may also
1310 * be called after smbc_init() has already called those two
1311 * functions, to replace the existing context with a new one.
1312 * Care should be taken, in this latter case, to ensure that
1313 * the server cache and any data allocated by the
1314 * authentication functions have been freed, if necessary.
1317 SMBCCTX
* smbc_set_context(SMBCCTX
* new_context
);
1320 * Open a file on an SMB server.
1322 * @param furl The smb url of the file to be opened.
1324 * @param flags Is one of O_RDONLY, O_WRONLY or O_RDWR which
1325 * request opening the file read-only,write-only
1326 * or read/write. flags may also be bitwise-or'd with
1327 * one or more of the following:
1328 * O_CREAT - If the file does not exist it will be
1330 * O_EXCL - When used with O_CREAT, if the file
1331 * already exists it is an error and the open will
1333 * O_TRUNC - If the file already exists it will be
1335 * O_APPEND The file is opened in append mode
1337 * @param mode mode specifies the permissions to use if a new
1338 * file is created. It is modified by the
1339 * process's umask in the usual way: the permissions
1340 * of the created file are (mode & ~umask)
1342 * Not currently use, but there for future use.
1343 * We will map this to SYSTEM, HIDDEN, etc bits
1344 * that reverses the mapping that smbc_fstat does.
1346 * @return Valid file handle, < 0 on error with errno set:
1347 * - ENOMEM Out of memory
1348 * - EINVAL if an invalid parameter passed, like no
1349 * file, or smbc_init not called.
1350 * - EEXIST pathname already exists and O_CREAT and
1352 * - EISDIR pathname refers to a directory and
1353 * the access requested involved writing.
1354 * - EACCES The requested access to the file is not
1356 * - ENODEV The requested share does not exist
1357 * - ENOTDIR A file on the path is not a directory
1358 * - ENOENT A directory component in pathname does
1363 * @note This call uses an underlying routine that may create
1364 * a new connection to the server specified in the URL.
1365 * If the credentials supplied in the URL, or via the
1366 * auth_fn in the smbc_init call, fail, this call will
1367 * try again with an empty username and password. This
1368 * often gets mapped to the guest account on some machines.
1371 int smbc_open(const char *furl
, int flags
, mode_t mode
);
1374 * Create a file on an SMB server.
1376 * Same as calling smbc_open() with flags = O_CREAT|O_WRONLY|O_TRUNC
1378 * @param furl The smb url of the file to be created
1380 * @param mode mode specifies the permissions to use if a new
1381 * file is created. It is modified by the
1382 * process's umask in the usual way: the permissions
1383 * of the created file are (mode & ~umask)
1385 * NOTE, the above is not true. We are dealing with
1386 * an SMB server, which has no concept of a umask!
1388 * @return Valid file handle, < 0 on error with errno set:
1389 * - ENOMEM Out of memory
1390 * - EINVAL if an invalid parameter passed, like no
1391 * file, or smbc_init not called.
1392 * - EEXIST pathname already exists and O_CREAT and
1394 * - EISDIR pathname refers to a directory and
1395 * the access requested involved writing.
1396 * - EACCES The requested access to the file is not
1398 * - ENOENT A directory component in pathname does
1400 * - ENODEV The requested share does not exist.
1405 int smbc_creat(const char *furl
, mode_t mode
);
1408 * Read from a file using an opened file handle.
1410 * @param fd Open file handle from smbc_open() or smbc_creat()
1412 * @param buf Pointer to buffer to receive read data
1414 * @param bufsize Size of buf in bytes
1416 * @return Number of bytes read;
1418 * < 0 on error, with errno set:
1419 * - EISDIR fd refers to a directory
1420 * - EBADF fd is not a valid file descriptor or
1421 * is not open for reading.
1422 * - EINVAL fd is attached to an object which is
1423 * unsuitable for reading, or no buffer passed or
1424 * smbc_init not called.
1426 * @see smbc_open(), smbc_write()
1429 ssize_t
smbc_read(int fd
, void *buf
, size_t bufsize
);
1433 * Write to a file using an opened file handle.
1435 * @param fd Open file handle from smbc_open() or smbc_creat()
1437 * @param buf Pointer to buffer to receive read data
1439 * @param bufsize Size of buf in bytes
1441 * @return Number of bytes written, < 0 on error with errno set:
1442 * - EISDIR fd refers to a directory.
1443 * - EBADF fd is not a valid file descriptor or
1444 * is not open for reading.
1445 * - EINVAL fd is attached to an object which is
1446 * unsuitable for reading, or no buffer passed or
1447 * smbc_init not called.
1449 * @see smbc_open(), smbc_read()
1452 ssize_t
smbc_write(int fd
, const void *buf
, size_t bufsize
);
1456 * Seek to a specific location in a file.
1458 * @param fd Open file handle from smbc_open() or smbc_creat()
1460 * @param offset Offset in bytes from whence
1462 * @param whence A location in the file:
1463 * - SEEK_SET The offset is set to offset bytes from
1464 * the beginning of the file
1465 * - SEEK_CUR The offset is set to current location
1466 * plus offset bytes.
1467 * - SEEK_END The offset is set to the size of the
1468 * file plus offset bytes.
1470 * @return Upon successful completion, lseek returns the
1471 * resulting offset location as measured in bytes
1472 * from the beginning of the file. Otherwise, a value
1473 * of (off_t)-1 is returned and errno is set to
1474 * indicate the error:
1475 * - EBADF Fildes is not an open file descriptor.
1476 * - EINVAL Whence is not a proper value or smbc_init
1479 * @todo Are all the whence values really supported?
1481 * @todo Are errno values complete and correct?
1483 off_t
smbc_lseek(int fd
, off_t offset
, int whence
);
1487 * Close an open file handle.
1489 * @param fd The file handle to close
1491 * @return 0 on success, < 0 on error with errno set:
1492 * - EBADF fd isn't a valid open file descriptor
1493 * - EINVAL smbc_init() failed or has not been called
1495 * @see smbc_open(), smbc_creat()
1497 int smbc_close(int fd
);
1500 /**@ingroup directory
1501 * Unlink (delete) a file or directory.
1503 * @param furl The smb url of the file to delete
1505 * @return 0 on success, < 0 on error with errno set:
1506 * - EACCES or EPERM Write access to the directory
1507 * containing pathname is not allowed or one
1508 * of the directories in pathname did not allow
1509 * search (execute) permission
1510 * - ENOENT A directory component in pathname does
1512 * - EINVAL NULL was passed in the file param or
1513 * smbc_init not called.
1514 * - EACCES You do not have access to the file
1515 * - ENOMEM Insufficient kernel memory was available
1517 * @see smbc_rmdir()s
1519 * @todo Are errno values complete and correct?
1521 int smbc_unlink(const char *furl
);
1524 /**@ingroup directory
1525 * Rename or move a file or directory.
1527 * @param ourl The original smb url (source url) of file or
1528 * directory to be moved
1530 * @param nurl The new smb url (destination url) of the file
1531 * or directory after the move. Currently nurl must
1532 * be on the same share as ourl.
1534 * @return 0 on success, < 0 on error with errno set:
1535 * - EISDIR nurl is an existing directory, but ourl is
1537 * - EEXIST nurl is a non-empty directory,
1538 * i.e., contains entries other than "." and ".."
1539 * - EINVAL The new url contained a path prefix
1540 * of the old, or, more generally, an attempt was
1541 * made to make a directory a subdirectory of itself
1542 * or smbc_init not called.
1543 * - ENOTDIR A component used as a directory in ourl
1544 * or nurl path is not, in fact, a directory. Or,
1545 * ourl is a directory, and newpath exists but is not
1547 * - EACCES or EPERM Write access to the directory
1548 * containing ourl or nurl is not allowed for the
1549 * process's effective uid, or one of the
1550 * directories in ourl or nurl did not allow search
1551 * (execute) permission, or ourl was a directory
1552 * and did not allow write permission.
1553 * - ENOENT A directory component in ourl or nurl
1555 * - EXDEV Rename across shares not supported.
1556 * - ENOMEM Insufficient kernel memory was available.
1557 * - EEXIST The target file, nurl, already exists.
1560 * @todo Are we going to support copying when urls are not on the same
1561 * share? I say no... NOTE. I agree for the moment.
1564 int smbc_rename(const char *ourl
, const char *nurl
);
1567 /**@ingroup directory
1568 * Open a directory used to obtain directory entries.
1570 * @param durl The smb url of the directory to open
1572 * @return Valid directory handle. < 0 on error with errno set:
1573 * - EACCES Permission denied.
1574 * - EINVAL A NULL file/URL was passed, or the URL would
1575 * not parse, or was of incorrect form or smbc_init not
1577 * - ENOENT durl does not exist, or name is an
1578 * - ENOMEM Insufficient memory to complete the
1580 * - ENOTDIR name is not a directory.
1581 * - EPERM the workgroup could not be found.
1582 * - ENODEV the workgroup or server could not be found.
1584 * @see smbc_getdents(), smbc_readdir(), smbc_closedir()
1587 int smbc_opendir(const char *durl
);
1590 /**@ingroup directory
1591 * Close a directory handle opened by smbc_opendir().
1593 * @param dh Directory handle to close
1595 * @return 0 on success, < 0 on error with errno set:
1596 * - EBADF dh is an invalid directory handle
1598 * @see smbc_opendir()
1600 int smbc_closedir(int dh
);
1603 /**@ingroup directory
1604 * Get multiple directory entries.
1606 * smbc_getdents() reads as many dirent structures from the an open
1607 * directory handle into a specified memory area as will fit.
1609 * @param dh Valid directory as returned by smbc_opendir()
1611 * @param dirp pointer to buffer that will receive the directory
1614 * @param count The size of the dirp buffer in bytes
1616 * @returns If any dirents returned, return will indicate the
1617 * total size. If there were no more dirents available,
1618 * 0 is returned. < 0 indicates an error.
1619 * - EBADF Invalid directory handle
1620 * - EINVAL Result buffer is too small or smbc_init
1622 * - ENOENT No such directory.
1623 * @see , smbc_dirent, smbc_readdir(), smbc_open()
1625 * @todo Are errno values complete and correct?
1627 * @todo Add example code so people know how to parse buffers.
1629 int smbc_getdents(unsigned int dh
, struct smbc_dirent
*dirp
, int count
);
1632 /**@ingroup directory
1633 * Get a single directory entry.
1635 * @param dh Valid directory as returned by smbc_opendir()
1637 * @return A pointer to a smbc_dirent structure, or NULL if an
1638 * error occurs or end-of-directory is reached:
1639 * - EBADF Invalid directory handle
1640 * - EINVAL smbc_init() failed or has not been called
1642 * @see smbc_dirent, smbc_getdents(), smbc_open()
1644 struct smbc_dirent
* smbc_readdir(unsigned int dh
);
1646 /**@ingroup directory
1647 * Works similar as smbc_readdir() but returns more information about file.
1649 * @param dh Valid directory as returned by smbc_opendir()
1651 * @return A const pointer to a libsmb_file_info structure,
1652 * or NULL if an error occurs or end-of-directory is reached:
1653 * - EBADF Invalid directory handle
1654 * - EINVAL smbc_init() failed or has not been called
1656 * @see smbc_open(), smbc_readdir()
1658 const struct libsmb_file_info
*smbc_readdirplus(unsigned int dh
);
1660 /**@ingroup directory
1661 * Works similar as smbc_readdirplus() as well as fills up stat structure if
1664 * @param dh Valid directory as returned by smbc_opendir()
1666 * @param stat Pointer to stat structure which will receive the
1667 * information. If this pointer is null the call
1668 * is identical to smbc_readdirplus.
1670 * @return A const pointer to a libsmb_file_info structure,
1671 * or NULL if an error occurs or end-of-directory is reached:
1672 * - EBADF Invalid directory handle
1673 * - EINVAL smbc_init() failed or has not been called
1675 * @see smbc_open(), smbc_readdir(), smbc_readdirplus2()
1677 const struct libsmb_file_info
*smbc_readdirplus2(unsigned int dh
,
1680 /**@ingroup directory
1681 * Get the current directory offset.
1683 * smbc_telldir() may be used in conjunction with smbc_readdir() and
1686 * @param dh Valid directory as returned by smbc_opendir()
1688 * @return The current location in the directory stream or -1
1689 * if an error occur. The current location is not
1690 * an offset. Because of the implementation, it is a
1691 * handle that allows the library to find the entry
1693 * - EBADF dh is not a valid directory handle
1694 * - EINVAL smbc_init() failed or has not been called
1695 * - ENOTDIR if dh is not a directory
1697 * @see smbc_readdir()
1700 off_t
smbc_telldir(int dh
);
1703 /**@ingroup directory
1704 * lseek on directories.
1706 * smbc_lseekdir() may be used in conjunction with smbc_readdir() and
1707 * smbc_telldir(). (rewind by smbc_lseekdir(fd, NULL))
1709 * @param fd Valid directory as returned by smbc_opendir()
1711 * @param offset The offset (as returned by smbc_telldir). Can be
1712 * NULL, in which case we will rewind
1714 * @return 0 on success, -1 on failure
1715 * - EBADF dh is not a valid directory handle
1716 * - ENOTDIR if dh is not a directory
1717 * - EINVAL offset did not refer to a valid dirent or
1718 * smbc_init not called.
1720 * @see smbc_telldir()
1723 * @todo In what does the return and errno values mean?
1725 int smbc_lseekdir(int fd
, off_t offset
);
1727 /**@ingroup directory
1728 * Create a directory.
1730 * @param durl The url of the directory to create
1732 * @param mode Specifies the permissions to use. It is modified
1733 * by the process's umask in the usual way: the
1734 * permissions of the created file are (mode & ~umask).
1736 * @return 0 on success, < 0 on error with errno set:
1737 * - EEXIST directory url already exists
1738 * - EACCES The parent directory does not allow write
1739 * permission to the process, or one of the directories
1740 * - ENOENT A directory component in pathname does not
1742 * - EINVAL NULL durl passed or smbc_init not called.
1743 * - ENOMEM Insufficient memory was available.
1748 int smbc_mkdir(const char *durl
, mode_t mode
);
1751 /**@ingroup directory
1752 * Remove a directory.
1754 * @param durl The smb url of the directory to remove
1756 * @return 0 on success, < 0 on error with errno set:
1757 * - EACCES or EPERM Write access to the directory
1758 * containing pathname was not allowed.
1759 * - EINVAL durl is NULL or smbc_init not called.
1760 * - ENOENT A directory component in pathname does not
1762 * - ENOTEMPTY directory contains entries.
1763 * - ENOMEM Insufficient kernel memory was available.
1765 * @see smbc_mkdir(), smbc_unlink()
1767 * @todo Are errno values complete and correct?
1769 int smbc_rmdir(const char *durl
);
1771 /**@ingroup directory
1772 * Request directory notifications
1774 * @param dh Valid directory as returned by smbc_opendir()
1776 * @param recursive Are changes in subdirectories wanted?
1778 * @param completion_filter Bitwise-or of the SMBC_NOTIFY_CHANGE_*
1779 * events that are interesting
1781 * @param callback_timeout_ms If set to non-zero, interval in milliseconds
1782 * that "cb" will be called with 0 actions.
1783 * This gives "cb" the chance to cancel the
1786 * @param cb Callback functions taking events. If "cb"
1787 * returns nonzero, smbc_notify will return.
1789 * @param private_data Pointer given to "cb"
1791 * @return 0 on success, -1 on error with errno set
1793 * @see smbc_opendir(), smbc_closedir()
1796 #define SMBC_NOTIFY_CHANGE_FILE_NAME 0x001
1797 #define SMBC_NOTIFY_CHANGE_DIR_NAME 0x002
1798 #define SMBC_NOTIFY_CHANGE_ATTRIBUTES 0x004
1799 #define SMBC_NOTIFY_CHANGE_SIZE 0x008
1800 #define SMBC_NOTIFY_CHANGE_LAST_WRITE 0x010
1801 #define SMBC_NOTIFY_CHANGE_LAST_ACCESS 0x020
1802 #define SMBC_NOTIFY_CHANGE_CREATION 0x040
1803 #define SMBC_NOTIFY_CHANGE_EA 0x080
1804 #define SMBC_NOTIFY_CHANGE_SECURITY 0x100
1805 #define SMBC_NOTIFY_CHANGE_STREAM_NAME 0x200
1806 #define SMBC_NOTIFY_CHANGE_STREAM_SIZE 0x400
1807 #define SMBC_NOTIFY_CHANGE_STREAM_WRITE 0x800
1809 int smbc_notify(int dh
, smbc_bool recursive
, uint32_t completion_filter
,
1810 unsigned callback_timeout_ms
,
1811 smbc_notify_callback_fn cb
, void *private_data
);
1813 /**@ingroup attribute
1814 * Get information about a file or directory.
1816 * @param url The smb url to get information for
1818 * @param st pointer to a buffer that will be filled with
1819 * standard Unix struct stat information.
1821 * @return 0 on success, < 0 on error with errno set:
1822 * - ENOENT A component of the path file_name does not
1824 * - EINVAL a NULL url was passed or smbc_init not called.
1825 * - EACCES Permission denied.
1826 * - ENOMEM Out of memory
1827 * - ENOTDIR The target dir, url, is not a directory.
1832 int smbc_stat(const char *url
, struct stat
*st
);
1835 /**@ingroup attribute
1836 * Get file information via an file descriptor.
1838 * @param fd Open file handle from smbc_open() or smbc_creat()
1840 * @param st pointer to a buffer that will be filled with
1841 * standard Unix struct stat information.
1843 * @return 0 on success, < 0 on error with errno set:
1844 * - EBADF filedes is bad.
1845 * - EACCES Permission denied.
1846 * - EBADF fd is not a valid file descriptor
1847 * - EINVAL Problems occurred in the underlying routines
1848 * or smbc_init not called.
1849 * - ENOMEM Out of memory
1851 * @see smbc_stat(), Unix stat()
1854 int smbc_fstat(int fd
, struct stat
*st
);
1857 /**@ingroup attribute
1858 * Get file system information for a specified path.
1860 * @param url The smb url to get information for
1862 * @param st pointer to a buffer that will be filled with
1863 * standard Unix struct statvfs information.
1865 * @return 0 on success, < 0 on error with errno set:
1866 * - EBADF filedes is bad.
1867 * - EACCES Permission denied.
1868 * - EBADF fd is not a valid file descriptor
1869 * - EINVAL Problems occurred in the underlying routines
1870 * or smbc_init not called.
1871 * - ENOMEM Out of memory
1873 * @see Unix fstatvfs()
1877 smbc_statvfs(char *url
,
1878 struct statvfs
*st
);
1880 /**@ingroup attribute
1881 * Get file system information via an file descriptor.
1883 * @param fd Open file handle from smbc_open(), smbc_creat(),
1886 * @param st pointer to a buffer that will be filled with
1887 * standard Unix struct statvfs information.
1889 * @return 0 on success, < 0 on error with errno set:
1890 * - EBADF filedes is bad.
1891 * - EACCES Permission denied.
1892 * - EBADF fd is not a valid file descriptor
1893 * - EINVAL Problems occurred in the underlying routines
1894 * or smbc_init not called.
1895 * - ENOMEM Out of memory
1897 * @see Unix fstatvfs()
1901 smbc_fstatvfs(int fd
,
1902 struct statvfs
*st
);
1905 /**@ingroup attribute
1906 * Truncate a file given a file descriptor
1908 * @param fd Open file handle from smbc_open() or smbc_creat()
1910 * @param size size to truncate the file to
1912 * @return 0 on success, < 0 on error with errno set:
1913 * - EBADF filedes is bad.
1914 * - EACCES Permission denied.
1915 * - EBADF fd is not a valid file descriptor
1916 * - EINVAL Problems occurred in the underlying routines
1917 * or smbc_init not called.
1918 * - ENOMEM Out of memory
1920 * @see , Unix ftruncate()
1923 int smbc_ftruncate(int fd
, off_t size
);
1926 /**@ingroup attribute
1927 * Change the permissions of a file.
1929 * @param url The smb url of the file or directory to change
1932 * @param mode The permissions to set:
1933 * - Put good explanation of permissions here!
1935 * @return 0 on success, < 0 on error with errno set:
1936 * - EPERM The effective UID does not match the owner
1937 * of the file, and is not zero
1938 * - ENOENT The file does not exist.
1939 * - ENOMEM Insufficient was available.
1940 * - ENOENT file or directory does not exist
1942 * @todo Actually implement this function?
1944 * @todo Are errno values complete and correct?
1946 int smbc_chmod(const char *url
, mode_t mode
);
1949 * @ingroup attribute
1950 * Change the last modification time on a file
1952 * @param url The smb url of the file or directory to change
1953 * the modification time of
1955 * @param tbuf An array of two timeval structures which contains,
1956 * respectively, the desired access and modification times.
1957 * NOTE: Only the tv_sec field off each timeval structure is
1958 * used. The tv_usec (microseconds) portion is ignored.
1960 * @return 0 on success, < 0 on error with errno set:
1961 * - EINVAL The client library is not properly initialized
1962 * - EPERM Permission was denied.
1965 int smbc_utimes(const char *url
, struct timeval
*tbuf
);
1969 * @ingroup attribute
1970 * Change the last modification time on a file
1972 * @param url The smb url of the file or directory to change
1973 * the modification time of
1975 * @param utbuf A pointer to a utimebuf structure which contains the
1976 * desired access and modification times.
1978 * @return 0 on success, < 0 on error with errno set:
1979 * - EINVAL The client library is not properly initialized
1980 * - ENOMEM No memory was available for internal needs
1981 * - EPERM Permission was denied.
1984 int smbc_utime(const char *fname
, struct utimbuf
*utbuf
);
1987 /**@ingroup attribute
1988 * Set extended attributes for a file. This is used for modifying a file's
1989 * security descriptor (i.e. owner, group, and access control list)
1991 * @param url The smb url of the file or directory to set extended
1994 * @param name The name of an attribute to be changed. Names are of
1995 * one of the following forms:
1997 * system.nt_sec_desc.<attribute name>
1998 * system.nt_sec_desc.*
1999 * system.nt_sec_desc.*+
2001 * where <attribute name> is one of:
2009 * acl+:<name or sid>
2011 * In the forms "system.nt_sec_desc.*" and
2012 * "system.nt_sec_desc.*+", the asterisk and plus signs are
2013 * literal, i.e. the string is provided exactly as shown, and
2014 * the value parameter should contain a complete security
2015 * descriptor with name:value pairs separated by tabs,
2016 * commas, or newlines (not spaces!).
2018 * The plus sign ('+') indicates that SIDs should be mapped
2019 * to names. Without the plus sign, SIDs are not mapped;
2020 * rather they are simply converted to a string format.
2022 * @param value The value to be assigned to the specified attribute name.
2023 * This buffer should contain only the attribute value if the
2024 * name was of the "system.nt_sec_desc.<attribute_name>"
2025 * form. If the name was of the "system.nt_sec_desc.*" form
2026 * then a complete security descriptor, with name:value pairs
2027 * separated by tabs, commas, or newlines (not spaces!),
2028 * should be provided in this value buffer. A complete
2029 * security descriptor will contain one or more entries
2030 * selected from the following:
2032 * REVISION:<revision number>
2033 * OWNER:<sid or name>
2034 * GROUP:<sid or name>
2035 * ACL:<sid or name>:<type>/<flags>/<mask>
2037 * The revision of the ACL specifies the internal Windows NT
2038 * ACL revision for the security descriptor. If not specified
2039 * it defaults to 1. Using values other than 1 may cause
2040 * strange behaviour.
2042 * The owner and group specify the owner and group sids for
2043 * the object. If the attribute name (either '*+' with a
2044 * complete security descriptor, or individual 'owner+' or
2045 * 'group+' attribute names) ended with a plus sign, the
2046 * specified name is resolved to a SID value, using the
2047 * server on which the file or directory resides. Otherwise,
2048 * the value should be provided in SID-printable format as
2049 * S-1-x-y-z, and is used directly. The <sid or name>
2050 * associated with the ACL: attribute should be provided
2053 * @param size The number of the bytes of data in the value buffer
2055 * @param flags A bit-wise OR of zero or more of the following:
2056 * SMBC_XATTR_FLAG_CREATE -
2057 * fail if the named attribute already exists
2058 * SMBC_XATTR_FLAG_REPLACE -
2059 * fail if the attribute does not already exist
2061 * If neither flag is specified, the specified attributes
2062 * will be added or replace existing attributes of the same
2063 * name, as necessary.
2065 * @return 0 on success, < 0 on error with errno set:
2066 * - EINVAL The client library is not properly initialized
2067 * or one of the parameters is not of a correct
2069 * - ENOMEM No memory was available for internal needs
2070 * - EEXIST If the attribute already exists and the flag
2071 * SMBC_XATTR_FLAG_CREAT was specified
2072 * - ENOATTR If the attribute does not exist and the flag
2073 * SMBC_XATTR_FLAG_REPLACE was specified
2074 * - EPERM Permission was denied.
2075 * - ENOTSUP The referenced file system does not support
2076 * extended attributes
2078 * @note Attribute names are compared in a case-insensitive
2079 * fashion. All of the following are equivalent, although
2080 * the all-lower-case name is the preferred format:
2081 * system.nt_sec_desc.owner
2082 * SYSTEM.NT_SEC_DESC.OWNER
2083 * sYsTeM.nt_sEc_desc.owNER
2086 int smbc_setxattr(const char *url
,
2093 /**@ingroup attribute
2094 * Set extended attributes for a file. This is used for modifying a file's
2095 * security descriptor (i.e. owner, group, and access control list). The
2096 * POSIX function which this maps to would act on a symbolic link rather than
2097 * acting on what the symbolic link points to, but with no symbolic links in
2098 * SMB file systems, this function is functionally identical to
2101 * @param url The smb url of the file or directory to set extended
2104 * @param name The name of an attribute to be changed. Names are of
2105 * one of the following forms:
2107 * system.nt_sec_desc.<attribute name>
2108 * system.nt_sec_desc.*
2109 * system.nt_sec_desc.*+
2111 * where <attribute name> is one of:
2119 * acl+:<name or sid>
2121 * In the forms "system.nt_sec_desc.*" and
2122 * "system.nt_sec_desc.*+", the asterisk and plus signs are
2123 * literal, i.e. the string is provided exactly as shown, and
2124 * the value parameter should contain a complete security
2125 * descriptor with name:value pairs separated by tabs,
2126 * commas, or newlines (not spaces!).
2128 * The plus sign ('+') indicates that SIDs should be mapped
2129 * to names. Without the plus sign, SIDs are not mapped;
2130 * rather they are simply converted to a string format.
2132 * @param value The value to be assigned to the specified attribute name.
2133 * This buffer should contain only the attribute value if the
2134 * name was of the "system.nt_sec_desc.<attribute_name>"
2135 * form. If the name was of the "system.nt_sec_desc.*" form
2136 * then a complete security descriptor, with name:value pairs
2137 * separated by tabs, commas, or newlines (not spaces!),
2138 * should be provided in this value buffer. A complete
2139 * security descriptor will contain one or more entries
2140 * selected from the following:
2142 * REVISION:<revision number>
2143 * OWNER:<sid or name>
2144 * GROUP:<sid or name>
2145 * ACL:<sid or name>:<type>/<flags>/<mask>
2147 * The revision of the ACL specifies the internal Windows NT
2148 * ACL revision for the security descriptor. If not specified
2149 * it defaults to 1. Using values other than 1 may cause
2150 * strange behaviour.
2152 * The owner and group specify the owner and group sids for
2153 * the object. If the attribute name (either '*+' with a
2154 * complete security descriptor, or individual 'owner+' or
2155 * 'group+' attribute names) ended with a plus sign, the
2156 * specified name is resolved to a SID value, using the
2157 * server on which the file or directory resides. Otherwise,
2158 * the value should be provided in SID-printable format as
2159 * S-1-x-y-z, and is used directly. The <sid or name>
2160 * associated with the ACL: attribute should be provided
2163 * @param size The number of the bytes of data in the value buffer
2165 * @param flags A bit-wise OR of zero or more of the following:
2166 * SMBC_XATTR_FLAG_CREATE -
2167 * fail if the named attribute already exists
2168 * SMBC_XATTR_FLAG_REPLACE -
2169 * fail if the attribute does not already exist
2171 * If neither flag is specified, the specified attributes
2172 * will be added or replace existing attributes of the same
2173 * name, as necessary.
2175 * @return 0 on success, < 0 on error with errno set:
2176 * - EINVAL The client library is not properly initialized
2177 * or one of the parameters is not of a correct
2179 * - ENOMEM No memory was available for internal needs
2180 * - EEXIST If the attribute already exists and the flag
2181 * SMBC_XATTR_FLAG_CREAT was specified
2182 * - ENOATTR If the attribute does not exist and the flag
2183 * SMBC_XATTR_FLAG_REPLACE was specified
2184 * - EPERM Permission was denied.
2185 * - ENOTSUP The referenced file system does not support
2186 * extended attributes
2188 * @note Attribute names are compared in a case-insensitive
2189 * fashion. All of the following are equivalent, although
2190 * the all-lower-case name is the preferred format:
2191 * system.nt_sec_desc.owner
2192 * SYSTEM.NT_SEC_DESC.OWNER
2193 * sYsTeM.nt_sEc_desc.owNER
2196 int smbc_lsetxattr(const char *url
,
2203 /**@ingroup attribute
2204 * Set extended attributes for a file. This is used for modifying a file's
2205 * security descriptor (i.e. owner, group, and access control list)
2207 * @param fd A file descriptor associated with an open file (as
2208 * previously returned by smbc_open(), to get extended
2211 * @param name The name of an attribute to be changed. Names are of
2212 * one of the following forms:
2214 * system.nt_sec_desc.<attribute name>
2215 * system.nt_sec_desc.*
2216 * system.nt_sec_desc.*+
2218 * where <attribute name> is one of:
2226 * acl+:<name or sid>
2228 * In the forms "system.nt_sec_desc.*" and
2229 * "system.nt_sec_desc.*+", the asterisk and plus signs are
2230 * literal, i.e. the string is provided exactly as shown, and
2231 * the value parameter should contain a complete security
2232 * descriptor with name:value pairs separated by tabs,
2233 * commas, or newlines (not spaces!).
2235 * The plus sign ('+') indicates that SIDs should be mapped
2236 * to names. Without the plus sign, SIDs are not mapped;
2237 * rather they are simply converted to a string format.
2239 * @param value The value to be assigned to the specified attribute name.
2240 * This buffer should contain only the attribute value if the
2241 * name was of the "system.nt_sec_desc.<attribute_name>"
2242 * form. If the name was of the "system.nt_sec_desc.*" form
2243 * then a complete security descriptor, with name:value pairs
2244 * separated by tabs, commas, or newlines (not spaces!),
2245 * should be provided in this value buffer. A complete
2246 * security descriptor will contain one or more entries
2247 * selected from the following:
2249 * REVISION:<revision number>
2250 * OWNER:<sid or name>
2251 * GROUP:<sid or name>
2252 * ACL:<sid or name>:<type>/<flags>/<mask>
2254 * The revision of the ACL specifies the internal Windows NT
2255 * ACL revision for the security descriptor. If not specified
2256 * it defaults to 1. Using values other than 1 may cause
2257 * strange behaviour.
2259 * The owner and group specify the owner and group sids for
2260 * the object. If the attribute name (either '*+' with a
2261 * complete security descriptor, or individual 'owner+' or
2262 * 'group+' attribute names) ended with a plus sign, the
2263 * specified name is resolved to a SID value, using the
2264 * server on which the file or directory resides. Otherwise,
2265 * the value should be provided in SID-printable format as
2266 * S-1-x-y-z, and is used directly. The <sid or name>
2267 * associated with the ACL: attribute should be provided
2270 * @param size The number of the bytes of data in the value buffer
2272 * @param flags A bit-wise OR of zero or more of the following:
2273 * SMBC_XATTR_FLAG_CREATE -
2274 * fail if the named attribute already exists
2275 * SMBC_XATTR_FLAG_REPLACE -
2276 * fail if the attribute does not already exist
2278 * If neither flag is specified, the specified attributes
2279 * will be added or replace existing attributes of the same
2280 * name, as necessary.
2282 * @return 0 on success, < 0 on error with errno set:
2283 * - EINVAL The client library is not properly initialized
2284 * or one of the parameters is not of a correct
2286 * - ENOMEM No memory was available for internal needs
2287 * - EEXIST If the attribute already exists and the flag
2288 * SMBC_XATTR_FLAG_CREAT was specified
2289 * - ENOATTR If the attribute does not exist and the flag
2290 * SMBC_XATTR_FLAG_REPLACE was specified
2291 * - EPERM Permission was denied.
2292 * - ENOTSUP The referenced file system does not support
2293 * extended attributes
2295 * @note Attribute names are compared in a case-insensitive
2296 * fashion. All of the following are equivalent, although
2297 * the all-lower-case name is the preferred format:
2298 * system.nt_sec_desc.owner
2299 * SYSTEM.NT_SEC_DESC.OWNER
2300 * sYsTeM.nt_sEc_desc.owNER
2303 int smbc_fsetxattr(int fd
,
2310 /**@ingroup attribute
2311 * Get extended attributes for a file.
2313 * @param url The smb url of the file or directory to get extended
2316 * @param name The name of an attribute to be retrieved. Names are of
2317 * one of the following forms:
2319 * system.nt_sec_desc.<attribute name>
2320 * system.nt_sec_desc.*
2321 * system.nt_sec_desc.*+
2323 * where <attribute name> is one of:
2331 * acl+:<name or sid>
2333 * In the forms "system.nt_sec_desc.*" and
2334 * "system.nt_sec_desc.*+", the asterisk and plus signs are
2335 * literal, i.e. the string is provided exactly as shown, and
2336 * the value parameter will return a complete security
2337 * descriptor with name:value pairs separated by tabs,
2338 * commas, or newlines (not spaces!).
2340 * The plus sign ('+') indicates that SIDs should be mapped
2341 * to names. Without the plus sign, SIDs are not mapped;
2342 * rather they are simply converted to a string format.
2344 * @param value A pointer to a buffer in which the value of the specified
2345 * attribute will be placed (unless size is zero).
2347 * @param size The size of the buffer pointed to by value. This parameter
2348 * may also be zero, in which case the size of the buffer
2349 * required to hold the attribute value will be returned,
2350 * but nothing will be placed into the value buffer.
2352 * @return 0 on success, < 0 on error with errno set:
2353 * - EINVAL The client library is not properly initialized
2354 * or one of the parameters is not of a correct
2356 * - ENOMEM No memory was available for internal needs
2357 * - EEXIST If the attribute already exists and the flag
2358 * SMBC_XATTR_FLAG_CREAT was specified
2359 * - ENOATTR If the attribute does not exist and the flag
2360 * SMBC_XATTR_FLAG_REPLACE was specified
2361 * - EPERM Permission was denied.
2362 * - ENOTSUP The referenced file system does not support
2363 * extended attributes
2366 int smbc_getxattr(const char *url
,
2372 /**@ingroup attribute
2373 * Get extended attributes for a file. The POSIX function which this maps to
2374 * would act on a symbolic link rather than acting on what the symbolic link
2375 * points to, but with no symbolic links in SMB file systems, this function
2376 * is functionally identical to smbc_getxattr().
2378 * @param url The smb url of the file or directory to get extended
2381 * @param name The name of an attribute to be retrieved. Names are of
2382 * one of the following forms:
2384 * system.nt_sec_desc.<attribute name>
2385 * system.nt_sec_desc.*
2386 * system.nt_sec_desc.*+
2388 * where <attribute name> is one of:
2396 * acl+:<name or sid>
2398 * In the forms "system.nt_sec_desc.*" and
2399 * "system.nt_sec_desc.*+", the asterisk and plus signs are
2400 * literal, i.e. the string is provided exactly as shown, and
2401 * the value parameter will return a complete security
2402 * descriptor with name:value pairs separated by tabs,
2403 * commas, or newlines (not spaces!).
2405 * The plus sign ('+') indicates that SIDs should be mapped
2406 * to names. Without the plus sign, SIDs are not mapped;
2407 * rather they are simply converted to a string format.
2409 * @param value A pointer to a buffer in which the value of the specified
2410 * attribute will be placed (unless size is zero).
2412 * @param size The size of the buffer pointed to by value. This parameter
2413 * may also be zero, in which case the size of the buffer
2414 * required to hold the attribute value will be returned,
2415 * but nothing will be placed into the value buffer.
2417 * @return size on success, < 0 on error with errno set:
2418 * - EINVAL The client library is not properly initialized
2419 * or one of the parameters is not of a correct
2421 * - ENOMEM No memory was available for internal needs
2422 * - EEXIST If the attribute already exists and the flag
2423 * SMBC_XATTR_FLAG_CREAT was specified
2424 * - ENOATTR If the attribute does not exist and the flag
2425 * SMBC_XATTR_FLAG_REPLACE was specified
2426 * - EPERM Permission was denied.
2427 * - ENOTSUP The referenced file system does not support
2428 * extended attributes
2431 int smbc_lgetxattr(const char *url
,
2437 /**@ingroup attribute
2438 * Get extended attributes for a file.
2440 * @param fd A file descriptor associated with an open file (as
2441 * previously returned by smbc_open(), to get extended
2444 * @param name The name of an attribute to be retrieved. Names are of
2445 * one of the following forms:
2447 * system.nt_sec_desc.<attribute name>
2448 * system.nt_sec_desc.*
2449 * system.nt_sec_desc.*+
2451 * where <attribute name> is one of:
2459 * acl+:<name or sid>
2461 * In the forms "system.nt_sec_desc.*" and
2462 * "system.nt_sec_desc.*+", the asterisk and plus signs are
2463 * literal, i.e. the string is provided exactly as shown, and
2464 * the value parameter will return a complete security
2465 * descriptor with name:value pairs separated by tabs,
2466 * commas, or newlines (not spaces!).
2468 * The plus sign ('+') indicates that SIDs should be mapped
2469 * to names. Without the plus sign, SIDs are not mapped;
2470 * rather they are simply converted to a string format.
2472 * @param value A pointer to a buffer in which the value of the specified
2473 * attribute will be placed (unless size is zero).
2475 * @param size The size of the buffer pointed to by value. This parameter
2476 * may also be zero, in which case the size of the buffer
2477 * required to hold the attribute value will be returned,
2478 * but nothing will be placed into the value buffer.
2480 * @return 0 on success, < 0 on error with errno set:
2481 * - EINVAL The client library is not properly initialized
2482 * or one of the parameters is not of a correct
2484 * - ENOMEM No memory was available for internal needs
2485 * - EEXIST If the attribute already exists and the flag
2486 * SMBC_XATTR_FLAG_CREAT was specified
2487 * - ENOATTR If the attribute does not exist and the flag
2488 * SMBC_XATTR_FLAG_REPLACE was specified
2489 * - EPERM Permission was denied.
2490 * - ENOTSUP The referenced file system does not support
2491 * extended attributes
2494 int smbc_fgetxattr(int fd
,
2500 /**@ingroup attribute
2501 * Remove extended attributes for a file. This is used for modifying a file's
2502 * security descriptor (i.e. owner, group, and access control list)
2504 * @param url The smb url of the file or directory to remove the extended
2507 * @param name The name of an attribute to be removed. Names are of
2508 * one of the following forms:
2510 * system.nt_sec_desc.<attribute name>
2511 * system.nt_sec_desc.*
2512 * system.nt_sec_desc.*+
2514 * where <attribute name> is one of:
2522 * acl+:<name or sid>
2524 * In the forms "system.nt_sec_desc.*" and
2525 * "system.nt_sec_desc.*+", the asterisk and plus signs are
2526 * literal, i.e. the string is provided exactly as shown, and
2527 * the value parameter will return a complete security
2528 * descriptor with name:value pairs separated by tabs,
2529 * commas, or newlines (not spaces!).
2531 * The plus sign ('+') indicates that SIDs should be mapped
2532 * to names. Without the plus sign, SIDs are not mapped;
2533 * rather they are simply converted to a string format.
2535 * @return 0 on success, < 0 on error with errno set:
2536 * - EINVAL The client library is not properly initialized
2537 * - ENOMEM No memory was available for internal needs
2538 * - EPERM Permission was denied.
2539 * - ENOTSUP The referenced file system does not support
2540 * extended attributes
2543 int smbc_removexattr(const char *url
,
2547 /**@ingroup attribute
2548 * Remove extended attributes for a file. This is used for modifying a file's
2549 * security descriptor (i.e. owner, group, and access control list) The POSIX
2550 * function which this maps to would act on a symbolic link rather than acting
2551 * on what the symbolic link points to, but with no symbolic links in SMB file
2552 * systems, this function is functionally identical to smbc_removexattr().
2554 * @param url The smb url of the file or directory to remove the extended
2557 * @param name The name of an attribute to be removed. Names are of
2558 * one of the following forms:
2560 * system.nt_sec_desc.<attribute name>
2561 * system.nt_sec_desc.*
2562 * system.nt_sec_desc.*+
2564 * where <attribute name> is one of:
2572 * acl+:<name or sid>
2574 * In the forms "system.nt_sec_desc.*" and
2575 * "system.nt_sec_desc.*+", the asterisk and plus signs are
2576 * literal, i.e. the string is provided exactly as shown, and
2577 * the value parameter will return a complete security
2578 * descriptor with name:value pairs separated by tabs,
2579 * commas, or newlines (not spaces!).
2581 * The plus sign ('+') indicates that SIDs should be mapped
2582 * to names. Without the plus sign, SIDs are not mapped;
2583 * rather they are simply converted to a string format.
2585 * @return 0 on success, < 0 on error with errno set:
2586 * - EINVAL The client library is not properly initialized
2587 * - ENOMEM No memory was available for internal needs
2588 * - EPERM Permission was denied.
2589 * - ENOTSUP The referenced file system does not support
2590 * extended attributes
2593 int smbc_lremovexattr(const char *url
,
2597 /**@ingroup attribute
2598 * Remove extended attributes for a file. This is used for modifying a file's
2599 * security descriptor (i.e. owner, group, and access control list)
2601 * @param fd A file descriptor associated with an open file (as
2602 * previously returned by smbc_open(), to get extended
2605 * @param name The name of an attribute to be removed. Names are of
2606 * one of the following forms:
2608 * system.nt_sec_desc.<attribute name>
2609 * system.nt_sec_desc.*
2610 * system.nt_sec_desc.*+
2612 * where <attribute name> is one of:
2620 * acl+:<name or sid>
2622 * In the forms "system.nt_sec_desc.*" and
2623 * "system.nt_sec_desc.*+", the asterisk and plus signs are
2624 * literal, i.e. the string is provided exactly as shown, and
2625 * the value parameter will return a complete security
2626 * descriptor with name:value pairs separated by tabs,
2627 * commas, or newlines (not spaces!).
2629 * The plus sign ('+') indicates that SIDs should be mapped
2630 * to names. Without the plus sign, SIDs are not mapped;
2631 * rather they are simply converted to a string format.
2633 * @return 0 on success, < 0 on error with errno set:
2634 * - EINVAL The client library is not properly initialized
2635 * - ENOMEM No memory was available for internal needs
2636 * - EPERM Permission was denied.
2637 * - ENOTSUP The referenced file system does not support
2638 * extended attributes
2641 int smbc_fremovexattr(int fd
,
2645 /**@ingroup attribute
2646 * List the supported extended attribute names associated with a file
2648 * @param url The smb url of the file or directory to list the extended
2651 * @param list A pointer to a buffer in which the list of attributes for
2652 * the specified file or directory will be placed (unless
2655 * @param size The size of the buffer pointed to by list. This parameter
2656 * may also be zero, in which case the size of the buffer
2657 * required to hold all of the attribute names will be
2658 * returned, but nothing will be placed into the list buffer.
2660 * @return 0 on success, < 0 on error with errno set:
2661 * - EINVAL The client library is not properly initialized
2662 * - ENOMEM No memory was available for internal needs
2663 * - EPERM Permission was denied.
2664 * - ENOTSUP The referenced file system does not support
2665 * extended attributes
2667 * @note This function always returns all attribute names supported
2668 * by NT file systems, regardless of whether the referenced
2669 * file system supports extended attributes (e.g. a Windows
2670 * 2000 machine supports extended attributes if NTFS is used,
2671 * but not if FAT is used, and Windows 98 doesn't support
2672 * extended attributes at all. Whether this is a feature or
2673 * a bug is yet to be decided.
2675 int smbc_listxattr(const char *url
,
2679 /**@ingroup attribute
2680 * List the supported extended attribute names associated with a file The
2681 * POSIX function which this maps to would act on a symbolic link rather than
2682 * acting on what the symbolic link points to, but with no symbolic links in
2683 * SMB file systems, this function is functionally identical to
2686 * @param url The smb url of the file or directory to list the extended
2689 * @param list A pointer to a buffer in which the list of attributes for
2690 * the specified file or directory will be placed (unless
2693 * @param size The size of the buffer pointed to by list. This parameter
2694 * may also be zero, in which case the size of the buffer
2695 * required to hold all of the attribute names will be
2696 * returned, but nothing will be placed into the list buffer.
2698 * @return 0 on success, < 0 on error with errno set:
2699 * - EINVAL The client library is not properly initialized
2700 * - ENOMEM No memory was available for internal needs
2701 * - EPERM Permission was denied.
2702 * - ENOTSUP The referenced file system does not support
2703 * extended attributes
2705 * @note This function always returns all attribute names supported
2706 * by NT file systems, regardless of whether the referenced
2707 * file system supports extended attributes (e.g. a Windows
2708 * 2000 machine supports extended attributes if NTFS is used,
2709 * but not if FAT is used, and Windows 98 doesn't support
2710 * extended attributes at all. Whether this is a feature or
2711 * a bug is yet to be decided.
2713 int smbc_llistxattr(const char *url
,
2717 /**@ingroup attribute
2718 * List the supported extended attribute names associated with a file
2720 * @param fd A file descriptor associated with an open file (as
2721 * previously returned by smbc_open(), to get extended
2724 * @param list A pointer to a buffer in which the list of attributes for
2725 * the specified file or directory will be placed (unless
2728 * @param size The size of the buffer pointed to by list. This parameter
2729 * may also be zero, in which case the size of the buffer
2730 * required to hold all of the attribute names will be
2731 * returned, but nothing will be placed into the list buffer.
2733 * @return 0 on success, < 0 on error with errno set:
2734 * - EINVAL The client library is not properly initialized
2735 * - ENOMEM No memory was available for internal needs
2736 * - EPERM Permission was denied.
2737 * - ENOTSUP The referenced file system does not support
2738 * extended attributes
2740 * @note This function always returns all attribute names supported
2741 * by NT file systems, regardless of whether the referenced
2742 * file system supports extended attributes (e.g. a Windows
2743 * 2000 machine supports extended attributes if NTFS is used,
2744 * but not if FAT is used, and Windows 98 doesn't support
2745 * extended attributes at all. Whether this is a feature or
2746 * a bug is yet to be decided.
2748 int smbc_flistxattr(int fd
,
2753 * Print a file given the name in fname. It would be a URL ...
2755 * @param fname The URL of a file on a remote SMB server that the
2756 * caller wants printed
2758 * @param printq The URL of the print share to print the file to.
2760 * @return 0 on success, < 0 on error with errno set:
2762 * - EINVAL fname or printq was NULL or smbc_init not
2764 * and errors returned by smbc_open
2767 int smbc_print_file(const char *fname
, const char *printq
);
2770 * Open a print file that can be written to by other calls. This simply
2771 * does an smbc_open call after checking if there is a file name on the
2772 * URI. If not, a temporary name is added ...
2774 * @param fname The URL of the print share to print to?
2776 * @returns A file handle for the print file if successful.
2777 * Returns -1 if an error occurred and errno has the values
2778 * - EINVAL fname was NULL or smbc_init not called.
2779 * - all errors returned by smbc_open
2782 int smbc_open_print_job(const char *fname
);
2785 * List the print jobs on a print share, for the moment, pass a callback
2787 * @param purl The url of the print share to list the jobs of
2789 * @param fn Callback function the receives printjob info
2791 * @return 0 on success, < 0 on error with errno set:
2792 * - EINVAL fname was NULL or smbc_init not called
2795 int smbc_list_print_jobs(const char *purl
, smbc_list_print_job_fn fn
);
2798 * Delete a print job
2800 * @param purl Url of the print share
2802 * @param id The id of the job to delete
2804 * @return 0 on success, < 0 on error with errno set:
2805 * - EINVAL fname was NULL or smbc_init not called
2807 * @todo what errno values are possible here?
2809 int smbc_unlink_print_job(const char *purl
, int id
);
2811 /**@ingroup callback
2812 * Remove a server from the cached server list it's unused.
2814 * @param context pointer to smb context
2816 * @param srv pointer to server to remove
2818 * @return On success, 0 is returned. 1 is returned if the server could not
2819 * be removed. Also usable outside libsmbclient.
2821 int smbc_remove_unused_server(SMBCCTX
* context
, SMBCSRV
* srv
);
2827 /**@ingroup directory
2828 * Convert strings of %xx to their single character equivalent.
2830 * @param dest A pointer to a buffer in which the resulting decoded
2831 * string should be placed. This may be a pointer to the
2832 * same buffer as src_segment.
2834 * @param src A pointer to the buffer containing the URL to be decoded.
2835 * Any %xx sequences herein are converted to their single
2836 * character equivalent. Each 'x' must be a valid hexadecimal
2837 * digit, or that % sequence is left undecoded.
2839 * @param max_dest_len
2840 * The size of the buffer pointed to by dest_segment.
2842 * @return The number of % sequences which could not be converted
2843 * due to lack of two following hexadecimal digits.
2849 smbc_urldecode(char *dest
, char * src
, size_t max_dest_len
);
2856 * Convert any characters not specifically allowed in a URL into their %xx
2859 * @param dest A pointer to a buffer in which the resulting encoded
2860 * string should be placed. Unlike smbc_urldecode(), this
2861 * must be a buffer unique from src.
2863 * @param src A pointer to the buffer containing the string to be encoded.
2864 * Any character not specifically allowed in a URL is converted
2865 * into its hexadecimal value and encoded as %xx.
2867 * @param max_dest_len
2868 * The size of the buffer pointed to by dest_segment.
2870 * @returns The remaining buffer length.
2876 smbc_urlencode(char * dest
, char * src
, int max_dest_len
);
2882 /**@ingroup directory
2883 * Return the version of the linked Samba code, and thus the version of the
2884 * libsmbclient code.
2886 * @return The version string.
2898 * @deprecated This interface has been deprecated use
2899 * smbc_set_credentials_with_fallback() instead.
2901 * @see smbc_set_credentials_with_fallback()
2903 DEPRECATED_SMBC_INTERFACE
2905 smbc_set_credentials(const char *workgroup
,
2907 const char *password
,
2908 smbc_bool use_kerberos
,
2909 const char *signing_state
);
2913 * Set the users credentials globally so they can be used for DFS
2914 * referrals. Probably best to use this function in the smbc_get_auth_data_fn
2917 * @param ctx The smb context.
2919 * @param workgroup Workgroup of the user.
2921 * @param user Username of user.
2923 * @param password Password of user.
2926 smbc_set_credentials_with_fallback(SMBCCTX
*ctx
,
2927 const char *workgroup
,
2929 const char *password
);
2935 * Initialize for threads using the Posix Threads (pthread)
2936 * implementation. This is a built-in implementation, avoiding the need to
2937 * implement the component functions of the thread interface. If this function
2938 * is used, it is not necessary to call smbc_thread_impl().
2943 smbc_thread_posix(void);
2948 * Initialize for an arbitrary thread implementation. The caller should
2949 * provide, as parameters, pointers to functions to implement the requisite
2950 * low-level thread functionality. A function must be provided for each
2951 * parameter; none may be null.
2953 * If the thread implementation is POSIX Threads (pthreads), then the much
2954 * simpler smbc_thread_pthread() function may be used instead of this one.
2956 * @param create_mutex
2957 * Create a mutex. This function should expect three parameters: lockname,
2958 * pplock, and location. It should create a unique mutex for each unique
2959 * lockname it is provided, and return the mutex identifier in *pplock. The
2960 * location parameter can be used for debugging, as it contains the
2961 * compiler-provided __location__ of the call.
2963 * @param destroy_mutex
2964 * Destroy a mutex. This function should expect two parameters: plock and
2965 * location. It should destroy the mutex associated with the identifier
2966 * plock. The location parameter can be used for debugging, as it contains
2967 * the compiler-provided __location__ of the call.
2970 * Lock a mutex. This function should expect three parameters: plock,
2971 * lock_type, and location. The mutex associated with identifier plock
2972 * should be locked if lock_type is 1, and unlocked if lock_type is 2. The
2973 * location parameter can be used for debugging, as it contains the
2974 * compiler-provided __location__ of the call.
2977 * Create thread local storage. This function should expect three
2978 * parameters: keyname, ppkey, and location. It should allocate an
2979 * implementation-specific amount of memory and assign the pointer to that
2980 * allocated memory to *ppkey. The location parameter can be used for
2981 * debugging, as it contains the compiler-provided __location__ of the
2982 * call. This function should return 0 upon success, non-zero upon failure.
2984 * @param destroy_tls
2985 * Destroy thread local storage. This function should expect two parameters:
2986 * ppkey and location. The ppkey parameter points to a variable containing a
2987 * thread local storage key previously provided by the create_tls
2988 * function. The location parameter can be used for debugging, as it
2989 * contains the compiler-provided __location__ of the call.
2992 * Set a thread local storage variable's value. This function should expect
2993 * three parameters: pkey, pval, and location. The pkey parameter is a
2994 * thread local storage key previously provided by the create_tls
2995 * function. The (void *) pval parameter contains the value to be placed in
2996 * the thread local storage variable identified by pkey. The location
2997 * parameter can be used for debugging, as it contains the compiler-provided
2998 * __location__ of the call. This function should return 0 upon success;
2999 * non-zero otherwise.
3002 * Retrieve a thread local storage variable's value. This function should
3003 * expect two parameters: pkey and location. The pkey parameter is a thread
3004 * local storage key previously provided by the create_tls function, and
3005 * which has previously been used in a call to the set_tls function to
3006 * initialize a thread local storage variable. The location parameter can be
3007 * used for debugging, as it contains the compiler-provided __location__ of
3008 * the call. This function should return the (void *) value stored in the
3009 * variable identified by pkey.
3015 /* Mutex functions. */
3016 int (*create_mutex
)(const char *lockname
,
3018 const char *location
),
3019 void (*destroy_mutex
)(void *plock
,
3020 const char *location
),
3021 int (*lock_mutex
)(void *plock
,
3023 const char *location
),
3025 /* Thread local storage. */
3026 int (*create_tls
)(const char *keyname
,
3028 const char *location
),
3029 void (*destroy_tls
)(void **ppkey
,
3030 const char *location
),
3031 int (*set_tls
)(void *pkey
,
3033 const char *location
),
3034 void *(*get_tls
)(void *pkey
,
3035 const char *location
)
3041 * @ingroup structure
3042 * Structure that contains a client context information
3043 * This structure is known as SMBCCTX
3045 * DO NOT DIRECTLY MANIPULATE THE CONTEXT STRUCTURE! The data in the context
3046 * structure should all be considered private to the library. It remains here
3047 * only for backward compatibility.
3049 * See the comments herein for use of the setter and getter functions which
3050 * should now be used for manipulating these values. New features, functions,
3051 * etc., are not added here but rather in _internal where they are not
3052 * directly visible to applications. This makes it much easier to maintain
3053 * ABI compatibility.
3061 * Use smbc_getDebug() and smbc_setDebug()
3063 int debug DEPRECATED_SMBC_INTERFACE
;
3066 * netbios name used for making connections
3069 * Use smbc_getNetbiosName() and smbc_setNetbiosName()
3071 char * netbios_name DEPRECATED_SMBC_INTERFACE
;
3074 * workgroup name used for making connections
3077 * Use smbc_getWorkgroup() and smbc_setWorkgroup()
3079 char * workgroup DEPRECATED_SMBC_INTERFACE
;
3082 * username used for making connections
3085 * Use smbc_getUser() and smbc_setUser()
3087 char * user DEPRECATED_SMBC_INTERFACE
;
3090 * timeout used for waiting on connections / response data (in
3094 * Use smbc_getTimeout() and smbc_setTimeout()
3096 int timeout DEPRECATED_SMBC_INTERFACE
;
3099 * callable functions for files:
3100 * For usage and return values see the SMBC_* functions
3104 * Use smbc_getFunction*() and smbc_setFunction*(), e.g.
3105 * smbc_getFunctionOpen(), smbc_setFunctionUnlink(), etc.
3107 smbc_open_fn open DEPRECATED_SMBC_INTERFACE
;
3108 smbc_creat_fn creat DEPRECATED_SMBC_INTERFACE
;
3109 smbc_read_fn read DEPRECATED_SMBC_INTERFACE
;
3110 smbc_write_fn write DEPRECATED_SMBC_INTERFACE
;
3111 smbc_unlink_fn unlink DEPRECATED_SMBC_INTERFACE
;
3112 smbc_rename_fn rename DEPRECATED_SMBC_INTERFACE
;
3113 smbc_lseek_fn lseek DEPRECATED_SMBC_INTERFACE
;
3114 smbc_stat_fn stat DEPRECATED_SMBC_INTERFACE
;
3115 smbc_fstat_fn fstat DEPRECATED_SMBC_INTERFACE
;
3116 #if 0 /* internal */
3117 smbc_ftruncate_fn ftruncate_fn
;
3119 smbc_close_fn close_fn DEPRECATED_SMBC_INTERFACE
;
3120 smbc_opendir_fn opendir DEPRECATED_SMBC_INTERFACE
;
3121 smbc_closedir_fn closedir DEPRECATED_SMBC_INTERFACE
;
3122 smbc_readdir_fn readdir DEPRECATED_SMBC_INTERFACE
;
3123 smbc_readdirplus_fn readdirplus DEPRECATED_SMBC_INTERFACE
;
3124 smbc_readdirplus2_fn readdirplus2 DEPRECATED_SMBC_INTERFACE
;
3125 smbc_getdents_fn getdents DEPRECATED_SMBC_INTERFACE
;
3126 smbc_mkdir_fn mkdir DEPRECATED_SMBC_INTERFACE
;
3127 smbc_rmdir_fn rmdir DEPRECATED_SMBC_INTERFACE
;
3128 smbc_telldir_fn telldir DEPRECATED_SMBC_INTERFACE
;
3129 smbc_lseekdir_fn lseekdir DEPRECATED_SMBC_INTERFACE
;
3130 smbc_fstatdir_fn fstatdir DEPRECATED_SMBC_INTERFACE
;
3131 smbc_chmod_fn chmod DEPRECATED_SMBC_INTERFACE
;
3132 smbc_utimes_fn utimes DEPRECATED_SMBC_INTERFACE
;
3133 smbc_setxattr_fn setxattr DEPRECATED_SMBC_INTERFACE
;
3134 smbc_getxattr_fn getxattr DEPRECATED_SMBC_INTERFACE
;
3135 smbc_removexattr_fn removexattr DEPRECATED_SMBC_INTERFACE
;
3136 smbc_listxattr_fn listxattr DEPRECATED_SMBC_INTERFACE
;
3138 /* Printing-related functions */
3139 smbc_print_file_fn print_file DEPRECATED_SMBC_INTERFACE
;
3140 smbc_open_print_job_fn open_print_job DEPRECATED_SMBC_INTERFACE
;
3141 smbc_list_print_jobs_fn list_print_jobs DEPRECATED_SMBC_INTERFACE
;
3142 smbc_unlink_print_job_fn unlink_print_job DEPRECATED_SMBC_INTERFACE
;
3149 * See the comment above each field, for the getter and setter
3150 * functions that should now be used.
3152 struct _smbc_callbacks
3155 * authentication function callback: called upon auth requests
3158 * Use smbc_getFunctionAuthData(), smbc_setFunctionAuthData()
3160 smbc_get_auth_data_fn auth_fn DEPRECATED_SMBC_INTERFACE
;
3163 * check if a server is still good
3166 * Use smbc_getFunctionCheckServer(),
3167 * smbc_setFunctionCheckServer()
3169 smbc_check_server_fn check_server_fn DEPRECATED_SMBC_INTERFACE
;
3172 * remove a server if unused
3175 * Use smbc_getFunctionRemoveUnusedServer(),
3176 * smbc_setFunctionCheckServer()
3178 smbc_remove_unused_server_fn remove_unused_server_fn DEPRECATED_SMBC_INTERFACE
;
3182 * For an example cache system see
3183 * samba/source/libsmb/libsmb_cache.c
3185 * Cache subsystem * functions follow.
3189 * server cache addition
3192 * Use smbc_getFunctionAddCachedServer(),
3193 * smbc_setFunctionAddCachedServer()
3195 smbc_add_cached_srv_fn add_cached_srv_fn DEPRECATED_SMBC_INTERFACE
;
3198 * server cache lookup
3201 * Use smbc_getFunctionGetCachedServer(),
3202 * smbc_setFunctionGetCachedServer()
3204 smbc_get_cached_srv_fn get_cached_srv_fn DEPRECATED_SMBC_INTERFACE
;
3207 * server cache removal
3210 * Use smbc_getFunctionRemoveCachedServer(),
3211 * smbc_setFunctionRemoveCachedServer()
3213 smbc_remove_cached_srv_fn remove_cached_srv_fn DEPRECATED_SMBC_INTERFACE
;
3216 * server cache purging, try to remove all cached servers
3220 * Use smbc_getFunctionPurgeCachedServers(),
3221 * smbc_setFunctionPurgeCachedServers()
3223 smbc_purge_cached_fn purge_cached_fn DEPRECATED_SMBC_INTERFACE
;
3227 * Space where the private data of the server cache used to be
3230 * Use smbc_getServerCacheData(), smbc_setServerCacheData()
3232 void * reserved DEPRECATED_SMBC_INTERFACE
;
3235 * Very old configuration options.
3238 * Use one of the following functions instead:
3239 * smbc_setOptionUseKerberos()
3240 * smbc_getOptionUseKerberos()
3241 * smbc_setOptionFallbackAfterKerberos()
3242 * smbc_getOptionFallbackAfterKerberos()
3243 * smbc_setOptionNoAutoAnonymousLogin()
3244 * smbc_getOptionNoAutoAnonymousLogin()
3246 int flags DEPRECATED_SMBC_INTERFACE
;
3249 * user options selections that apply to this session
3251 * NEW OPTIONS ARE NOT ADDED HERE!
3254 * To set and retrieve options, use the smbc_setOption*() and
3255 * smbc_getOption*() functions.
3257 struct _smbc_options
{
3258 int browse_max_lmb_count DEPRECATED_SMBC_INTERFACE
;
3259 int urlencode_readdir_entries DEPRECATED_SMBC_INTERFACE
;
3260 int one_share_per_server DEPRECATED_SMBC_INTERFACE
;
3261 } options DEPRECATED_SMBC_INTERFACE
;
3264 * do _NOT_ touch this from your program !
3266 struct SMBC_internal_data
* internal
;
3270 #endif /* SMBCLIENT_H_INCLUDED */