1 /*=====================================================================
2 Unix SMB/Netbios implementation.
3 SMB client library API definitions
4 Copyright (C) Andrew Tridgell 1998
5 Copyright (C) Richard Sharpe 2000
6 Copyright (C) John Terpsra 2000
7 Copyright (C) Tom Jansen (Ninja ISD) 2002
8 Copyright (C) Derrell Lipman 2003-2008
11 This program is free software; you can redistribute it and/or modify
12 it under the terms of the GNU General Public License as published by
13 the Free Software Foundation; either version 3 of the License, or
14 (at your option) any later version.
16 This program is distributed in the hope that it will be useful,
17 but WITHOUT ANY WARRANTY; without even the implied warranty of
18 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 GNU General Public License for more details.
21 You should have received a copy of the GNU General Public License
22 along with this program; if not, see <http://www.gnu.org/licenses/>.
23 =====================================================================*/
25 #ifndef SMBCLIENT_H_INCLUDED
26 #define SMBCLIENT_H_INCLUDED
28 #undef DEPRECATED_SMBC_INTERFACE
29 #if ! defined(__LIBSMBCLIENT_INTERNAL__) && defined(__GNUC__)
30 # define DEPRECATED_SMBC_INTERFACE __attribute__ ((deprecated))
32 # define DEPRECATED_SMBC_INTERFACE
39 /*-------------------------------------------------------------------*/
40 /* The following are special comments to instruct DOXYGEN (automated
43 /** \defgroup libsmbclient
45 /** \defgroup structure Data Structures Type and Constants
46 * \ingroup libsmbclient
47 * Data structures, types, and constants
49 /** \defgroup callback Callback function types
50 * \ingroup libsmbclient
53 /** \defgroup file File Functions
54 * \ingroup libsmbclient
55 * Functions used to access individual file contents
57 /** \defgroup directory Directory Functions
58 * \ingroup libsmbclient
59 * Functions used to access directory entries
61 /** \defgroup attribute Attributes Functions
62 * \ingroup libsmbclient
63 * Functions used to view or change file and directory attributes
65 /** \defgroup print Print Functions
66 * \ingroup libsmbclient
67 * Functions used to access printing functionality
69 /** \defgroup misc Miscellaneous Functions
70 * \ingroup libsmbclient
71 * Functions that don't fit in to other categories
73 /*-------------------------------------------------------------------*/
75 /* Make sure we have the following includes for now ... */
76 #include <sys/types.h>
78 #include <sys/statvfs.h>
83 #define SMBC_BASE_FD 10000 /* smallest file descriptor returned */
85 #define SMBC_WORKGROUP 1
87 #define SMBC_FILE_SHARE 3
88 #define SMBC_PRINTER_SHARE 4
89 #define SMBC_COMMS_SHARE 5
90 #define SMBC_IPC_SHARE 6
96 * Structure that represents a directory entry.
105 SMBC_PRINTER_SHARE=4,
111 unsigned int smbc_type
;
113 /** Length of this smbc_dirent in bytes
116 /** The length of the comment string in bytes (does not include
119 unsigned int commentlen
;
120 /** Points to the null terminated comment string
123 /** The length of the name string in bytes (does not include
126 unsigned int namelen
;
127 /** Points to the null terminated name string
133 * Flags for smbc_setxattr()
134 * Specify a bitwise OR of these, or 0 to add or replace as necessary
136 #define SMBC_XATTR_FLAG_CREATE 0x1 /* fail if attr already exists */
137 #define SMBC_XATTR_FLAG_REPLACE 0x2 /* fail if attr does not exist */
141 * Mappings of the DOS mode bits, as returned by smbc_getxattr() when the
142 * attribute name "system.dos_attr.mode" (or "system.dos_attr.*" or
143 * "system.*") is specified.
145 #define SMBC_DOS_MODE_READONLY 0x01
146 #define SMBC_DOS_MODE_HIDDEN 0x02
147 #define SMBC_DOS_MODE_SYSTEM 0x04
148 #define SMBC_DOS_MODE_VOLUME_ID 0x08
149 #define SMBC_DOS_MODE_DIRECTORY 0x10
150 #define SMBC_DOS_MODE_ARCHIVE 0x20
153 * Valid values for the option "open_share_mode", when calling
154 * smbc_setOptionOpenShareMode()
156 typedef enum smbc_share_mode
158 SMBC_SHAREMODE_DENY_DOS
= 0,
159 SMBC_SHAREMODE_DENY_ALL
= 1,
160 SMBC_SHAREMODE_DENY_WRITE
= 2,
161 SMBC_SHAREMODE_DENY_READ
= 3,
162 SMBC_SHAREMODE_DENY_NONE
= 4,
163 SMBC_SHAREMODE_DENY_FCB
= 7
168 * Values for option SMB Encryption Level, as set and retrieved with
169 * smbc_setOptionSmbEncryptionLevel() and smbc_getOptionSmbEncryptionLevel()
171 typedef enum smbc_smb_encrypt_level
173 SMBC_ENCRYPTLEVEL_NONE
= 0,
174 SMBC_ENCRYPTLEVEL_REQUEST
= 1,
175 SMBC_ENCRYPTLEVEL_REQUIRE
= 2
176 } smbc_smb_encrypt_level
;
180 * Capabilities set in the f_flag field of struct statvfs, from
181 * smbc_statvfs(). These may be OR-ed together to reflect a full set of
182 * available capabilities.
184 typedef enum smbc_vfs_feature
186 /* Defined by POSIX or in Linux include files (low-order bits) */
187 SMBC_VFS_FEATURE_RDONLY
= (1 << 0),
189 /* Specific to libsmbclient (high-order bits) */
190 SMBC_VFS_FEATURE_DFS
= (1 << 28),
191 SMBC_VFS_FEATURE_CASE_INSENSITIVE
= (1 << 29),
192 SMBC_VFS_FEATURE_NO_UNIXCIFS
= (1 << 30)
195 typedef int smbc_bool
;
199 # define ENOATTR ENOENT /* No such attribute */
205 /**@ingroup structure
206 * Structure that represents a print job.
210 struct print_job_info
212 /** numeric ID of the print job
216 /** represents print job priority (lower numbers mean higher priority)
218 unsigned short priority
;
220 /** Size of the print job
224 /** Name of the user that owns the print job
228 /** Name of the print job. This will have no name if an anonymous print
229 * file was opened. Ie smb://server/printer
233 /** Time the print job was spooled
237 #endif /* _CLIENT_H */
240 /**@ingroup structure
243 typedef struct _SMBCSRV SMBCSRV
;
245 /**@ingroup structure
246 * File or directory handle
248 typedef struct _SMBCFILE SMBCFILE
;
250 /**@ingroup structure
251 * File or directory handle
253 typedef struct _SMBCCTX SMBCCTX
;
257 * Flags for SMBCCTX->flags
259 * NEW CODE SHOULD NOT DIRECTLY MANIPULATE THE CONTEXT STRUCTURE.
261 * smbc_setOptionUseKerberos()
262 * smbc_getOptionUseKerberos()
263 * smbc_setOptionFallbackAfterKerberos()
264 * smbc_getOptionFallbackAFterKerberos()
265 * smbc_setOptionNoAutoAnonymousLogin()
266 * smbc_getOptionNoAutoAnonymousLogin()
267 * smbc_setOptionUseCCache()
268 * smbc_getOptionUseCCache()
270 # define SMB_CTX_FLAG_USE_KERBEROS (1 << 0)
271 # define SMB_CTX_FLAG_FALLBACK_AFTER_KERBEROS (1 << 1)
272 # define SMBCCTX_FLAG_NO_AUTO_ANONYMOUS_LOGON (1 << 2)
273 # define SMB_CTX_FLAG_USE_CCACHE (1 << 3)
278 * Authentication callback function type (traditional method)
280 * Type for the the authentication function called by the library to
281 * obtain authentication credentials
283 * For kerberos support the function should just be called without
284 * prompting the user for credentials. Which means a simple 'return'
285 * should work. Take a look at examples/libsmbclient/get_auth_data_fn.h
286 * and examples/libsmbclient/testbrowse.c.
288 * @param srv Server being authenticated to
290 * @param shr Share being authenticated to
292 * @param wg Pointer to buffer containing a "hint" for the
293 * workgroup to be authenticated. Should be filled in
294 * with the correct workgroup if the hint is wrong.
296 * @param wglen The size of the workgroup buffer in bytes
298 * @param un Pointer to buffer containing a "hint" for the
299 * user name to be use for authentication. Should be
300 * filled in with the correct workgroup if the hint is
303 * @param unlen The size of the username buffer in bytes
305 * @param pw Pointer to buffer containing to which password
308 * @param pwlen The size of the password buffer in bytes
311 typedef void (*smbc_get_auth_data_fn
)(const char *srv
,
315 char *pw
, int pwlen
);
317 * Authentication callback function type (method that includes context)
319 * Type for the the authentication function called by the library to
320 * obtain authentication credentials
322 * For kerberos support the function should just be called without
323 * prompting the user for credentials. Which means a simple 'return'
324 * should work. Take a look at examples/libsmbclient/get_auth_data_fn.h
325 * and examples/libsmbclient/testbrowse.c.
327 * @param c Pointer to the smb context
329 * @param srv Server being authenticated to
331 * @param shr Share being authenticated to
333 * @param wg Pointer to buffer containing a "hint" for the
334 * workgroup to be authenticated. Should be filled in
335 * with the correct workgroup if the hint is wrong.
337 * @param wglen The size of the workgroup buffer in bytes
339 * @param un Pointer to buffer containing a "hint" for the
340 * user name to be use for authentication. Should be
341 * filled in with the correct workgroup if the hint is
344 * @param unlen The size of the username buffer in bytes
346 * @param pw Pointer to buffer containing to which password
349 * @param pwlen The size of the password buffer in bytes
352 typedef void (*smbc_get_auth_data_with_context_fn
)(SMBCCTX
*c
,
357 char *pw
, int pwlen
);
361 * Print job info callback function type.
363 * @param i pointer to print job information structure
366 typedef void (*smbc_list_print_job_fn
)(struct print_job_info
*i
);
370 * Check if a server is still good
372 * @param c pointer to smb context
374 * @param srv pointer to server to check
376 * @return 0 when connection is good. 1 on error.
379 typedef int (*smbc_check_server_fn
)(SMBCCTX
* c
, SMBCSRV
*srv
);
382 * Remove a server if unused
384 * @param c pointer to smb context
386 * @param srv pointer to server to remove
388 * @return 0 on success. 1 on failure.
391 typedef int (*smbc_remove_unused_server_fn
)(SMBCCTX
* c
, SMBCSRV
*srv
);
395 * Add a server to the cache system
397 * @param c pointer to smb context
399 * @param srv pointer to server to add
401 * @param server server name
403 * @param share share name
405 * @param workgroup workgroup used to connect
407 * @param username username used to connect
409 * @return 0 on success. 1 on failure.
412 typedef int (*smbc_add_cached_srv_fn
) (SMBCCTX
* c
, SMBCSRV
*srv
,
413 const char * server
, const char * share
,
414 const char * workgroup
, const char * username
);
417 * Look up a server in the cache system
419 * @param c pointer to smb context
421 * @param server server name to match
423 * @param share share name to match
425 * @param workgroup workgroup to match
427 * @param username username to match
429 * @return pointer to SMBCSRV on success. NULL on failure.
432 typedef SMBCSRV
* (*smbc_get_cached_srv_fn
) (SMBCCTX
* c
, const char * server
,
433 const char * share
, const char * workgroup
,
434 const char * username
);
437 * Check if a server is still good
439 * @param c pointer to smb context
441 * @param srv pointer to server to remove
443 * @return 0 when found and removed. 1 on failure.
446 typedef int (*smbc_remove_cached_srv_fn
)(SMBCCTX
* c
, SMBCSRV
*srv
);
450 * Try to remove all servers from the cache system and disconnect
452 * @param c pointer to smb context
454 * @return 0 when found and removed. 1 on failure.
457 typedef int (*smbc_purge_cached_fn
) (SMBCCTX
* c
);
461 /*****************************************
462 * Getters and setters for CONFIGURATION *
463 *****************************************/
465 /** Get the debug level */
467 smbc_getDebug(SMBCCTX
*c
);
469 /** Set the debug level */
471 smbc_setDebug(SMBCCTX
*c
, int debug
);
473 /** Get the netbios name used for making connections */
475 smbc_getNetbiosName(SMBCCTX
*c
);
477 /** Set the netbios name used for making connections */
479 smbc_setNetbiosName(SMBCCTX
*c
, char * netbios_name
);
481 /** Get the workgroup used for making connections */
483 smbc_getWorkgroup(SMBCCTX
*c
);
485 /** Set the workgroup used for making connections */
486 void smbc_setWorkgroup(SMBCCTX
*c
, char * workgroup
);
488 /** Get the username used for making connections */
490 smbc_getUser(SMBCCTX
*c
);
492 /** Set the username used for making connections */
494 smbc_setUser(SMBCCTX
*c
, char * user
);
497 * Get the timeout used for waiting on connections and response data
501 smbc_getTimeout(SMBCCTX
*c
);
504 * Set the timeout used for waiting on connections and response data
508 smbc_setTimeout(SMBCCTX
*c
, int timeout
);
512 * Get the TCP port used to connect (0 means default).
515 smbc_getPort(SMBCCTX
*c
);
518 * Set the TCP port used to connect (0 means default).
521 smbc_setPort(SMBCCTX
*c
, uint16_t port
);
525 /***********************************
526 * Getters and setters for OPTIONS *
527 ***********************************/
529 /** Get whether to log to standard error instead of standard output */
531 smbc_getOptionDebugToStderr(SMBCCTX
*c
);
533 /** Set whether to log to standard error instead of standard output */
535 smbc_setOptionDebugToStderr(SMBCCTX
*c
, smbc_bool b
);
538 * Get whether to use new-style time attribute names, e.g. WRITE_TIME rather
539 * than the old-style names such as M_TIME. This allows also setting/getting
540 * CREATE_TIME which was previously unimplemented. (Note that the old C_TIME
541 * was supposed to be CHANGE_TIME but was confused and sometimes referred to
545 smbc_getOptionFullTimeNames(SMBCCTX
*c
);
548 * Set whether to use new-style time attribute names, e.g. WRITE_TIME rather
549 * than the old-style names such as M_TIME. This allows also setting/getting
550 * CREATE_TIME which was previously unimplemented. (Note that the old C_TIME
551 * was supposed to be CHANGE_TIME but was confused and sometimes referred to
555 smbc_setOptionFullTimeNames(SMBCCTX
*c
, smbc_bool b
);
558 * Get the share mode to use for files opened with SMBC_open_ctx(). The
559 * default is SMBC_SHAREMODE_DENY_NONE.
562 smbc_getOptionOpenShareMode(SMBCCTX
*c
);
565 * Set the share mode to use for files opened with SMBC_open_ctx(). The
566 * default is SMBC_SHAREMODE_DENY_NONE.
569 smbc_setOptionOpenShareMode(SMBCCTX
*c
, smbc_share_mode share_mode
);
571 /** Retrieve a previously saved user data handle */
573 smbc_getOptionUserData(SMBCCTX
*c
);
575 /** Save a user data handle */
577 smbc_setOptionUserData(SMBCCTX
*c
, void *user_data
);
579 /** Get the encoded value for encryption level. */
580 smbc_smb_encrypt_level
581 smbc_getOptionSmbEncryptionLevel(SMBCCTX
*c
);
583 /** Set the encoded value for encryption level. */
585 smbc_setOptionSmbEncryptionLevel(SMBCCTX
*c
, smbc_smb_encrypt_level level
);
588 * Get whether to treat file names as case-sensitive if we can't determine
589 * when connecting to the remote share whether the file system is case
590 * sensitive. This defaults to FALSE since it's most likely that if we can't
591 * retrieve the file system attributes, it's a very old file system that does
592 * not support case sensitivity.
595 smbc_getOptionCaseSensitive(SMBCCTX
*c
);
598 * Set whether to treat file names as case-sensitive if we can't determine
599 * when connecting to the remote share whether the file system is case
600 * sensitive. This defaults to FALSE since it's most likely that if we can't
601 * retrieve the file system attributes, it's a very old file system that does
602 * not support case sensitivity.
605 smbc_setOptionCaseSensitive(SMBCCTX
*c
, smbc_bool b
);
609 * Get from how many local master browsers should the list of workgroups be
610 * retrieved. It can take up to 12 minutes or longer after a server becomes a
611 * local master browser, for it to have the entire browse list (the list of
612 * workgroups/domains) from an entire network. Since a client never knows
613 * which local master browser will be found first, the one which is found
614 * first and used to retrieve a browse list may have an incomplete or empty
615 * browse list. By requesting the browse list from multiple local master
616 * browsers, a more complete list can be generated. For small networks (few
617 * workgroups), it is recommended that this value be set to 0, causing the
618 * browse lists from all found local master browsers to be retrieved and
619 * merged. For networks with many workgroups, a suitable value for this
620 * variable is probably somewhere around 3. (Default: 3).
623 smbc_getOptionBrowseMaxLmbCount(SMBCCTX
*c
);
626 * Set from how many local master browsers should the list of workgroups be
627 * retrieved. It can take up to 12 minutes or longer after a server becomes a
628 * local master browser, for it to have the entire browse list (the list of
629 * workgroups/domains) from an entire network. Since a client never knows
630 * which local master browser will be found first, the one which is found
631 * first and used to retrieve a browse list may have an incomplete or empty
632 * browse list. By requesting the browse list from multiple local master
633 * browsers, a more complete list can be generated. For small networks (few
634 * workgroups), it is recommended that this value be set to 0, causing the
635 * browse lists from all found local master browsers to be retrieved and
636 * merged. For networks with many workgroups, a suitable value for this
637 * variable is probably somewhere around 3. (Default: 3).
640 smbc_setOptionBrowseMaxLmbCount(SMBCCTX
*c
, int count
);
643 * Get whether to url-encode readdir entries.
645 * There is a difference in the desired return strings from
646 * smbc_readdir() depending upon whether the filenames are to
647 * be displayed to the user, or whether they are to be
648 * appended to the path name passed to smbc_opendir() to call
649 * a further smbc_ function (e.g. open the file with
650 * smbc_open()). In the former case, the filename should be
651 * in "human readable" form. In the latter case, the smbc_
652 * functions expect a URL which must be url-encoded. Those
653 * functions decode the URL. If, for example, smbc_readdir()
654 * returned a file name of "abc%20def.txt", passing a path
655 * with this file name attached to smbc_open() would cause
656 * smbc_open to attempt to open the file "abc def.txt" since
657 * the %20 is decoded into a space.
659 * Set this option to True if the names returned by
660 * smbc_readdir() should be url-encoded such that they can be
661 * passed back to another smbc_ call. Set it to False if the
662 * names returned by smbc_readdir() are to be presented to the
665 * For backwards compatibility, this option defaults to False.
668 smbc_getOptionUrlEncodeReaddirEntries(SMBCCTX
*c
);
671 * Set whether to url-encode readdir entries.
673 * There is a difference in the desired return strings from
674 * smbc_readdir() depending upon whether the filenames are to
675 * be displayed to the user, or whether they are to be
676 * appended to the path name passed to smbc_opendir() to call
677 * a further smbc_ function (e.g. open the file with
678 * smbc_open()). In the former case, the filename should be
679 * in "human readable" form. In the latter case, the smbc_
680 * functions expect a URL which must be url-encoded. Those
681 * functions decode the URL. If, for example, smbc_readdir()
682 * returned a file name of "abc%20def.txt", passing a path
683 * with this file name attached to smbc_open() would cause
684 * smbc_open to attempt to open the file "abc def.txt" since
685 * the %20 is decoded into a space.
687 * Set this option to True if the names returned by
688 * smbc_readdir() should be url-encoded such that they can be
689 * passed back to another smbc_ call. Set it to False if the
690 * names returned by smbc_readdir() are to be presented to the
693 * For backwards compatibility, this option defaults to False.
696 smbc_setOptionUrlEncodeReaddirEntries(SMBCCTX
*c
, smbc_bool b
);
699 * Get whether to use the same connection for all shares on a server.
701 * Some Windows versions appear to have a limit to the number
702 * of concurrent SESSIONs and/or TREE CONNECTions. In
703 * one-shot programs (i.e. the program runs and then quickly
704 * ends, thereby shutting down all connections), it is
705 * probably reasonable to establish a new connection for each
706 * share. In long-running applications, the limitation can be
707 * avoided by using only a single connection to each server,
708 * and issuing a new TREE CONNECT when the share is accessed.
711 smbc_getOptionOneSharePerServer(SMBCCTX
*c
);
714 * Set whether to use the same connection for all shares on a server.
716 * Some Windows versions appear to have a limit to the number
717 * of concurrent SESSIONs and/or TREE CONNECTions. In
718 * one-shot programs (i.e. the program runs and then quickly
719 * ends, thereby shutting down all connections), it is
720 * probably reasonable to establish a new connection for each
721 * share. In long-running applications, the limitation can be
722 * avoided by using only a single connection to each server,
723 * and issuing a new TREE CONNECT when the share is accessed.
726 smbc_setOptionOneSharePerServer(SMBCCTX
*c
, smbc_bool b
);
728 /** Get whether to enable use of kerberos */
730 smbc_getOptionUseKerberos(SMBCCTX
*c
);
732 /** Set whether to enable use of kerberos */
734 smbc_setOptionUseKerberos(SMBCCTX
*c
, smbc_bool b
);
736 /** Get whether to fallback after kerberos */
738 smbc_getOptionFallbackAfterKerberos(SMBCCTX
*c
);
740 /** Set whether to fallback after kerberos */
742 smbc_setOptionFallbackAfterKerberos(SMBCCTX
*c
, smbc_bool b
);
744 /** Get whether to automatically select anonymous login */
746 smbc_getOptionNoAutoAnonymousLogin(SMBCCTX
*c
);
748 /** Set whether to automatically select anonymous login */
750 smbc_setOptionNoAutoAnonymousLogin(SMBCCTX
*c
, smbc_bool b
);
752 /** Get whether to enable use of the winbind ccache */
754 smbc_getOptionUseCCache(SMBCCTX
*c
);
756 /** Set whether to enable use of the winbind ccache */
758 smbc_setOptionUseCCache(SMBCCTX
*c
, smbc_bool b
);
760 /** Get indication that the password supplied is the NT hash */
762 smbc_getOptionUseNTHash(SMBCCTX
*c
);
764 /** Set indication that the password supplied is the NT hash */
766 smbc_setOptionUseNTHash(SMBCCTX
*c
, smbc_bool b
);
770 /*************************************
771 * Getters and setters for FUNCTIONS *
772 *************************************/
774 /** Get the function for obtaining authentication data */
775 smbc_get_auth_data_fn
smbc_getFunctionAuthData(SMBCCTX
*c
);
777 /** Set the function for obtaining authentication data */
778 void smbc_setFunctionAuthData(SMBCCTX
*c
, smbc_get_auth_data_fn fn
);
780 /** Get the new-style authentication function which includes the context. */
781 smbc_get_auth_data_with_context_fn
782 smbc_getFunctionAuthDataWithContext(SMBCCTX
*c
);
784 /** Set the new-style authentication function which includes the context. */
786 smbc_setFunctionAuthDataWithContext(SMBCCTX
*c
,
787 smbc_get_auth_data_with_context_fn fn
);
789 /** Get the function for checking if a server is still good */
790 smbc_check_server_fn
smbc_getFunctionCheckServer(SMBCCTX
*c
);
792 /** Set the function for checking if a server is still good */
793 void smbc_setFunctionCheckServer(SMBCCTX
*c
, smbc_check_server_fn fn
);
795 /** Get the function for removing a server if unused */
796 smbc_remove_unused_server_fn
smbc_getFunctionRemoveUnusedServer(SMBCCTX
*c
);
798 /** Set the function for removing a server if unused */
799 void smbc_setFunctionRemoveUnusedServer(SMBCCTX
*c
,
800 smbc_remove_unused_server_fn fn
);
802 /** Get the function for adding a cached server */
803 smbc_add_cached_srv_fn
smbc_getFunctionAddCachedServer(SMBCCTX
*c
);
805 /** Set the function for adding a cached server */
806 void smbc_setFunctionAddCachedServer(SMBCCTX
*c
, smbc_add_cached_srv_fn fn
);
808 /** Get the function for server cache lookup */
809 smbc_get_cached_srv_fn
smbc_getFunctionGetCachedServer(SMBCCTX
*c
);
811 /** Set the function for server cache lookup */
812 void smbc_setFunctionGetCachedServer(SMBCCTX
*c
, smbc_get_cached_srv_fn fn
);
814 /** Get the function for server cache removal */
815 smbc_remove_cached_srv_fn
smbc_getFunctionRemoveCachedServer(SMBCCTX
*c
);
817 /** Set the function for server cache removal */
818 void smbc_setFunctionRemoveCachedServer(SMBCCTX
*c
,
819 smbc_remove_cached_srv_fn fn
);
822 * Get the function for server cache purging. This function tries to
823 * remove all cached servers (e.g. on disconnect)
825 smbc_purge_cached_fn
smbc_getFunctionPurgeCachedServers(SMBCCTX
*c
);
828 * Set the function for server cache purging. This function tries to
829 * remove all cached servers (e.g. on disconnect)
831 void smbc_setFunctionPurgeCachedServers(SMBCCTX
*c
,
832 smbc_purge_cached_fn fn
);
834 /** Get the function to store private data of the server cache */
835 struct smbc_server_cache
* smbc_getServerCacheData(SMBCCTX
*c
);
837 /** Set the function to store private data of the server cache */
838 void smbc_setServerCacheData(SMBCCTX
*c
, struct smbc_server_cache
* cache
);
842 /*****************************************************************
843 * Callable functions for files. *
844 * Each callable has a function signature typedef, a declaration *
845 * for the getter, and a declaration for the setter. *
846 *****************************************************************/
848 typedef SMBCFILE
* (*smbc_open_fn
)(SMBCCTX
*c
,
852 smbc_open_fn
smbc_getFunctionOpen(SMBCCTX
*c
);
853 void smbc_setFunctionOpen(SMBCCTX
*c
, smbc_open_fn fn
);
855 typedef SMBCFILE
* (*smbc_creat_fn
)(SMBCCTX
*c
,
858 smbc_creat_fn
smbc_getFunctionCreat(SMBCCTX
*c
);
859 void smbc_setFunctionCreat(SMBCCTX
*c
, smbc_creat_fn
);
861 typedef ssize_t (*smbc_read_fn
)(SMBCCTX
*c
,
865 smbc_read_fn
smbc_getFunctionRead(SMBCCTX
*c
);
866 void smbc_setFunctionRead(SMBCCTX
*c
, smbc_read_fn fn
);
868 typedef ssize_t (*smbc_write_fn
)(SMBCCTX
*c
,
872 smbc_write_fn
smbc_getFunctionWrite(SMBCCTX
*c
);
873 void smbc_setFunctionWrite(SMBCCTX
*c
, smbc_write_fn fn
);
875 typedef off_t (*smbc_splice_fn
)(SMBCCTX
*c
,
879 int (*splice_cb
)(off_t n
, void *priv
),
881 smbc_splice_fn
smbc_getFunctionSplice(SMBCCTX
*c
);
882 void smbc_setFunctionSplice(SMBCCTX
*c
, smbc_splice_fn fn
);
884 typedef int (*smbc_unlink_fn
)(SMBCCTX
*c
,
886 smbc_unlink_fn
smbc_getFunctionUnlink(SMBCCTX
*c
);
887 void smbc_setFunctionUnlink(SMBCCTX
*c
, smbc_unlink_fn fn
);
889 typedef int (*smbc_rename_fn
)(SMBCCTX
*ocontext
,
893 smbc_rename_fn
smbc_getFunctionRename(SMBCCTX
*c
);
894 void smbc_setFunctionRename(SMBCCTX
*c
, smbc_rename_fn fn
);
896 typedef off_t (*smbc_lseek_fn
)(SMBCCTX
*c
,
900 smbc_lseek_fn
smbc_getFunctionLseek(SMBCCTX
*c
);
901 void smbc_setFunctionLseek(SMBCCTX
*c
, smbc_lseek_fn fn
);
903 typedef int (*smbc_stat_fn
)(SMBCCTX
*c
,
906 smbc_stat_fn
smbc_getFunctionStat(SMBCCTX
*c
);
907 void smbc_setFunctionStat(SMBCCTX
*c
, smbc_stat_fn fn
);
909 typedef int (*smbc_fstat_fn
)(SMBCCTX
*c
,
912 smbc_fstat_fn
smbc_getFunctionFstat(SMBCCTX
*c
);
913 void smbc_setFunctionFstat(SMBCCTX
*c
, smbc_fstat_fn fn
);
915 typedef int (*smbc_statvfs_fn
)(SMBCCTX
*c
,
918 smbc_statvfs_fn
smbc_getFunctionStatVFS(SMBCCTX
*c
);
919 void smbc_setFunctionStatVFS(SMBCCTX
*c
, smbc_statvfs_fn fn
);
921 typedef int (*smbc_fstatvfs_fn
)(SMBCCTX
*c
,
924 smbc_fstatvfs_fn
smbc_getFunctionFstatVFS(SMBCCTX
*c
);
925 void smbc_setFunctionFstatVFS(SMBCCTX
*c
, smbc_fstatvfs_fn fn
);
927 typedef int (*smbc_ftruncate_fn
)(SMBCCTX
*c
,
930 smbc_ftruncate_fn
smbc_getFunctionFtruncate(SMBCCTX
*c
);
931 void smbc_setFunctionFtruncate(SMBCCTX
*c
, smbc_ftruncate_fn fn
);
933 typedef int (*smbc_close_fn
)(SMBCCTX
*c
,
935 smbc_close_fn
smbc_getFunctionClose(SMBCCTX
*c
);
936 void smbc_setFunctionClose(SMBCCTX
*c
, smbc_close_fn fn
);
940 /*****************************************************************
941 * Callable functions for directories. *
942 * Each callable has a function signature typedef, a declaration *
943 * for the getter, and a declaration for the setter. *
944 *****************************************************************/
946 typedef SMBCFILE
* (*smbc_opendir_fn
)(SMBCCTX
*c
,
948 smbc_opendir_fn
smbc_getFunctionOpendir(SMBCCTX
*c
);
949 void smbc_setFunctionOpendir(SMBCCTX
*c
, smbc_opendir_fn fn
);
951 typedef int (*smbc_closedir_fn
)(SMBCCTX
*c
,
953 smbc_closedir_fn
smbc_getFunctionClosedir(SMBCCTX
*c
);
954 void smbc_setFunctionClosedir(SMBCCTX
*c
, smbc_closedir_fn fn
);
956 typedef struct smbc_dirent
* (*smbc_readdir_fn
)(SMBCCTX
*c
,
958 smbc_readdir_fn
smbc_getFunctionReaddir(SMBCCTX
*c
);
959 void smbc_setFunctionReaddir(SMBCCTX
*c
, smbc_readdir_fn fn
);
961 typedef int (*smbc_getdents_fn
)(SMBCCTX
*c
,
963 struct smbc_dirent
*dirp
,
965 smbc_getdents_fn
smbc_getFunctionGetdents(SMBCCTX
*c
);
966 void smbc_setFunctionGetdents(SMBCCTX
*c
, smbc_getdents_fn fn
);
968 typedef int (*smbc_mkdir_fn
)(SMBCCTX
*c
,
971 smbc_mkdir_fn
smbc_getFunctionMkdir(SMBCCTX
*c
);
972 void smbc_setFunctionMkdir(SMBCCTX
*c
, smbc_mkdir_fn fn
);
974 typedef int (*smbc_rmdir_fn
)(SMBCCTX
*c
,
976 smbc_rmdir_fn
smbc_getFunctionRmdir(SMBCCTX
*c
);
977 void smbc_setFunctionRmdir(SMBCCTX
*c
, smbc_rmdir_fn fn
);
979 typedef off_t (*smbc_telldir_fn
)(SMBCCTX
*c
,
981 smbc_telldir_fn
smbc_getFunctionTelldir(SMBCCTX
*c
);
982 void smbc_setFunctionTelldir(SMBCCTX
*c
, smbc_telldir_fn fn
);
984 typedef int (*smbc_lseekdir_fn
)(SMBCCTX
*c
,
987 smbc_lseekdir_fn
smbc_getFunctionLseekdir(SMBCCTX
*c
);
988 void smbc_setFunctionLseekdir(SMBCCTX
*c
, smbc_lseekdir_fn fn
);
990 typedef int (*smbc_fstatdir_fn
)(SMBCCTX
*c
,
993 smbc_fstatdir_fn
smbc_getFunctionFstatdir(SMBCCTX
*c
);
994 void smbc_setFunctionFstatdir(SMBCCTX
*c
, smbc_fstatdir_fn fn
);
996 #define SMBC_NOTIFY_ACTION_ADDED 1
997 #define SMBC_NOTIFY_ACTION_REMOVED 2
998 #define SMBC_NOTIFY_ACTION_MODIFIED 3
999 #define SMBC_NOTIFY_ACTION_OLD_NAME 4
1000 #define SMBC_NOTIFY_ACTION_NEW_NAME 5
1001 #define SMBC_NOTIFY_ACTION_ADDED_STREAM 6
1002 #define SMBC_NOTIFY_ACTION_REMOVED_STREAM 7
1003 #define SMBC_NOTIFY_ACTION_MODIFIED_STREAM 8
1005 struct smbc_notify_callback_action
{
1007 const char *filename
;
1010 typedef int (*smbc_notify_callback_fn
)(
1011 const struct smbc_notify_callback_action
*actions
,
1012 size_t num_actions
, void *private_data
);
1014 typedef int (*smbc_notify_fn
)(SMBCCTX
*c
, SMBCFILE
*dir
, smbc_bool recursive
,
1015 uint32_t completion_filter
,
1016 unsigned callback_timeout_ms
,
1017 smbc_notify_callback_fn cb
, void *private_data
);
1018 smbc_notify_fn
smbc_getFunctionNotify(SMBCCTX
*c
);
1019 void smbc_setFunctionNotify(SMBCCTX
*c
, smbc_notify_fn fn
);
1022 /*****************************************************************
1023 * Callable functions applicable to both files and directories. *
1024 * Each callable has a function signature typedef, a declaration *
1025 * for the getter, and a declaration for the setter. *
1026 *****************************************************************/
1028 typedef int (*smbc_chmod_fn
)(SMBCCTX
*c
,
1031 smbc_chmod_fn
smbc_getFunctionChmod(SMBCCTX
*c
);
1032 void smbc_setFunctionChmod(SMBCCTX
*c
, smbc_chmod_fn fn
);
1034 typedef int (*smbc_utimes_fn
)(SMBCCTX
*c
,
1036 struct timeval
*tbuf
);
1037 smbc_utimes_fn
smbc_getFunctionUtimes(SMBCCTX
*c
);
1038 void smbc_setFunctionUtimes(SMBCCTX
*c
, smbc_utimes_fn fn
);
1040 typedef int (*smbc_setxattr_fn
)(SMBCCTX
*context
,
1046 smbc_setxattr_fn
smbc_getFunctionSetxattr(SMBCCTX
*c
);
1047 void smbc_setFunctionSetxattr(SMBCCTX
*c
, smbc_setxattr_fn fn
);
1049 typedef int (*smbc_getxattr_fn
)(SMBCCTX
*context
,
1054 smbc_getxattr_fn
smbc_getFunctionGetxattr(SMBCCTX
*c
);
1055 void smbc_setFunctionGetxattr(SMBCCTX
*c
, smbc_getxattr_fn fn
);
1057 typedef int (*smbc_removexattr_fn
)(SMBCCTX
*context
,
1060 smbc_removexattr_fn
smbc_getFunctionRemovexattr(SMBCCTX
*c
);
1061 void smbc_setFunctionRemovexattr(SMBCCTX
*c
, smbc_removexattr_fn fn
);
1063 typedef int (*smbc_listxattr_fn
)(SMBCCTX
*context
,
1067 smbc_listxattr_fn
smbc_getFunctionListxattr(SMBCCTX
*c
);
1068 void smbc_setFunctionListxattr(SMBCCTX
*c
, smbc_listxattr_fn fn
);
1072 /*****************************************************************
1073 * Callable functions for printing. *
1074 * Each callable has a function signature typedef, a declaration *
1075 * for the getter, and a declaration for the setter. *
1076 *****************************************************************/
1078 typedef int (*smbc_print_file_fn
)(SMBCCTX
*c_file
,
1081 const char *printq
);
1082 smbc_print_file_fn
smbc_getFunctionPrintFile(SMBCCTX
*c
);
1083 void smbc_setFunctionPrintFile(SMBCCTX
*c
, smbc_print_file_fn fn
);
1085 typedef SMBCFILE
* (*smbc_open_print_job_fn
)(SMBCCTX
*c
,
1087 smbc_open_print_job_fn
smbc_getFunctionOpenPrintJob(SMBCCTX
*c
);
1088 void smbc_setFunctionOpenPrintJob(SMBCCTX
*c
,
1089 smbc_open_print_job_fn fn
);
1091 typedef int (*smbc_list_print_jobs_fn
)(SMBCCTX
*c
,
1093 smbc_list_print_job_fn fn
);
1094 smbc_list_print_jobs_fn
smbc_getFunctionListPrintJobs(SMBCCTX
*c
);
1095 void smbc_setFunctionListPrintJobs(SMBCCTX
*c
,
1096 smbc_list_print_jobs_fn fn
);
1098 typedef int (*smbc_unlink_print_job_fn
)(SMBCCTX
*c
,
1101 smbc_unlink_print_job_fn
smbc_getFunctionUnlinkPrintJob(SMBCCTX
*c
);
1102 void smbc_setFunctionUnlinkPrintJob(SMBCCTX
*c
,
1103 smbc_unlink_print_job_fn fn
);
1107 * Create a new SBMCCTX (a context).
1109 * Must be called before the context is passed to smbc_context_init()
1111 * @return The given SMBCCTX pointer on success, NULL on error with errno set:
1112 * - ENOMEM Out of memory
1114 * @see smbc_free_context(), smbc_init_context()
1116 * @note Do not forget to smbc_init_context() the returned SMBCCTX pointer !
1118 SMBCCTX
* smbc_new_context(void);
1121 * Delete a SBMCCTX (a context) acquired from smbc_new_context().
1123 * The context will be deleted if possible.
1125 * @param context A pointer to a SMBCCTX obtained from smbc_new_context()
1127 * @param shutdown_ctx If 1, all connections and files will be closed even if they are busy.
1130 * @return Returns 0 on succes. Returns 1 on failure with errno set:
1131 * - EBUSY Server connections are still used, Files are open or cache
1132 * could not be purged
1133 * - EBADF context == NULL
1135 * @see smbc_new_context()
1137 * @note It is advised to clean up all the contexts with shutdown_ctx set to 1
1138 * just before exit()'ing. When shutdown_ctx is 0, this function can be
1139 * use in periodical cleanup functions for example.
1141 int smbc_free_context(SMBCCTX
* context
, int shutdown_ctx
);
1146 * @deprecated. Use smbc_setOption*() functions instead.
1149 smbc_option_set(SMBCCTX
*context
,
1151 ... /* option_value */);
1154 * @deprecated. Use smbc_getOption*() functions instead.
1157 smbc_option_get(SMBCCTX
*context
,
1161 * Initialize a SBMCCTX (a context).
1163 * Must be called before using any SMBCCTX API function
1165 * @param context A pointer to a SMBCCTX obtained from smbc_new_context()
1167 * @return A pointer to the given SMBCCTX on success,
1168 * NULL on error with errno set:
1169 * - EBADF NULL context given
1170 * - ENOMEM Out of memory
1171 * - ENOENT The smb.conf file would not load
1173 * @see smbc_new_context()
1175 * @note my_context = smbc_init_context(smbc_new_context())
1176 * is perfectly safe, but it might leak memory on
1177 * smbc_context_init() failure. Avoid this.
1178 * You'll have to call smbc_free_context() yourself
1182 SMBCCTX
* smbc_init_context(SMBCCTX
* context
);
1185 * Initialize the samba client library.
1187 * Must be called before using any of the smbclient API function
1189 * @param fn The function that will be called to obtaion
1190 * authentication credentials.
1192 * @param debug Allows caller to set the debug level. Can be
1193 * changed in smb.conf file. Allows caller to set
1194 * debugging if no smb.conf.
1196 * @return 0 on success, < 0 on error with errno set:
1197 * - ENOMEM Out of memory
1198 * - ENOENT The smb.conf file would not load
1202 int smbc_init(smbc_get_auth_data_fn fn
, int debug
);
1205 * Set or retrieve the compatibility library's context pointer
1207 * @param context New context to use, or NULL. If a new context is provided,
1208 * it must have allocated with smbc_new_context() and
1209 * initialized with smbc_init_context(), followed, optionally,
1210 * by some manual changes to some of the non-internal fields.
1212 * @return The old context.
1214 * @see smbc_new_context(), smbc_init_context(), smbc_init()
1216 * @note This function may be called prior to smbc_init() to force
1217 * use of the next context without any internal calls to
1218 * smbc_new_context() or smbc_init_context(). It may also
1219 * be called after smbc_init() has already called those two
1220 * functions, to replace the existing context with a new one.
1221 * Care should be taken, in this latter case, to ensure that
1222 * the server cache and any data allocated by the
1223 * authentication functions have been freed, if necessary.
1226 SMBCCTX
* smbc_set_context(SMBCCTX
* new_context
);
1229 * Open a file on an SMB server.
1231 * @param furl The smb url of the file to be opened.
1233 * @param flags Is one of O_RDONLY, O_WRONLY or O_RDWR which
1234 * request opening the file read-only,write-only
1235 * or read/write. flags may also be bitwise-or'd with
1236 * one or more of the following:
1237 * O_CREAT - If the file does not exist it will be
1239 * O_EXCL - When used with O_CREAT, if the file
1240 * already exists it is an error and the open will
1242 * O_TRUNC - If the file already exists it will be
1244 * O_APPEND The file is opened in append mode
1246 * @param mode mode specifies the permissions to use if a new
1247 * file is created. It is modified by the
1248 * process's umask in the usual way: the permissions
1249 * of the created file are (mode & ~umask)
1251 * Not currently use, but there for future use.
1252 * We will map this to SYSTEM, HIDDEN, etc bits
1253 * that reverses the mapping that smbc_fstat does.
1255 * @return Valid file handle, < 0 on error with errno set:
1256 * - ENOMEM Out of memory
1257 * - EINVAL if an invalid parameter passed, like no
1258 * file, or smbc_init not called.
1259 * - EEXIST pathname already exists and O_CREAT and
1261 * - EISDIR pathname refers to a directory and
1262 * the access requested involved writing.
1263 * - EACCES The requested access to the file is not
1265 * - ENODEV The requested share does not exist
1266 * - ENOTDIR A file on the path is not a directory
1267 * - ENOENT A directory component in pathname does
1272 * @note This call uses an underlying routine that may create
1273 * a new connection to the server specified in the URL.
1274 * If the credentials supplied in the URL, or via the
1275 * auth_fn in the smbc_init call, fail, this call will
1276 * try again with an empty username and password. This
1277 * often gets mapped to the guest account on some machines.
1280 int smbc_open(const char *furl
, int flags
, mode_t mode
);
1283 * Create a file on an SMB server.
1285 * Same as calling smbc_open() with flags = O_CREAT|O_WRONLY|O_TRUNC
1287 * @param furl The smb url of the file to be created
1289 * @param mode mode specifies the permissions to use if a new
1290 * file is created. It is modified by the
1291 * process's umask in the usual way: the permissions
1292 * of the created file are (mode & ~umask)
1294 * NOTE, the above is not true. We are dealing with
1295 * an SMB server, which has no concept of a umask!
1297 * @return Valid file handle, < 0 on error with errno set:
1298 * - ENOMEM Out of memory
1299 * - EINVAL if an invalid parameter passed, like no
1300 * file, or smbc_init not called.
1301 * - EEXIST pathname already exists and O_CREAT and
1303 * - EISDIR pathname refers to a directory and
1304 * the access requested involved writing.
1305 * - EACCES The requested access to the file is not
1307 * - ENOENT A directory component in pathname does
1309 * - ENODEV The requested share does not exist.
1314 int smbc_creat(const char *furl
, mode_t mode
);
1317 * Read from a file using an opened file handle.
1319 * @param fd Open file handle from smbc_open() or smbc_creat()
1321 * @param buf Pointer to buffer to receive read data
1323 * @param bufsize Size of buf in bytes
1325 * @return Number of bytes read;
1327 * < 0 on error, with errno set:
1328 * - EISDIR fd refers to a directory
1329 * - EBADF fd is not a valid file descriptor or
1330 * is not open for reading.
1331 * - EINVAL fd is attached to an object which is
1332 * unsuitable for reading, or no buffer passed or
1333 * smbc_init not called.
1335 * @see smbc_open(), smbc_write()
1338 ssize_t
smbc_read(int fd
, void *buf
, size_t bufsize
);
1342 * Write to a file using an opened file handle.
1344 * @param fd Open file handle from smbc_open() or smbc_creat()
1346 * @param buf Pointer to buffer to recieve read data
1348 * @param bufsize Size of buf in bytes
1350 * @return Number of bytes written, < 0 on error with errno set:
1351 * - EISDIR fd refers to a directory.
1352 * - EBADF fd is not a valid file descriptor or
1353 * is not open for reading.
1354 * - EINVAL fd is attached to an object which is
1355 * unsuitable for reading, or no buffer passed or
1356 * smbc_init not called.
1358 * @see smbc_open(), smbc_read()
1361 ssize_t
smbc_write(int fd
, const void *buf
, size_t bufsize
);
1365 * Seek to a specific location in a file.
1367 * @param fd Open file handle from smbc_open() or smbc_creat()
1369 * @param offset Offset in bytes from whence
1371 * @param whence A location in the file:
1372 * - SEEK_SET The offset is set to offset bytes from
1373 * the beginning of the file
1374 * - SEEK_CUR The offset is set to current location
1375 * plus offset bytes.
1376 * - SEEK_END The offset is set to the size of the
1377 * file plus offset bytes.
1379 * @return Upon successful completion, lseek returns the
1380 * resulting offset location as measured in bytes
1381 * from the beginning of the file. Otherwise, a value
1382 * of (off_t)-1 is returned and errno is set to
1383 * indicate the error:
1384 * - EBADF Fildes is not an open file descriptor.
1385 * - EINVAL Whence is not a proper value or smbc_init
1388 * @todo Are all the whence values really supported?
1390 * @todo Are errno values complete and correct?
1392 off_t
smbc_lseek(int fd
, off_t offset
, int whence
);
1396 * Close an open file handle.
1398 * @param fd The file handle to close
1400 * @return 0 on success, < 0 on error with errno set:
1401 * - EBADF fd isn't a valid open file descriptor
1402 * - EINVAL smbc_init() failed or has not been called
1404 * @see smbc_open(), smbc_creat()
1406 int smbc_close(int fd
);
1409 /**@ingroup directory
1410 * Unlink (delete) a file or directory.
1412 * @param furl The smb url of the file to delete
1414 * @return 0 on success, < 0 on error with errno set:
1415 * - EACCES or EPERM Write access to the directory
1416 * containing pathname is not allowed or one
1417 * of the directories in pathname did not allow
1418 * search (execute) permission
1419 * - ENOENT A directory component in pathname does
1421 * - EINVAL NULL was passed in the file param or
1422 * smbc_init not called.
1423 * - EACCES You do not have access to the file
1424 * - ENOMEM Insufficient kernel memory was available
1426 * @see smbc_rmdir()s
1428 * @todo Are errno values complete and correct?
1430 int smbc_unlink(const char *furl
);
1433 /**@ingroup directory
1434 * Rename or move a file or directory.
1436 * @param ourl The original smb url (source url) of file or
1437 * directory to be moved
1439 * @param nurl The new smb url (destination url) of the file
1440 * or directory after the move. Currently nurl must
1441 * be on the same share as ourl.
1443 * @return 0 on success, < 0 on error with errno set:
1444 * - EISDIR nurl is an existing directory, but ourl is
1446 * - EEXIST nurl is a non-empty directory,
1447 * i.e., contains entries other than "." and ".."
1448 * - EINVAL The new url contained a path prefix
1449 * of the old, or, more generally, an attempt was
1450 * made to make a directory a subdirectory of itself
1451 * or smbc_init not called.
1452 * - ENOTDIR A component used as a directory in ourl
1453 * or nurl path is not, in fact, a directory. Or,
1454 * ourl is a directory, and newpath exists but is not
1456 * - EACCES or EPERM Write access to the directory
1457 * containing ourl or nurl is not allowed for the
1458 * process's effective uid, or one of the
1459 * directories in ourl or nurl did not allow search
1460 * (execute) permission, or ourl was a directory
1461 * and did not allow write permission.
1462 * - ENOENT A directory component in ourl or nurl
1464 * - EXDEV Rename across shares not supported.
1465 * - ENOMEM Insufficient kernel memory was available.
1466 * - EEXIST The target file, nurl, already exists.
1469 * @todo Are we going to support copying when urls are not on the same
1470 * share? I say no... NOTE. I agree for the moment.
1473 int smbc_rename(const char *ourl
, const char *nurl
);
1476 /**@ingroup directory
1477 * Open a directory used to obtain directory entries.
1479 * @param durl The smb url of the directory to open
1481 * @return Valid directory handle. < 0 on error with errno set:
1482 * - EACCES Permission denied.
1483 * - EINVAL A NULL file/URL was passed, or the URL would
1484 * not parse, or was of incorrect form or smbc_init not
1486 * - ENOENT durl does not exist, or name is an
1487 * - ENOMEM Insufficient memory to complete the
1489 * - ENOTDIR name is not a directory.
1490 * - EPERM the workgroup could not be found.
1491 * - ENODEV the workgroup or server could not be found.
1493 * @see smbc_getdents(), smbc_readdir(), smbc_closedir()
1496 int smbc_opendir(const char *durl
);
1499 /**@ingroup directory
1500 * Close a directory handle opened by smbc_opendir().
1502 * @param dh Directory handle to close
1504 * @return 0 on success, < 0 on error with errno set:
1505 * - EBADF dh is an invalid directory handle
1507 * @see smbc_opendir()
1509 int smbc_closedir(int dh
);
1512 /**@ingroup directory
1513 * Get multiple directory entries.
1515 * smbc_getdents() reads as many dirent structures from the an open
1516 * directory handle into a specified memory area as will fit.
1518 * @param dh Valid directory as returned by smbc_opendir()
1520 * @param dirp pointer to buffer that will receive the directory
1523 * @param count The size of the dirp buffer in bytes
1525 * @returns If any dirents returned, return will indicate the
1526 * total size. If there were no more dirents available,
1527 * 0 is returned. < 0 indicates an error.
1528 * - EBADF Invalid directory handle
1529 * - EINVAL Result buffer is too small or smbc_init
1531 * - ENOENT No such directory.
1532 * @see , smbc_dirent, smbc_readdir(), smbc_open()
1534 * @todo Are errno values complete and correct?
1536 * @todo Add example code so people know how to parse buffers.
1538 int smbc_getdents(unsigned int dh
, struct smbc_dirent
*dirp
, int count
);
1541 /**@ingroup directory
1542 * Get a single directory entry.
1544 * @param dh Valid directory as returned by smbc_opendir()
1546 * @return A pointer to a smbc_dirent structure, or NULL if an
1547 * error occurs or end-of-directory is reached:
1548 * - EBADF Invalid directory handle
1549 * - EINVAL smbc_init() failed or has not been called
1551 * @see smbc_dirent, smbc_getdents(), smbc_open()
1553 struct smbc_dirent
* smbc_readdir(unsigned int dh
);
1556 /**@ingroup directory
1557 * Get the current directory offset.
1559 * smbc_telldir() may be used in conjunction with smbc_readdir() and
1562 * @param dh Valid directory as returned by smbc_opendir()
1564 * @return The current location in the directory stream or -1
1565 * if an error occur. The current location is not
1566 * an offset. Becuase of the implementation, it is a
1567 * handle that allows the library to find the entry
1569 * - EBADF dh is not a valid directory handle
1570 * - EINVAL smbc_init() failed or has not been called
1571 * - ENOTDIR if dh is not a directory
1573 * @see smbc_readdir()
1576 off_t
smbc_telldir(int dh
);
1579 /**@ingroup directory
1580 * lseek on directories.
1582 * smbc_lseekdir() may be used in conjunction with smbc_readdir() and
1583 * smbc_telldir(). (rewind by smbc_lseekdir(fd, NULL))
1585 * @param fd Valid directory as returned by smbc_opendir()
1587 * @param offset The offset (as returned by smbc_telldir). Can be
1588 * NULL, in which case we will rewind
1590 * @return 0 on success, -1 on failure
1591 * - EBADF dh is not a valid directory handle
1592 * - ENOTDIR if dh is not a directory
1593 * - EINVAL offset did not refer to a valid dirent or
1594 * smbc_init not called.
1596 * @see smbc_telldir()
1599 * @todo In what does the reture and errno values mean?
1601 int smbc_lseekdir(int fd
, off_t offset
);
1603 /**@ingroup directory
1604 * Create a directory.
1606 * @param durl The url of the directory to create
1608 * @param mode Specifies the permissions to use. It is modified
1609 * by the process's umask in the usual way: the
1610 * permissions of the created file are (mode & ~umask).
1612 * @return 0 on success, < 0 on error with errno set:
1613 * - EEXIST directory url already exists
1614 * - EACCES The parent directory does not allow write
1615 * permission to the process, or one of the directories
1616 * - ENOENT A directory component in pathname does not
1618 * - EINVAL NULL durl passed or smbc_init not called.
1619 * - ENOMEM Insufficient memory was available.
1624 int smbc_mkdir(const char *durl
, mode_t mode
);
1627 /**@ingroup directory
1628 * Remove a directory.
1630 * @param durl The smb url of the directory to remove
1632 * @return 0 on success, < 0 on error with errno set:
1633 * - EACCES or EPERM Write access to the directory
1634 * containing pathname was not allowed.
1635 * - EINVAL durl is NULL or smbc_init not called.
1636 * - ENOENT A directory component in pathname does not
1638 * - ENOTEMPTY directory contains entries.
1639 * - ENOMEM Insufficient kernel memory was available.
1641 * @see smbc_mkdir(), smbc_unlink()
1643 * @todo Are errno values complete and correct?
1645 int smbc_rmdir(const char *durl
);
1647 /**@ingroup directory
1648 * Request directory notifications
1650 * @param dh Valid directory as returned by smbc_opendir()
1652 * @param recursive Are changes in subdirectories wanted?
1654 * @param completion_filter Bitwise-or of the SMBC_NOTIFY_CHANGE_*
1655 * events that are interesting
1657 * @param callback_timeout_ms If set to non-zero, interval in milliseconds
1658 * that "cb" will be called with 0 actions.
1659 * This gives "cb" the chance to cancel the
1662 * @param cb Callback functions taking events. If "cb"
1663 * returns nonzero, smbc_notify will return.
1665 * @param private_data Pointer given to "cb"
1667 * @return 0 on success, -1 on error with errno set
1669 * @see smbc_opendir(), smbc_closedir()
1672 #define SMBC_NOTIFY_CHANGE_FILE_NAME 0x001
1673 #define SMBC_NOTIFY_CHANGE_DIR_NAME 0x002
1674 #define SMBC_NOTIFY_CHANGE_ATTRIBUTES 0x004
1675 #define SMBC_NOTIFY_CHANGE_SIZE 0x008
1676 #define SMBC_NOTIFY_CHANGE_LAST_WRITE 0x010
1677 #define SMBC_NOTIFY_CHANGE_LAST_ACCESS 0x020
1678 #define SMBC_NOTIFY_CHANGE_CREATION 0x040
1679 #define SMBC_NOTIFY_CHANGE_EA 0x080
1680 #define SMBC_NOTIFY_CHANGE_SECURITY 0x100
1681 #define SMBC_NOTIFY_CHANGE_STREAM_NAME 0x200
1682 #define SMBC_NOTIFY_CHANGE_STREAM_SIZE 0x400
1683 #define SMBC_NOTIFY_CHANGE_STREAM_WRITE 0x800
1685 int smbc_notify(int dh
, smbc_bool recursive
, uint32_t completion_filter
,
1686 unsigned callback_timeout_ms
,
1687 smbc_notify_callback_fn cb
, void *private_data
);
1689 /**@ingroup attribute
1690 * Get information about a file or directory.
1692 * @param url The smb url to get information for
1694 * @param st pointer to a buffer that will be filled with
1695 * standard Unix struct stat information.
1697 * @return 0 on success, < 0 on error with errno set:
1698 * - ENOENT A component of the path file_name does not
1700 * - EINVAL a NULL url was passed or smbc_init not called.
1701 * - EACCES Permission denied.
1702 * - ENOMEM Out of memory
1703 * - ENOTDIR The target dir, url, is not a directory.
1708 int smbc_stat(const char *url
, struct stat
*st
);
1711 /**@ingroup attribute
1712 * Get file information via an file descriptor.
1714 * @param fd Open file handle from smbc_open() or smbc_creat()
1716 * @param st pointer to a buffer that will be filled with
1717 * standard Unix struct stat information.
1719 * @return 0 on success, < 0 on error with errno set:
1720 * - EBADF filedes is bad.
1721 * - EACCES Permission denied.
1722 * - EBADF fd is not a valid file descriptor
1723 * - EINVAL Problems occurred in the underlying routines
1724 * or smbc_init not called.
1725 * - ENOMEM Out of memory
1727 * @see smbc_stat(), Unix stat()
1730 int smbc_fstat(int fd
, struct stat
*st
);
1733 /**@ingroup attribute
1734 * Get file system information for a specified path.
1736 * @param url The smb url to get information for
1738 * @param st pointer to a buffer that will be filled with
1739 * standard Unix struct statvfs information.
1741 * @return 0 on success, < 0 on error with errno set:
1742 * - EBADF filedes is bad.
1743 * - EACCES Permission denied.
1744 * - EBADF fd is not a valid file descriptor
1745 * - EINVAL Problems occurred in the underlying routines
1746 * or smbc_init not called.
1747 * - ENOMEM Out of memory
1749 * @see Unix fstatvfs()
1753 smbc_statvfs(char *url
,
1754 struct statvfs
*st
);
1756 /**@ingroup attribute
1757 * Get file system information via an file descriptor.
1759 * @param fd Open file handle from smbc_open(), smbc_creat(),
1762 * @param st pointer to a buffer that will be filled with
1763 * standard Unix struct statvfs information.
1765 * @return 0 on success, < 0 on error with errno set:
1766 * - EBADF filedes is bad.
1767 * - EACCES Permission denied.
1768 * - EBADF fd is not a valid file descriptor
1769 * - EINVAL Problems occurred in the underlying routines
1770 * or smbc_init not called.
1771 * - ENOMEM Out of memory
1773 * @see Unix fstatvfs()
1777 smbc_fstatvfs(int fd
,
1778 struct statvfs
*st
);
1781 /**@ingroup attribute
1782 * Truncate a file given a file descriptor
1784 * @param fd Open file handle from smbc_open() or smbc_creat()
1786 * @param size size to truncate the file to
1788 * @return 0 on success, < 0 on error with errno set:
1789 * - EBADF filedes is bad.
1790 * - EACCES Permission denied.
1791 * - EBADF fd is not a valid file descriptor
1792 * - EINVAL Problems occurred in the underlying routines
1793 * or smbc_init not called.
1794 * - ENOMEM Out of memory
1796 * @see , Unix ftruncate()
1799 int smbc_ftruncate(int fd
, off_t size
);
1802 /**@ingroup attribute
1803 * Change the permissions of a file.
1805 * @param url The smb url of the file or directory to change
1808 * @param mode The permissions to set:
1809 * - Put good explaination of permissions here!
1811 * @return 0 on success, < 0 on error with errno set:
1812 * - EPERM The effective UID does not match the owner
1813 * of the file, and is not zero
1814 * - ENOENT The file does not exist.
1815 * - ENOMEM Insufficient was available.
1816 * - ENOENT file or directory does not exist
1818 * @todo Actually implement this fuction?
1820 * @todo Are errno values complete and correct?
1822 int smbc_chmod(const char *url
, mode_t mode
);
1825 * @ingroup attribute
1826 * Change the last modification time on a file
1828 * @param url The smb url of the file or directory to change
1829 * the modification time of
1831 * @param tbuf An array of two timeval structures which contains,
1832 * respectively, the desired access and modification times.
1833 * NOTE: Only the tv_sec field off each timeval structure is
1834 * used. The tv_usec (microseconds) portion is ignored.
1836 * @return 0 on success, < 0 on error with errno set:
1837 * - EINVAL The client library is not properly initialized
1838 * - EPERM Permission was denied.
1841 int smbc_utimes(const char *url
, struct timeval
*tbuf
);
1845 * @ingroup attribute
1846 * Change the last modification time on a file
1848 * @param url The smb url of the file or directory to change
1849 * the modification time of
1851 * @param utbuf A pointer to a utimebuf structure which contains the
1852 * desired access and modification times.
1854 * @return 0 on success, < 0 on error with errno set:
1855 * - EINVAL The client library is not properly initialized
1856 * - ENOMEM No memory was available for internal needs
1857 * - EPERM Permission was denied.
1860 int smbc_utime(const char *fname
, struct utimbuf
*utbuf
);
1863 /**@ingroup attribute
1864 * Set extended attributes for a file. This is used for modifying a file's
1865 * security descriptor (i.e. owner, group, and access control list)
1867 * @param url The smb url of the file or directory to set extended
1870 * @param name The name of an attribute to be changed. Names are of
1871 * one of the following forms:
1873 * system.nt_sec_desc.<attribute name>
1874 * system.nt_sec_desc.*
1875 * system.nt_sec_desc.*+
1877 * where <attribute name> is one of:
1885 * acl+:<name or sid>
1887 * In the forms "system.nt_sec_desc.*" and
1888 * "system.nt_sec_desc.*+", the asterisk and plus signs are
1889 * literal, i.e. the string is provided exactly as shown, and
1890 * the value parameter should contain a complete security
1891 * descriptor with name:value pairs separated by tabs,
1892 * commas, or newlines (not spaces!).
1894 * The plus sign ('+') indicates that SIDs should be mapped
1895 * to names. Without the plus sign, SIDs are not mapped;
1896 * rather they are simply converted to a string format.
1898 * @param value The value to be assigned to the specified attribute name.
1899 * This buffer should contain only the attribute value if the
1900 * name was of the "system.nt_sec_desc.<attribute_name>"
1901 * form. If the name was of the "system.nt_sec_desc.*" form
1902 * then a complete security descriptor, with name:value pairs
1903 * separated by tabs, commas, or newlines (not spaces!),
1904 * should be provided in this value buffer. A complete
1905 * security descriptor will contain one or more entries
1906 * selected from the following:
1908 * REVISION:<revision number>
1909 * OWNER:<sid or name>
1910 * GROUP:<sid or name>
1911 * ACL:<sid or name>:<type>/<flags>/<mask>
1913 * The revision of the ACL specifies the internal Windows NT
1914 * ACL revision for the security descriptor. If not specified
1915 * it defaults to 1. Using values other than 1 may cause
1916 * strange behaviour.
1918 * The owner and group specify the owner and group sids for
1919 * the object. If the attribute name (either '*+' with a
1920 * complete security descriptor, or individual 'owner+' or
1921 * 'group+' attribute names) ended with a plus sign, the
1922 * specified name is resolved to a SID value, using the
1923 * server on which the file or directory resides. Otherwise,
1924 * the value should be provided in SID-printable format as
1925 * S-1-x-y-z, and is used directly. The <sid or name>
1926 * associated with the ACL: attribute should be provided
1929 * @param size The number of the bytes of data in the value buffer
1931 * @param flags A bit-wise OR of zero or more of the following:
1932 * SMBC_XATTR_FLAG_CREATE -
1933 * fail if the named attribute already exists
1934 * SMBC_XATTR_FLAG_REPLACE -
1935 * fail if the attribute does not already exist
1937 * If neither flag is specified, the specified attributes
1938 * will be added or replace existing attributes of the same
1939 * name, as necessary.
1941 * @return 0 on success, < 0 on error with errno set:
1942 * - EINVAL The client library is not properly initialized
1943 * or one of the parameters is not of a correct
1945 * - ENOMEM No memory was available for internal needs
1946 * - EEXIST If the attribute already exists and the flag
1947 * SMBC_XATTR_FLAG_CREAT was specified
1948 * - ENOATTR If the attribute does not exist and the flag
1949 * SMBC_XATTR_FLAG_REPLACE was specified
1950 * - EPERM Permission was denied.
1951 * - ENOTSUP The referenced file system does not support
1952 * extended attributes
1954 * @note Attribute names are compared in a case-insensitive
1955 * fashion. All of the following are equivalent, although
1956 * the all-lower-case name is the preferred format:
1957 * system.nt_sec_desc.owner
1958 * SYSTEM.NT_SEC_DESC.OWNER
1959 * sYsTeM.nt_sEc_desc.owNER
1962 int smbc_setxattr(const char *url
,
1969 /**@ingroup attribute
1970 * Set extended attributes for a file. This is used for modifying a file's
1971 * security descriptor (i.e. owner, group, and access control list). The
1972 * POSIX function which this maps to would act on a symbolic link rather than
1973 * acting on what the symbolic link points to, but with no symbolic links in
1974 * SMB file systems, this function is functionally identical to
1977 * @param url The smb url of the file or directory to set extended
1980 * @param name The name of an attribute to be changed. Names are of
1981 * one of the following forms:
1983 * system.nt_sec_desc.<attribute name>
1984 * system.nt_sec_desc.*
1985 * system.nt_sec_desc.*+
1987 * where <attribute name> is one of:
1995 * acl+:<name or sid>
1997 * In the forms "system.nt_sec_desc.*" and
1998 * "system.nt_sec_desc.*+", the asterisk and plus signs are
1999 * literal, i.e. the string is provided exactly as shown, and
2000 * the value parameter should contain a complete security
2001 * descriptor with name:value pairs separated by tabs,
2002 * commas, or newlines (not spaces!).
2004 * The plus sign ('+') indicates that SIDs should be mapped
2005 * to names. Without the plus sign, SIDs are not mapped;
2006 * rather they are simply converted to a string format.
2008 * @param value The value to be assigned to the specified attribute name.
2009 * This buffer should contain only the attribute value if the
2010 * name was of the "system.nt_sec_desc.<attribute_name>"
2011 * form. If the name was of the "system.nt_sec_desc.*" form
2012 * then a complete security descriptor, with name:value pairs
2013 * separated by tabs, commas, or newlines (not spaces!),
2014 * should be provided in this value buffer. A complete
2015 * security descriptor will contain one or more entries
2016 * selected from the following:
2018 * REVISION:<revision number>
2019 * OWNER:<sid or name>
2020 * GROUP:<sid or name>
2021 * ACL:<sid or name>:<type>/<flags>/<mask>
2023 * The revision of the ACL specifies the internal Windows NT
2024 * ACL revision for the security descriptor. If not specified
2025 * it defaults to 1. Using values other than 1 may cause
2026 * strange behaviour.
2028 * The owner and group specify the owner and group sids for
2029 * the object. If the attribute name (either '*+' with a
2030 * complete security descriptor, or individual 'owner+' or
2031 * 'group+' attribute names) ended with a plus sign, the
2032 * specified name is resolved to a SID value, using the
2033 * server on which the file or directory resides. Otherwise,
2034 * the value should be provided in SID-printable format as
2035 * S-1-x-y-z, and is used directly. The <sid or name>
2036 * associated with the ACL: attribute should be provided
2039 * @param size The number of the bytes of data in the value buffer
2041 * @param flags A bit-wise OR of zero or more of the following:
2042 * SMBC_XATTR_FLAG_CREATE -
2043 * fail if the named attribute already exists
2044 * SMBC_XATTR_FLAG_REPLACE -
2045 * fail if the attribute does not already exist
2047 * If neither flag is specified, the specified attributes
2048 * will be added or replace existing attributes of the same
2049 * name, as necessary.
2051 * @return 0 on success, < 0 on error with errno set:
2052 * - EINVAL The client library is not properly initialized
2053 * or one of the parameters is not of a correct
2055 * - ENOMEM No memory was available for internal needs
2056 * - EEXIST If the attribute already exists and the flag
2057 * SMBC_XATTR_FLAG_CREAT was specified
2058 * - ENOATTR If the attribute does not exist and the flag
2059 * SMBC_XATTR_FLAG_REPLACE was specified
2060 * - EPERM Permission was denied.
2061 * - ENOTSUP The referenced file system does not support
2062 * extended attributes
2064 * @note Attribute names are compared in a case-insensitive
2065 * fashion. All of the following are equivalent, although
2066 * the all-lower-case name is the preferred format:
2067 * system.nt_sec_desc.owner
2068 * SYSTEM.NT_SEC_DESC.OWNER
2069 * sYsTeM.nt_sEc_desc.owNER
2072 int smbc_lsetxattr(const char *url
,
2079 /**@ingroup attribute
2080 * Set extended attributes for a file. This is used for modifying a file's
2081 * security descriptor (i.e. owner, group, and access control list)
2083 * @param fd A file descriptor associated with an open file (as
2084 * previously returned by smbc_open(), to get extended
2087 * @param name The name of an attribute to be changed. Names are of
2088 * one of the following forms:
2090 * system.nt_sec_desc.<attribute name>
2091 * system.nt_sec_desc.*
2092 * system.nt_sec_desc.*+
2094 * where <attribute name> is one of:
2102 * acl+:<name or sid>
2104 * In the forms "system.nt_sec_desc.*" and
2105 * "system.nt_sec_desc.*+", the asterisk and plus signs are
2106 * literal, i.e. the string is provided exactly as shown, and
2107 * the value parameter should contain a complete security
2108 * descriptor with name:value pairs separated by tabs,
2109 * commas, or newlines (not spaces!).
2111 * The plus sign ('+') indicates that SIDs should be mapped
2112 * to names. Without the plus sign, SIDs are not mapped;
2113 * rather they are simply converted to a string format.
2115 * @param value The value to be assigned to the specified attribute name.
2116 * This buffer should contain only the attribute value if the
2117 * name was of the "system.nt_sec_desc.<attribute_name>"
2118 * form. If the name was of the "system.nt_sec_desc.*" form
2119 * then a complete security descriptor, with name:value pairs
2120 * separated by tabs, commas, or newlines (not spaces!),
2121 * should be provided in this value buffer. A complete
2122 * security descriptor will contain one or more entries
2123 * selected from the following:
2125 * REVISION:<revision number>
2126 * OWNER:<sid or name>
2127 * GROUP:<sid or name>
2128 * ACL:<sid or name>:<type>/<flags>/<mask>
2130 * The revision of the ACL specifies the internal Windows NT
2131 * ACL revision for the security descriptor. If not specified
2132 * it defaults to 1. Using values other than 1 may cause
2133 * strange behaviour.
2135 * The owner and group specify the owner and group sids for
2136 * the object. If the attribute name (either '*+' with a
2137 * complete security descriptor, or individual 'owner+' or
2138 * 'group+' attribute names) ended with a plus sign, the
2139 * specified name is resolved to a SID value, using the
2140 * server on which the file or directory resides. Otherwise,
2141 * the value should be provided in SID-printable format as
2142 * S-1-x-y-z, and is used directly. The <sid or name>
2143 * associated with the ACL: attribute should be provided
2146 * @param size The number of the bytes of data in the value buffer
2148 * @param flags A bit-wise OR of zero or more of the following:
2149 * SMBC_XATTR_FLAG_CREATE -
2150 * fail if the named attribute already exists
2151 * SMBC_XATTR_FLAG_REPLACE -
2152 * fail if the attribute does not already exist
2154 * If neither flag is specified, the specified attributes
2155 * will be added or replace existing attributes of the same
2156 * name, as necessary.
2158 * @return 0 on success, < 0 on error with errno set:
2159 * - EINVAL The client library is not properly initialized
2160 * or one of the parameters is not of a correct
2162 * - ENOMEM No memory was available for internal needs
2163 * - EEXIST If the attribute already exists and the flag
2164 * SMBC_XATTR_FLAG_CREAT was specified
2165 * - ENOATTR If the attribute does not exist and the flag
2166 * SMBC_XATTR_FLAG_REPLACE was specified
2167 * - EPERM Permission was denied.
2168 * - ENOTSUP The referenced file system does not support
2169 * extended attributes
2171 * @note Attribute names are compared in a case-insensitive
2172 * fashion. All of the following are equivalent, although
2173 * the all-lower-case name is the preferred format:
2174 * system.nt_sec_desc.owner
2175 * SYSTEM.NT_SEC_DESC.OWNER
2176 * sYsTeM.nt_sEc_desc.owNER
2179 int smbc_fsetxattr(int fd
,
2186 /**@ingroup attribute
2187 * Get extended attributes for a file.
2189 * @param url The smb url of the file or directory to get extended
2192 * @param name The name of an attribute to be retrieved. Names are of
2193 * one of the following forms:
2195 * system.nt_sec_desc.<attribute name>
2196 * system.nt_sec_desc.*
2197 * system.nt_sec_desc.*+
2199 * where <attribute name> is one of:
2207 * acl+:<name or sid>
2209 * In the forms "system.nt_sec_desc.*" and
2210 * "system.nt_sec_desc.*+", the asterisk and plus signs are
2211 * literal, i.e. the string is provided exactly as shown, and
2212 * the value parameter will return a complete security
2213 * descriptor with name:value pairs separated by tabs,
2214 * commas, or newlines (not spaces!).
2216 * The plus sign ('+') indicates that SIDs should be mapped
2217 * to names. Without the plus sign, SIDs are not mapped;
2218 * rather they are simply converted to a string format.
2220 * @param value A pointer to a buffer in which the value of the specified
2221 * attribute will be placed (unless size is zero).
2223 * @param size The size of the buffer pointed to by value. This parameter
2224 * may also be zero, in which case the size of the buffer
2225 * required to hold the attribute value will be returned,
2226 * but nothing will be placed into the value buffer.
2228 * @return 0 on success, < 0 on error with errno set:
2229 * - EINVAL The client library is not properly initialized
2230 * or one of the parameters is not of a correct
2232 * - ENOMEM No memory was available for internal needs
2233 * - EEXIST If the attribute already exists and the flag
2234 * SMBC_XATTR_FLAG_CREAT was specified
2235 * - ENOATTR If the attribute does not exist and the flag
2236 * SMBC_XATTR_FLAG_REPLACE was specified
2237 * - EPERM Permission was denied.
2238 * - ENOTSUP The referenced file system does not support
2239 * extended attributes
2242 int smbc_getxattr(const char *url
,
2248 /**@ingroup attribute
2249 * Get extended attributes for a file. The POSIX function which this maps to
2250 * would act on a symbolic link rather than acting on what the symbolic link
2251 * points to, but with no symbolic links in SMB file systems, this function
2252 * is functionally identical to smbc_getxattr().
2254 * @param url The smb url of the file or directory to get extended
2257 * @param name The name of an attribute to be retrieved. Names are of
2258 * one of the following forms:
2260 * system.nt_sec_desc.<attribute name>
2261 * system.nt_sec_desc.*
2262 * system.nt_sec_desc.*+
2264 * where <attribute name> is one of:
2272 * acl+:<name or sid>
2274 * In the forms "system.nt_sec_desc.*" and
2275 * "system.nt_sec_desc.*+", the asterisk and plus signs are
2276 * literal, i.e. the string is provided exactly as shown, and
2277 * the value parameter will return a complete security
2278 * descriptor with name:value pairs separated by tabs,
2279 * commas, or newlines (not spaces!).
2281 * The plus sign ('+') indicates that SIDs should be mapped
2282 * to names. Without the plus sign, SIDs are not mapped;
2283 * rather they are simply converted to a string format.
2285 * @param value A pointer to a buffer in which the value of the specified
2286 * attribute will be placed (unless size is zero).
2288 * @param size The size of the buffer pointed to by value. This parameter
2289 * may also be zero, in which case the size of the buffer
2290 * required to hold the attribute value will be returned,
2291 * but nothing will be placed into the value buffer.
2293 * @return 0 on success, < 0 on error with errno set:
2294 * - EINVAL The client library is not properly initialized
2295 * or one of the parameters is not of a correct
2297 * - ENOMEM No memory was available for internal needs
2298 * - EEXIST If the attribute already exists and the flag
2299 * SMBC_XATTR_FLAG_CREAT was specified
2300 * - ENOATTR If the attribute does not exist and the flag
2301 * SMBC_XATTR_FLAG_REPLACE was specified
2302 * - EPERM Permission was denied.
2303 * - ENOTSUP The referenced file system does not support
2304 * extended attributes
2307 int smbc_lgetxattr(const char *url
,
2313 /**@ingroup attribute
2314 * Get extended attributes for a file.
2316 * @param fd A file descriptor associated with an open file (as
2317 * previously returned by smbc_open(), to get extended
2320 * @param name The name of an attribute to be retrieved. Names are of
2321 * one of the following forms:
2323 * system.nt_sec_desc.<attribute name>
2324 * system.nt_sec_desc.*
2325 * system.nt_sec_desc.*+
2327 * where <attribute name> is one of:
2335 * acl+:<name or sid>
2337 * In the forms "system.nt_sec_desc.*" and
2338 * "system.nt_sec_desc.*+", the asterisk and plus signs are
2339 * literal, i.e. the string is provided exactly as shown, and
2340 * the value parameter will return a complete security
2341 * descriptor with name:value pairs separated by tabs,
2342 * commas, or newlines (not spaces!).
2344 * The plus sign ('+') indicates that SIDs should be mapped
2345 * to names. Without the plus sign, SIDs are not mapped;
2346 * rather they are simply converted to a string format.
2348 * @param value A pointer to a buffer in which the value of the specified
2349 * attribute will be placed (unless size is zero).
2351 * @param size The size of the buffer pointed to by value. This parameter
2352 * may also be zero, in which case the size of the buffer
2353 * required to hold the attribute value will be returned,
2354 * but nothing will be placed into the value buffer.
2356 * @return 0 on success, < 0 on error with errno set:
2357 * - EINVAL The client library is not properly initialized
2358 * or one of the parameters is not of a correct
2360 * - ENOMEM No memory was available for internal needs
2361 * - EEXIST If the attribute already exists and the flag
2362 * SMBC_XATTR_FLAG_CREAT was specified
2363 * - ENOATTR If the attribute does not exist and the flag
2364 * SMBC_XATTR_FLAG_REPLACE was specified
2365 * - EPERM Permission was denied.
2366 * - ENOTSUP The referenced file system does not support
2367 * extended attributes
2370 int smbc_fgetxattr(int fd
,
2376 /**@ingroup attribute
2377 * Remove extended attributes for a file. This is used for modifying a file's
2378 * security descriptor (i.e. owner, group, and access control list)
2380 * @param url The smb url of the file or directory to remove the extended
2383 * @param name The name of an attribute to be removed. Names are of
2384 * one of the following forms:
2386 * system.nt_sec_desc.<attribute name>
2387 * system.nt_sec_desc.*
2388 * system.nt_sec_desc.*+
2390 * where <attribute name> is one of:
2398 * acl+:<name or sid>
2400 * In the forms "system.nt_sec_desc.*" and
2401 * "system.nt_sec_desc.*+", the asterisk and plus signs are
2402 * literal, i.e. the string is provided exactly as shown, and
2403 * the value parameter will return a complete security
2404 * descriptor with name:value pairs separated by tabs,
2405 * commas, or newlines (not spaces!).
2407 * The plus sign ('+') indicates that SIDs should be mapped
2408 * to names. Without the plus sign, SIDs are not mapped;
2409 * rather they are simply converted to a string format.
2411 * @return 0 on success, < 0 on error with errno set:
2412 * - EINVAL The client library is not properly initialized
2413 * - ENOMEM No memory was available for internal needs
2414 * - EPERM Permission was denied.
2415 * - ENOTSUP The referenced file system does not support
2416 * extended attributes
2419 int smbc_removexattr(const char *url
,
2423 /**@ingroup attribute
2424 * Remove extended attributes for a file. This is used for modifying a file's
2425 * security descriptor (i.e. owner, group, and access control list) The POSIX
2426 * function which this maps to would act on a symbolic link rather than acting
2427 * on what the symbolic link points to, but with no symbolic links in SMB file
2428 * systems, this function is functionally identical to smbc_removexattr().
2430 * @param url The smb url of the file or directory to remove the extended
2433 * @param name The name of an attribute to be removed. Names are of
2434 * one of the following forms:
2436 * system.nt_sec_desc.<attribute name>
2437 * system.nt_sec_desc.*
2438 * system.nt_sec_desc.*+
2440 * where <attribute name> is one of:
2448 * acl+:<name or sid>
2450 * In the forms "system.nt_sec_desc.*" and
2451 * "system.nt_sec_desc.*+", the asterisk and plus signs are
2452 * literal, i.e. the string is provided exactly as shown, and
2453 * the value parameter will return a complete security
2454 * descriptor with name:value pairs separated by tabs,
2455 * commas, or newlines (not spaces!).
2457 * The plus sign ('+') indicates that SIDs should be mapped
2458 * to names. Without the plus sign, SIDs are not mapped;
2459 * rather they are simply converted to a string format.
2461 * @return 0 on success, < 0 on error with errno set:
2462 * - EINVAL The client library is not properly initialized
2463 * - ENOMEM No memory was available for internal needs
2464 * - EPERM Permission was denied.
2465 * - ENOTSUP The referenced file system does not support
2466 * extended attributes
2469 int smbc_lremovexattr(const char *url
,
2473 /**@ingroup attribute
2474 * Remove extended attributes for a file. This is used for modifying a file's
2475 * security descriptor (i.e. owner, group, and access control list)
2477 * @param fd A file descriptor associated with an open file (as
2478 * previously returned by smbc_open(), to get extended
2481 * @param name The name of an attribute to be removed. Names are of
2482 * one of the following forms:
2484 * system.nt_sec_desc.<attribute name>
2485 * system.nt_sec_desc.*
2486 * system.nt_sec_desc.*+
2488 * where <attribute name> is one of:
2496 * acl+:<name or sid>
2498 * In the forms "system.nt_sec_desc.*" and
2499 * "system.nt_sec_desc.*+", the asterisk and plus signs are
2500 * literal, i.e. the string is provided exactly as shown, and
2501 * the value parameter will return a complete security
2502 * descriptor with name:value pairs separated by tabs,
2503 * commas, or newlines (not spaces!).
2505 * The plus sign ('+') indicates that SIDs should be mapped
2506 * to names. Without the plus sign, SIDs are not mapped;
2507 * rather they are simply converted to a string format.
2509 * @return 0 on success, < 0 on error with errno set:
2510 * - EINVAL The client library is not properly initialized
2511 * - ENOMEM No memory was available for internal needs
2512 * - EPERM Permission was denied.
2513 * - ENOTSUP The referenced file system does not support
2514 * extended attributes
2517 int smbc_fremovexattr(int fd
,
2521 /**@ingroup attribute
2522 * List the supported extended attribute names associated with a file
2524 * @param url The smb url of the file or directory to list the extended
2527 * @param list A pointer to a buffer in which the list of attributes for
2528 * the specified file or directory will be placed (unless
2531 * @param size The size of the buffer pointed to by list. This parameter
2532 * may also be zero, in which case the size of the buffer
2533 * required to hold all of the attribute names will be
2534 * returned, but nothing will be placed into the list buffer.
2536 * @return 0 on success, < 0 on error with errno set:
2537 * - EINVAL The client library is not properly initialized
2538 * - ENOMEM No memory was available for internal needs
2539 * - EPERM Permission was denied.
2540 * - ENOTSUP The referenced file system does not support
2541 * extended attributes
2543 * @note This function always returns all attribute names supported
2544 * by NT file systems, regardless of whether the referenced
2545 * file system supports extended attributes (e.g. a Windows
2546 * 2000 machine supports extended attributes if NTFS is used,
2547 * but not if FAT is used, and Windows 98 doesn't support
2548 * extended attributes at all. Whether this is a feature or
2549 * a bug is yet to be decided.
2551 int smbc_listxattr(const char *url
,
2555 /**@ingroup attribute
2556 * List the supported extended attribute names associated with a file The
2557 * POSIX function which this maps to would act on a symbolic link rather than
2558 * acting on what the symbolic link points to, but with no symbolic links in
2559 * SMB file systems, this function is functionally identical to
2562 * @param url The smb url of the file or directory to list the extended
2565 * @param list A pointer to a buffer in which the list of attributes for
2566 * the specified file or directory will be placed (unless
2569 * @param size The size of the buffer pointed to by list. This parameter
2570 * may also be zero, in which case the size of the buffer
2571 * required to hold all of the attribute names will be
2572 * returned, but nothing will be placed into the list buffer.
2574 * @return 0 on success, < 0 on error with errno set:
2575 * - EINVAL The client library is not properly initialized
2576 * - ENOMEM No memory was available for internal needs
2577 * - EPERM Permission was denied.
2578 * - ENOTSUP The referenced file system does not support
2579 * extended attributes
2581 * @note This function always returns all attribute names supported
2582 * by NT file systems, regardless of wether the referenced
2583 * file system supports extended attributes (e.g. a Windows
2584 * 2000 machine supports extended attributes if NTFS is used,
2585 * but not if FAT is used, and Windows 98 doesn't support
2586 * extended attributes at all. Whether this is a feature or
2587 * a bug is yet to be decided.
2589 int smbc_llistxattr(const char *url
,
2593 /**@ingroup attribute
2594 * List the supported extended attribute names associated with a file
2596 * @param fd A file descriptor associated with an open file (as
2597 * previously returned by smbc_open(), to get extended
2600 * @param list A pointer to a buffer in which the list of attributes for
2601 * the specified file or directory will be placed (unless
2604 * @param size The size of the buffer pointed to by list. This parameter
2605 * may also be zero, in which case the size of the buffer
2606 * required to hold all of the attribute names will be
2607 * returned, but nothing will be placed into the list buffer.
2609 * @return 0 on success, < 0 on error with errno set:
2610 * - EINVAL The client library is not properly initialized
2611 * - ENOMEM No memory was available for internal needs
2612 * - EPERM Permission was denied.
2613 * - ENOTSUP The referenced file system does not support
2614 * extended attributes
2616 * @note This function always returns all attribute names supported
2617 * by NT file systems, regardless of wether the referenced
2618 * file system supports extended attributes (e.g. a Windows
2619 * 2000 machine supports extended attributes if NTFS is used,
2620 * but not if FAT is used, and Windows 98 doesn't support
2621 * extended attributes at all. Whether this is a feature or
2622 * a bug is yet to be decided.
2624 int smbc_flistxattr(int fd
,
2629 * Print a file given the name in fname. It would be a URL ...
2631 * @param fname The URL of a file on a remote SMB server that the
2632 * caller wants printed
2634 * @param printq The URL of the print share to print the file to.
2636 * @return 0 on success, < 0 on error with errno set:
2638 * - EINVAL fname or printq was NULL or smbc_init not
2640 * and errors returned by smbc_open
2643 int smbc_print_file(const char *fname
, const char *printq
);
2646 * Open a print file that can be written to by other calls. This simply
2647 * does an smbc_open call after checking if there is a file name on the
2648 * URI. If not, a temporary name is added ...
2650 * @param fname The URL of the print share to print to?
2652 * @returns A file handle for the print file if successful.
2653 * Returns -1 if an error ocurred and errno has the values
2654 * - EINVAL fname was NULL or smbc_init not called.
2655 * - all errors returned by smbc_open
2658 int smbc_open_print_job(const char *fname
);
2661 * List the print jobs on a print share, for the moment, pass a callback
2663 * @param purl The url of the print share to list the jobs of
2665 * @param fn Callback function the receives printjob info
2667 * @return 0 on success, < 0 on error with errno set:
2668 * - EINVAL fname was NULL or smbc_init not called
2671 int smbc_list_print_jobs(const char *purl
, smbc_list_print_job_fn fn
);
2674 * Delete a print job
2676 * @param purl Url of the print share
2678 * @param id The id of the job to delete
2680 * @return 0 on success, < 0 on error with errno set:
2681 * - EINVAL fname was NULL or smbc_init not called
2683 * @todo what errno values are possible here?
2685 int smbc_unlink_print_job(const char *purl
, int id
);
2687 /**@ingroup callback
2688 * Remove a server from the cached server list it's unused.
2690 * @param context pointer to smb context
2692 * @param srv pointer to server to remove
2694 * @return On success, 0 is returned. 1 is returned if the server could not
2695 * be removed. Also useable outside libsmbclient.
2697 int smbc_remove_unused_server(SMBCCTX
* context
, SMBCSRV
* srv
);
2703 /**@ingroup directory
2704 * Convert strings of %xx to their single character equivalent.
2706 * @param dest A pointer to a buffer in which the resulting decoded
2707 * string should be placed. This may be a pointer to the
2708 * same buffer as src_segment.
2710 * @param src A pointer to the buffer containing the URL to be decoded.
2711 * Any %xx sequences herein are converted to their single
2712 * character equivalent. Each 'x' must be a valid hexadecimal
2713 * digit, or that % sequence is left undecoded.
2715 * @param max_dest_len
2716 * The size of the buffer pointed to by dest_segment.
2718 * @return The number of % sequences which could not be converted
2719 * due to lack of two following hexadecimal digits.
2725 smbc_urldecode(char *dest
, char * src
, size_t max_dest_len
);
2732 * Convert any characters not specifically allowed in a URL into their %xx
2735 * @param dest A pointer to a buffer in which the resulting encoded
2736 * string should be placed. Unlike smbc_urldecode(), this
2737 * must be a buffer unique from src.
2739 * @param src A pointer to the buffer containing the string to be encoded.
2740 * Any character not specifically allowed in a URL is converted
2741 * into its hexadecimal value and encoded as %xx.
2743 * @param max_dest_len
2744 * The size of the buffer pointed to by dest_segment.
2746 * @returns The remaining buffer length.
2752 smbc_urlencode(char * dest
, char * src
, int max_dest_len
);
2758 /**@ingroup directory
2759 * Return the version of the linked Samba code, and thus the version of the
2760 * libsmbclient code.
2762 * @return The version string.
2774 * Set the users credentials globally so they can be used for DFS
2775 * referrals. Probably best to use this function in the smbc_get_auth_data_fn
2778 * @param workgroup Workgroup of the user.
2780 * @param user Username of user.
2782 * @param password Password of user.
2784 * @param use_kerberos Whether to use Kerberos
2786 * @param signing_state One of these strings (all equivalents on same line):
2787 * "off", "no", "false"
2788 * "on", "yes", "true", "auto"
2789 * "force", "required", "forced"
2793 smbc_set_credentials(const char *workgroup
,
2795 const char *password
,
2796 smbc_bool use_kerberos
,
2797 const char *signing_state
);
2800 * Wrapper around smbc_set_credentials.
2801 * Used to set correct credentials that will
2802 * be used to connect to DFS target share
2807 smbc_set_credentials_with_fallback(SMBCCTX
*ctx
,
2808 const char *workgroup
,
2810 const char *password
);
2816 * Initialize for threads using the Posix Threads (pthread)
2817 * implementation. This is a built-in implementation, avoiding the need to
2818 * implement the component functions of the thread interface. If this function
2819 * is used, it is not necessary to call smbc_thread_impl().
2824 smbc_thread_posix(void);
2829 * Initialize for an arbitrary thread implementation. The caller should
2830 * provide, as parameters, pointers to functions to implement the requisite
2831 * low-level thread functionality. A function must be provided for each
2832 * parameter; none may be null.
2834 * If the thread implementation is POSIX Threads (pthreads), then the much
2835 * simpler smbc_thread_pthread() function may be used instead of this one.
2837 * @param create_mutex
2838 * Create a mutex. This function should expect three parameters: lockname,
2839 * pplock, and location. It should create a unique mutex for each unique
2840 * lockname it is provided, and return the mutex identifier in *pplock. The
2841 * location parameter can be used for debugging, as it contains the
2842 * compiler-provided __location__ of the call.
2844 * @param destroy_mutex
2845 * Destroy a mutex. This function should expect two parameters: plock and
2846 * location. It should destroy the mutex associated with the identifier
2847 * plock. The location parameter can be used for debugging, as it contains
2848 * the compiler-provided __location__ of the call.
2851 * Lock a mutex. This function should expect three parameters: plock,
2852 * lock_type, and location. The mutex aassociated with identifier plock
2853 * should be locked if lock_type is 1, and unlocked if lock_type is 2. The
2854 * location parameter can be used for debugging, as it contains the
2855 * compiler-provided __location__ of the call.
2858 * Create thread local storage. This function should expect three
2859 * parameters: keyname, ppkey, and location. It should allocate an
2860 * implementation-specific amount of memory and assign the pointer to that
2861 * allocated memory to *ppkey. The location parameter can be used for
2862 * debugging, as it contains the compiler-provided __location__ of the
2863 * call. This function should return 0 upon success, non-zero upon failure.
2865 * @param destroy_tls
2866 * Destroy thread local storage. This function should expect two parameters:
2867 * ppkey and location. The ppkey parameter points to a variable containing a
2868 * thread local storage key previously provided by the create_tls
2869 * function. The location parameter can be used for debugging, as it
2870 * contains the compiler-provided __location__ of the call.
2873 * Set a thread local storage variable's value. This function should expect
2874 * three parameters: pkey, pval, and location. The pkey parameter is a
2875 * thread local storage key previously provided by the create_tls
2876 * function. The (void *) pval parameter contains the value to be placed in
2877 * the thread local storage variable identified by pkey. The location
2878 * parameter can be used for debugging, as it contains the compiler-provided
2879 * __location__ of the call. This function should return 0 upon success;
2880 * non-zero otherwise.
2883 * Retrieve a thread local storage variable's value. This function should
2884 * expect two parameters: pkey and location. The pkey parameter is a thread
2885 * local storage key previously provided by the create_tls function, and
2886 * which has previously been used in a call to the set_tls function to
2887 * initialize a thread local storage variable. The location parameter can be
2888 * used for debugging, as it contains the compiler-provided __location__ of
2889 * the call. This function should return the (void *) value stored in the
2890 * variable identified by pkey.
2896 /* Mutex functions. */
2897 int (*create_mutex
)(const char *lockname
,
2899 const char *location
),
2900 void (*destroy_mutex
)(void *plock
,
2901 const char *location
),
2902 int (*lock_mutex
)(void *plock
,
2904 const char *location
),
2906 /* Thread local storage. */
2907 int (*create_tls
)(const char *keyname
,
2909 const char *location
),
2910 void (*destroy_tls
)(void **ppkey
,
2911 const char *location
),
2912 int (*set_tls
)(void *pkey
,
2914 const char *location
),
2915 void *(*get_tls
)(void *pkey
,
2916 const char *location
)
2922 * @ingroup structure
2923 * Structure that contains a client context information
2924 * This structure is known as SMBCCTX
2926 * DO NOT DIRECTLY MANIPULATE THE CONTEXT STRUCTURE! The data in the context
2927 * structure should all be considered private to the library. It remains here
2928 * only for backward compatibility.
2930 * See the comments herein for use of the setter and getter functions which
2931 * should now be used for manipulating these values. New features, functions,
2932 * etc., are not added here but rather in _internal where they are not
2933 * directly visible to applications. This makes it much easier to maintain
2934 * ABI compatibility.
2942 * Use smbc_getDebug() and smbc_setDebug()
2944 int debug DEPRECATED_SMBC_INTERFACE
;
2947 * netbios name used for making connections
2950 * Use smbc_getNetbiosName() and smbc_setNetbiosName()
2952 char * netbios_name DEPRECATED_SMBC_INTERFACE
;
2955 * workgroup name used for making connections
2958 * Use smbc_getWorkgroup() and smbc_setWorkgroup()
2960 char * workgroup DEPRECATED_SMBC_INTERFACE
;
2963 * username used for making connections
2966 * Use smbc_getUser() and smbc_setUser()
2968 char * user DEPRECATED_SMBC_INTERFACE
;
2971 * timeout used for waiting on connections / response data (in
2975 * Use smbc_getTimeout() and smbc_setTimeout()
2977 int timeout DEPRECATED_SMBC_INTERFACE
;
2980 * callable functions for files:
2981 * For usage and return values see the SMBC_* functions
2985 * Use smbc_getFunction*() and smbc_setFunction*(), e.g.
2986 * smbc_getFunctionOpen(), smbc_setFunctionUnlink(), etc.
2988 smbc_open_fn open DEPRECATED_SMBC_INTERFACE
;
2989 smbc_creat_fn creat DEPRECATED_SMBC_INTERFACE
;
2990 smbc_read_fn read DEPRECATED_SMBC_INTERFACE
;
2991 smbc_write_fn write DEPRECATED_SMBC_INTERFACE
;
2992 smbc_unlink_fn unlink DEPRECATED_SMBC_INTERFACE
;
2993 smbc_rename_fn rename DEPRECATED_SMBC_INTERFACE
;
2994 smbc_lseek_fn lseek DEPRECATED_SMBC_INTERFACE
;
2995 smbc_stat_fn stat DEPRECATED_SMBC_INTERFACE
;
2996 smbc_fstat_fn fstat DEPRECATED_SMBC_INTERFACE
;
2997 #if 0 /* internal */
2998 smbc_ftruncate_fn ftruncate_fn
;
3000 smbc_close_fn close_fn DEPRECATED_SMBC_INTERFACE
;
3001 smbc_opendir_fn opendir DEPRECATED_SMBC_INTERFACE
;
3002 smbc_closedir_fn closedir DEPRECATED_SMBC_INTERFACE
;
3003 smbc_readdir_fn readdir DEPRECATED_SMBC_INTERFACE
;
3004 smbc_getdents_fn getdents DEPRECATED_SMBC_INTERFACE
;
3005 smbc_mkdir_fn mkdir DEPRECATED_SMBC_INTERFACE
;
3006 smbc_rmdir_fn rmdir DEPRECATED_SMBC_INTERFACE
;
3007 smbc_telldir_fn telldir DEPRECATED_SMBC_INTERFACE
;
3008 smbc_lseekdir_fn lseekdir DEPRECATED_SMBC_INTERFACE
;
3009 smbc_fstatdir_fn fstatdir DEPRECATED_SMBC_INTERFACE
;
3010 smbc_chmod_fn chmod DEPRECATED_SMBC_INTERFACE
;
3011 smbc_utimes_fn utimes DEPRECATED_SMBC_INTERFACE
;
3012 smbc_setxattr_fn setxattr DEPRECATED_SMBC_INTERFACE
;
3013 smbc_getxattr_fn getxattr DEPRECATED_SMBC_INTERFACE
;
3014 smbc_removexattr_fn removexattr DEPRECATED_SMBC_INTERFACE
;
3015 smbc_listxattr_fn listxattr DEPRECATED_SMBC_INTERFACE
;
3017 /* Printing-related functions */
3018 smbc_print_file_fn print_file DEPRECATED_SMBC_INTERFACE
;
3019 smbc_open_print_job_fn open_print_job DEPRECATED_SMBC_INTERFACE
;
3020 smbc_list_print_jobs_fn list_print_jobs DEPRECATED_SMBC_INTERFACE
;
3021 smbc_unlink_print_job_fn unlink_print_job DEPRECATED_SMBC_INTERFACE
;
3028 * See the comment above each field, for the getter and setter
3029 * functions that should now be used.
3031 struct _smbc_callbacks
3034 * authentication function callback: called upon auth requests
3037 * Use smbc_getFunctionAuthData(), smbc_setFunctionAuthData()
3039 smbc_get_auth_data_fn auth_fn DEPRECATED_SMBC_INTERFACE
;
3042 * check if a server is still good
3045 * Use smbc_getFunctionCheckServer(),
3046 * smbc_setFunctionCheckServer()
3048 smbc_check_server_fn check_server_fn DEPRECATED_SMBC_INTERFACE
;
3051 * remove a server if unused
3054 * Use smbc_getFunctionRemoveUnusedServer(),
3055 * smbc_setFunctionCheckServer()
3057 smbc_remove_unused_server_fn remove_unused_server_fn DEPRECATED_SMBC_INTERFACE
;
3061 * For an example cache system see
3062 * samba/source/libsmb/libsmb_cache.c
3064 * Cache subsystem * functions follow.
3068 * server cache addition
3071 * Use smbc_getFunctionAddCachedServer(),
3072 * smbc_setFunctionAddCachedServer()
3074 smbc_add_cached_srv_fn add_cached_srv_fn DEPRECATED_SMBC_INTERFACE
;
3077 * server cache lookup
3080 * Use smbc_getFunctionGetCachedServer(),
3081 * smbc_setFunctionGetCachedServer()
3083 smbc_get_cached_srv_fn get_cached_srv_fn DEPRECATED_SMBC_INTERFACE
;
3086 * server cache removal
3089 * Use smbc_getFunctionRemoveCachedServer(),
3090 * smbc_setFunctionRemoveCachedServer()
3092 smbc_remove_cached_srv_fn remove_cached_srv_fn DEPRECATED_SMBC_INTERFACE
;
3095 * server cache purging, try to remove all cached servers
3099 * Use smbc_getFunctionPurgeCachedServers(),
3100 * smbc_setFunctionPurgeCachedServers()
3102 smbc_purge_cached_fn purge_cached_fn DEPRECATED_SMBC_INTERFACE
;
3106 * Space where the private data of the server cache used to be
3109 * Use smbc_getServerCacheData(), smbc_setServerCacheData()
3111 void * reserved DEPRECATED_SMBC_INTERFACE
;
3114 * Very old configuration options.
3117 * Use one of the following functions instead:
3118 * smbc_setOptionUseKerberos()
3119 * smbc_getOptionUseKerberos()
3120 * smbc_setOptionFallbackAfterKerberos()
3121 * smbc_getOptionFallbackAfterKerberos()
3122 * smbc_setOptionNoAutoAnonymousLogin()
3123 * smbc_getOptionNoAutoAnonymousLogin()
3125 int flags DEPRECATED_SMBC_INTERFACE
;
3128 * user options selections that apply to this session
3130 * NEW OPTIONS ARE NOT ADDED HERE!
3133 * To set and retrieve options, use the smbc_setOption*() and
3134 * smbc_getOption*() functions.
3136 struct _smbc_options
{
3137 int browse_max_lmb_count DEPRECATED_SMBC_INTERFACE
;
3138 int urlencode_readdir_entries DEPRECATED_SMBC_INTERFACE
;
3139 int one_share_per_server DEPRECATED_SMBC_INTERFACE
;
3140 } options DEPRECATED_SMBC_INTERFACE
;
3143 * do _NOT_ touch this from your program !
3145 struct SMBC_internal_data
* internal
;
3149 #endif /* SMBCLIENT_H_INCLUDED */