s4/ldb: expose the ldb flags with ldb_get_flags()
[Samba/aatanasov.git] / source3 / include / libsmbclient.h
blob7de5000615e5423c1846676e6cc41285ae45fa7d
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))
31 #else
32 # define DEPRECATED_SMBC_INTERFACE
33 #endif
35 #ifdef __cplusplus
36 extern "C" {
37 #endif
39 /*-------------------------------------------------------------------*/
40 /* The following are special comments to instruct DOXYGEN (automated
41 * documentation tool:
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
51 * Callback functions
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>
77 #include <sys/stat.h>
78 #include <sys/statvfs.h>
79 #include <fcntl.h>
80 #include <utime.h>
82 #define SMBC_BASE_FD 10000 /* smallest file descriptor returned */
84 #define SMBC_WORKGROUP 1
85 #define SMBC_SERVER 2
86 #define SMBC_FILE_SHARE 3
87 #define SMBC_PRINTER_SHARE 4
88 #define SMBC_COMMS_SHARE 5
89 #define SMBC_IPC_SHARE 6
90 #define SMBC_DIR 7
91 #define SMBC_FILE 8
92 #define SMBC_LINK 9
94 /**@ingroup structure
95 * Structure that represents a directory entry.
98 struct smbc_dirent
100 /** Type of entity.
101 SMBC_WORKGROUP=1,
102 SMBC_SERVER=2,
103 SMBC_FILE_SHARE=3,
104 SMBC_PRINTER_SHARE=4,
105 SMBC_COMMS_SHARE=5,
106 SMBC_IPC_SHARE=6,
107 SMBC_DIR=7,
108 SMBC_FILE=8,
109 SMBC_LINK=9,*/
110 unsigned int smbc_type;
112 /** Length of this smbc_dirent in bytes
114 unsigned int dirlen;
115 /** The length of the comment string in bytes (does not include
116 * null terminator)
118 unsigned int commentlen;
119 /** Points to the null terminated comment string
121 char *comment;
122 /** The length of the name string in bytes (does not include
123 * null terminator)
125 unsigned int namelen;
126 /** Points to the null terminated name string
128 char name[1];
132 * Flags for smbc_setxattr()
133 * Specify a bitwise OR of these, or 0 to add or replace as necessary
135 #define SMBC_XATTR_FLAG_CREATE 0x1 /* fail if attr already exists */
136 #define SMBC_XATTR_FLAG_REPLACE 0x2 /* fail if attr does not exist */
140 * Mappings of the DOS mode bits, as returned by smbc_getxattr() when the
141 * attribute name "system.dos_attr.mode" (or "system.dos_attr.*" or
142 * "system.*") is specified.
144 #define SMBC_DOS_MODE_READONLY 0x01
145 #define SMBC_DOS_MODE_HIDDEN 0x02
146 #define SMBC_DOS_MODE_SYSTEM 0x04
147 #define SMBC_DOS_MODE_VOLUME_ID 0x08
148 #define SMBC_DOS_MODE_DIRECTORY 0x10
149 #define SMBC_DOS_MODE_ARCHIVE 0x20
152 * Valid values for the option "open_share_mode", when calling
153 * smbc_setOptionOpenShareMode()
155 typedef enum smbc_share_mode
157 SMBC_SHAREMODE_DENY_DOS = 0,
158 SMBC_SHAREMODE_DENY_ALL = 1,
159 SMBC_SHAREMODE_DENY_WRITE = 2,
160 SMBC_SHAREMODE_DENY_READ = 3,
161 SMBC_SHAREMODE_DENY_NONE = 4,
162 SMBC_SHAREMODE_DENY_FCB = 7
163 } smbc_share_mode;
167 * Values for option SMB Encryption Level, as set and retrieved with
168 * smbc_setOptionSmbEncryptionLevel() and smbc_getOptionSmbEncryptionLevel()
170 typedef enum smbc_smb_encrypt_level
172 SMBC_ENCRYPTLEVEL_NONE = 0,
173 SMBC_ENCRYPTLEVEL_REQUEST = 1,
174 SMBC_ENCRYPTLEVEL_REQUIRE = 2
175 } smbc_smb_encrypt_level;
179 * Capabilities set in the f_flag field of struct statvfs, from
180 * smbc_statvfs(). These may be OR-ed together to reflect a full set of
181 * available capabilities.
183 typedef enum smbc_vfs_feature
185 /* Defined by POSIX or in Linux include files (low-order bits) */
186 SMBC_VFS_FEATURE_RDONLY = (1 << 0),
188 /* Specific to libsmbclient (high-order bits) */
189 SMBC_VFS_FEATURE_DFS = (1 << 28),
190 SMBC_VFS_FEATURE_CASE_INSENSITIVE = (1 << 29),
191 SMBC_VFS_FEATURE_NO_UNIXCIFS = (1 << 30)
192 } smbc_vfs_feature;
194 typedef int smbc_bool;
197 #ifndef ENOATTR
198 # define ENOATTR ENOENT /* No such attribute */
199 #endif
204 /**@ingroup structure
205 * Structure that represents a print job.
208 #ifndef _CLIENT_H
209 struct print_job_info
211 /** numeric ID of the print job
213 unsigned short id;
215 /** represents print job priority (lower numbers mean higher priority)
217 unsigned short priority;
219 /** Size of the print job
221 size_t size;
223 /** Name of the user that owns the print job
225 char user[128];
227 /** Name of the print job. This will have no name if an anonymous print
228 * file was opened. Ie smb://server/printer
230 char name[128];
232 /** Time the print job was spooled
234 time_t t;
236 #endif /* _CLIENT_H */
239 /**@ingroup structure
240 * Server handle
242 typedef struct _SMBCSRV SMBCSRV;
244 /**@ingroup structure
245 * File or directory handle
247 typedef struct _SMBCFILE SMBCFILE;
249 /**@ingroup structure
250 * File or directory handle
252 typedef struct _SMBCCTX SMBCCTX;
256 * Flags for SMBCCTX->flags
258 * NEW CODE SHOULD NOT DIRECTLY MANIPULATE THE CONTEXT STRUCTURE.
259 * Instead, use:
260 * smbc_setOptionUseKerberos()
261 * smbc_getOptionUseKerberos()
262 * smbc_setOptionFallbackAfterKerberos()
263 * smbc_getOptionFallbackAFterKerberos()
264 * smbc_setOptionNoAutoAnonymousLogin()
265 * smbc_getOptionNoAutoAnonymousLogin()
267 # define SMB_CTX_FLAG_USE_KERBEROS (1 << 0)
268 # define SMB_CTX_FLAG_FALLBACK_AFTER_KERBEROS (1 << 1)
269 # define SMBCCTX_FLAG_NO_AUTO_ANONYMOUS_LOGON (1 << 2)
273 /**@ingroup callback
274 * Authentication callback function type (traditional method)
276 * Type for the the authentication function called by the library to
277 * obtain authentication credentals
279 * For kerberos support the function should just be called without
280 * prompting the user for credentials. Which means a simple 'return'
281 * should work. Take a look at examples/libsmbclient/get_auth_data_fn.h
282 * and examples/libsmbclient/testbrowse.c.
284 * @param srv Server being authenticated to
286 * @param shr Share being authenticated to
288 * @param wg Pointer to buffer containing a "hint" for the
289 * workgroup to be authenticated. Should be filled in
290 * with the correct workgroup if the hint is wrong.
292 * @param wglen The size of the workgroup buffer in bytes
294 * @param un Pointer to buffer containing a "hint" for the
295 * user name to be use for authentication. Should be
296 * filled in with the correct workgroup if the hint is
297 * wrong.
299 * @param unlen The size of the username buffer in bytes
301 * @param pw Pointer to buffer containing to which password
302 * copied
304 * @param pwlen The size of the password buffer in bytes
307 typedef void (*smbc_get_auth_data_fn)(const char *srv,
308 const char *shr,
309 char *wg, int wglen,
310 char *un, int unlen,
311 char *pw, int pwlen);
312 /**@ingroup callback
313 * Authentication callback function type (method that includes context)
315 * Type for the the authentication function called by the library to
316 * obtain authentication credentals
318 * For kerberos support the function should just be called without
319 * prompting the user for credentials. Which means a simple 'return'
320 * should work. Take a look at examples/libsmbclient/get_auth_data_fn.h
321 * and examples/libsmbclient/testbrowse.c.
323 * @param c Pointer to the smb context
325 * @param srv Server being authenticated to
327 * @param shr Share being authenticated to
329 * @param wg Pointer to buffer containing a "hint" for the
330 * workgroup to be authenticated. Should be filled in
331 * with the correct workgroup if the hint is wrong.
333 * @param wglen The size of the workgroup buffer in bytes
335 * @param un Pointer to buffer containing a "hint" for the
336 * user name to be use for authentication. Should be
337 * filled in with the correct workgroup if the hint is
338 * wrong.
340 * @param unlen The size of the username buffer in bytes
342 * @param pw Pointer to buffer containing to which password
343 * copied
345 * @param pwlen The size of the password buffer in bytes
348 typedef void (*smbc_get_auth_data_with_context_fn)(SMBCCTX *c,
349 const char *srv,
350 const char *shr,
351 char *wg, int wglen,
352 char *un, int unlen,
353 char *pw, int pwlen);
356 /**@ingroup callback
357 * Print job info callback function type.
359 * @param i pointer to print job information structure
362 typedef void (*smbc_list_print_job_fn)(struct print_job_info *i);
365 /**@ingroup callback
366 * Check if a server is still good
368 * @param c pointer to smb context
370 * @param srv pointer to server to check
372 * @return 0 when connection is good. 1 on error.
375 typedef int (*smbc_check_server_fn)(SMBCCTX * c, SMBCSRV *srv);
377 /**@ingroup callback
378 * Remove a server if unused
380 * @param c pointer to smb context
382 * @param srv pointer to server to remove
384 * @return 0 on success. 1 on failure.
387 typedef int (*smbc_remove_unused_server_fn)(SMBCCTX * c, SMBCSRV *srv);
390 /**@ingroup callback
391 * Add a server to the cache system
393 * @param c pointer to smb context
395 * @param srv pointer to server to add
397 * @param server server name
399 * @param share share name
401 * @param workgroup workgroup used to connect
403 * @param username username used to connect
405 * @return 0 on success. 1 on failure.
408 typedef int (*smbc_add_cached_srv_fn) (SMBCCTX * c, SMBCSRV *srv,
409 const char * server, const char * share,
410 const char * workgroup, const char * username);
412 /**@ingroup callback
413 * Look up a server in the cache system
415 * @param c pointer to smb context
417 * @param server server name to match
419 * @param share share name to match
421 * @param workgroup workgroup to match
423 * @param username username to match
425 * @return pointer to SMBCSRV on success. NULL on failure.
428 typedef SMBCSRV * (*smbc_get_cached_srv_fn) (SMBCCTX * c, const char * server,
429 const char * share, const char * workgroup,
430 const char * username);
432 /**@ingroup callback
433 * Check if a server is still good
435 * @param c pointer to smb context
437 * @param srv pointer to server to remove
439 * @return 0 when found and removed. 1 on failure.
442 typedef int (*smbc_remove_cached_srv_fn)(SMBCCTX * c, SMBCSRV *srv);
445 /**@ingroup callback
446 * Try to remove all servers from the cache system and disconnect
448 * @param c pointer to smb context
450 * @return 0 when found and removed. 1 on failure.
453 typedef int (*smbc_purge_cached_fn) (SMBCCTX * c);
457 /*****************************************
458 * Getters and setters for CONFIGURATION *
459 *****************************************/
461 /** Get the debug level */
463 smbc_getDebug(SMBCCTX *c);
465 /** Set the debug level */
466 void
467 smbc_setDebug(SMBCCTX *c, int debug);
469 /** Get the netbios name used for making connections */
470 char *
471 smbc_getNetbiosName(SMBCCTX *c);
473 /** Set the netbios name used for making connections */
474 void
475 smbc_setNetbiosName(SMBCCTX *c, char * netbios_name);
477 /** Get the workgroup used for making connections */
478 char *
479 smbc_getWorkgroup(SMBCCTX *c);
481 /** Set the workgroup used for making connections */
482 void smbc_setWorkgroup(SMBCCTX *c, char * workgroup);
484 /** Get the username used for making connections */
485 char *
486 smbc_getUser(SMBCCTX *c);
488 /** Set the username used for making connections */
489 void
490 smbc_setUser(SMBCCTX *c, char * user);
493 * Get the timeout used for waiting on connections and response data
494 * (in milliseconds)
497 smbc_getTimeout(SMBCCTX *c);
500 * Set the timeout used for waiting on connections and response data
501 * (in milliseconds)
503 void
504 smbc_setTimeout(SMBCCTX *c, int timeout);
508 /***********************************
509 * Getters and setters for OPTIONS *
510 ***********************************/
512 /** Get whether to log to standard error instead of standard output */
513 smbc_bool
514 smbc_getOptionDebugToStderr(SMBCCTX *c);
516 /** Set whether to log to standard error instead of standard output */
517 void
518 smbc_setOptionDebugToStderr(SMBCCTX *c, smbc_bool b);
521 * Get whether to use new-style time attribute names, e.g. WRITE_TIME rather
522 * than the old-style names such as M_TIME. This allows also setting/getting
523 * CREATE_TIME which was previously unimplemented. (Note that the old C_TIME
524 * was supposed to be CHANGE_TIME but was confused and sometimes referred to
525 * CREATE_TIME.)
527 smbc_bool
528 smbc_getOptionFullTimeNames(SMBCCTX *c);
531 * Set whether to use new-style time attribute names, e.g. WRITE_TIME rather
532 * than the old-style names such as M_TIME. This allows also setting/getting
533 * CREATE_TIME which was previously unimplemented. (Note that the old C_TIME
534 * was supposed to be CHANGE_TIME but was confused and sometimes referred to
535 * CREATE_TIME.)
537 void
538 smbc_setOptionFullTimeNames(SMBCCTX *c, smbc_bool b);
541 * Get the share mode to use for files opened with SMBC_open_ctx(). The
542 * default is SMBC_SHAREMODE_DENY_NONE.
544 smbc_share_mode
545 smbc_getOptionOpenShareMode(SMBCCTX *c);
548 * Set the share mode to use for files opened with SMBC_open_ctx(). The
549 * default is SMBC_SHAREMODE_DENY_NONE.
551 void
552 smbc_setOptionOpenShareMode(SMBCCTX *c, smbc_share_mode share_mode);
554 /** Retrieve a previously saved user data handle */
555 void *
556 smbc_getOptionUserData(SMBCCTX *c);
558 /** Save a user data handle */
559 void
560 smbc_setOptionUserData(SMBCCTX *c, void *user_data);
562 /** Get the encoded value for encryption level. */
563 smbc_smb_encrypt_level
564 smbc_getOptionSmbEncryptionLevel(SMBCCTX *c);
566 /** Set the encoded value for encryption level. */
567 void
568 smbc_setOptionSmbEncryptionLevel(SMBCCTX *c, smbc_smb_encrypt_level level);
571 * Get whether to treat file names as case-sensitive if we can't determine
572 * when connecting to the remote share whether the file system is case
573 * sensitive. This defaults to FALSE since it's most likely that if we can't
574 * retrieve the file system attributes, it's a very old file system that does
575 * not support case sensitivity.
577 smbc_bool
578 smbc_getOptionCaseSensitive(SMBCCTX *c);
581 * Set whether to treat file names as case-sensitive if we can't determine
582 * when connecting to the remote share whether the file system is case
583 * sensitive. This defaults to FALSE since it's most likely that if we can't
584 * retrieve the file system attributes, it's a very old file system that does
585 * not support case sensitivity.
587 void
588 smbc_setOptionCaseSensitive(SMBCCTX *c, smbc_bool b);
592 * Get from how many local master browsers should the list of workgroups be
593 * retrieved. It can take up to 12 minutes or longer after a server becomes a
594 * local master browser, for it to have the entire browse list (the list of
595 * workgroups/domains) from an entire network. Since a client never knows
596 * which local master browser will be found first, the one which is found
597 * first and used to retrieve a browse list may have an incomplete or empty
598 * browse list. By requesting the browse list from multiple local master
599 * browsers, a more complete list can be generated. For small networks (few
600 * workgroups), it is recommended that this value be set to 0, causing the
601 * browse lists from all found local master browsers to be retrieved and
602 * merged. For networks with many workgroups, a suitable value for this
603 * variable is probably somewhere around 3. (Default: 3).
606 smbc_getOptionBrowseMaxLmbCount(SMBCCTX *c);
609 * Set 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).
622 void
623 smbc_setOptionBrowseMaxLmbCount(SMBCCTX *c, int count);
626 * Get whether to url-encode readdir entries.
628 * There is a difference in the desired return strings from
629 * smbc_readdir() depending upon whether the filenames are to
630 * be displayed to the user, or whether they are to be
631 * appended to the path name passed to smbc_opendir() to call
632 * a further smbc_ function (e.g. open the file with
633 * smbc_open()). In the former case, the filename should be
634 * in "human readable" form. In the latter case, the smbc_
635 * functions expect a URL which must be url-encoded. Those
636 * functions decode the URL. If, for example, smbc_readdir()
637 * returned a file name of "abc%20def.txt", passing a path
638 * with this file name attached to smbc_open() would cause
639 * smbc_open to attempt to open the file "abc def.txt" since
640 * the %20 is decoded into a space.
642 * Set this option to True if the names returned by
643 * smbc_readdir() should be url-encoded such that they can be
644 * passed back to another smbc_ call. Set it to False if the
645 * names returned by smbc_readdir() are to be presented to the
646 * user.
648 * For backwards compatibility, this option defaults to False.
650 smbc_bool
651 smbc_getOptionUrlEncodeReaddirEntries(SMBCCTX *c);
654 * Set whether to url-encode readdir entries.
656 * There is a difference in the desired return strings from
657 * smbc_readdir() depending upon whether the filenames are to
658 * be displayed to the user, or whether they are to be
659 * appended to the path name passed to smbc_opendir() to call
660 * a further smbc_ function (e.g. open the file with
661 * smbc_open()). In the former case, the filename should be
662 * in "human readable" form. In the latter case, the smbc_
663 * functions expect a URL which must be url-encoded. Those
664 * functions decode the URL. If, for example, smbc_readdir()
665 * returned a file name of "abc%20def.txt", passing a path
666 * with this file name attached to smbc_open() would cause
667 * smbc_open to attempt to open the file "abc def.txt" since
668 * the %20 is decoded into a space.
670 * Set this option to True if the names returned by
671 * smbc_readdir() should be url-encoded such that they can be
672 * passed back to another smbc_ call. Set it to False if the
673 * names returned by smbc_readdir() are to be presented to the
674 * user.
676 * For backwards compatibility, this option defaults to False.
678 void
679 smbc_setOptionUrlEncodeReaddirEntries(SMBCCTX *c, smbc_bool b);
682 * Get whether to use the same connection for all shares on a server.
684 * Some Windows versions appear to have a limit to the number
685 * of concurrent SESSIONs and/or TREE CONNECTions. In
686 * one-shot programs (i.e. the program runs and then quickly
687 * ends, thereby shutting down all connections), it is
688 * probably reasonable to establish a new connection for each
689 * share. In long-running applications, the limitation can be
690 * avoided by using only a single connection to each server,
691 * and issuing a new TREE CONNECT when the share is accessed.
693 smbc_bool
694 smbc_getOptionOneSharePerServer(SMBCCTX *c);
697 * Set whether to use the same connection for all shares on a server.
699 * Some Windows versions appear to have a limit to the number
700 * of concurrent SESSIONs and/or TREE CONNECTions. In
701 * one-shot programs (i.e. the program runs and then quickly
702 * ends, thereby shutting down all connections), it is
703 * probably reasonable to establish a new connection for each
704 * share. In long-running applications, the limitation can be
705 * avoided by using only a single connection to each server,
706 * and issuing a new TREE CONNECT when the share is accessed.
708 void
709 smbc_setOptionOneSharePerServer(SMBCCTX *c, smbc_bool b);
711 /** Get whether to enable use of kerberos */
712 smbc_bool
713 smbc_getOptionUseKerberos(SMBCCTX *c);
715 /** Set whether to enable use of kerberos */
716 void
717 smbc_setOptionUseKerberos(SMBCCTX *c, smbc_bool b);
719 /** Get whether to fallback after kerberos */
720 smbc_bool
721 smbc_getOptionFallbackAfterKerberos(SMBCCTX *c);
723 /** Set whether to fallback after kerberos */
724 void
725 smbc_setOptionFallbackAfterKerberos(SMBCCTX *c, smbc_bool b);
727 /** Get whether to automatically select anonymous login */
728 smbc_bool
729 smbc_getOptionNoAutoAnonymousLogin(SMBCCTX *c);
731 /** Set whether to automatically select anonymous login */
732 void
733 smbc_setOptionNoAutoAnonymousLogin(SMBCCTX *c, smbc_bool b);
737 /*************************************
738 * Getters and setters for FUNCTIONS *
739 *************************************/
741 /** Get the function for obtaining authentication data */
742 smbc_get_auth_data_fn smbc_getFunctionAuthData(SMBCCTX *c);
744 /** Set the function for obtaining authentication data */
745 void smbc_setFunctionAuthData(SMBCCTX *c, smbc_get_auth_data_fn fn);
747 /** Get the new-style authentication function which includes the context. */
748 smbc_get_auth_data_with_context_fn
749 smbc_getFunctionAuthDataWithContext(SMBCCTX *c);
751 /** Set the new-style authentication function which includes the context. */
752 void
753 smbc_setFunctionAuthDataWithContext(SMBCCTX *c,
754 smbc_get_auth_data_with_context_fn fn);
756 /** Get the function for checking if a server is still good */
757 smbc_check_server_fn smbc_getFunctionCheckServer(SMBCCTX *c);
759 /** Set the function for checking if a server is still good */
760 void smbc_setFunctionCheckServer(SMBCCTX *c, smbc_check_server_fn fn);
762 /** Get the function for removing a server if unused */
763 smbc_remove_unused_server_fn smbc_getFunctionRemoveUnusedServer(SMBCCTX *c);
765 /** Set the function for removing a server if unused */
766 void smbc_setFunctionRemoveUnusedServer(SMBCCTX *c,
767 smbc_remove_unused_server_fn fn);
769 /** Get the function for adding a cached server */
770 smbc_add_cached_srv_fn smbc_getFunctionAddCachedServer(SMBCCTX *c);
772 /** Set the function for adding a cached server */
773 void smbc_setFunctionAddCachedServer(SMBCCTX *c, smbc_add_cached_srv_fn fn);
775 /** Get the function for server cache lookup */
776 smbc_get_cached_srv_fn smbc_getFunctionGetCachedServer(SMBCCTX *c);
778 /** Set the function for server cache lookup */
779 void smbc_setFunctionGetCachedServer(SMBCCTX *c, smbc_get_cached_srv_fn fn);
781 /** Get the function for server cache removal */
782 smbc_remove_cached_srv_fn smbc_getFunctionRemoveCachedServer(SMBCCTX *c);
784 /** Set the function for server cache removal */
785 void smbc_setFunctionRemoveCachedServer(SMBCCTX *c,
786 smbc_remove_cached_srv_fn fn);
789 * Get the function for server cache purging. This function tries to
790 * remove all cached servers (e.g. on disconnect)
792 smbc_purge_cached_fn smbc_getFunctionPurgeCachedServers(SMBCCTX *c);
795 * Set the function for server cache purging. This function tries to
796 * remove all cached servers (e.g. on disconnect)
798 void smbc_setFunctionPurgeCachedServers(SMBCCTX *c,
799 smbc_purge_cached_fn fn);
801 /** Get the function to store private data of the server cache */
802 struct smbc_server_cache * smbc_getServerCacheData(SMBCCTX *c);
804 /** Set the function to store private data of the server cache */
805 void smbc_setServerCacheData(SMBCCTX *c, struct smbc_server_cache * cache);
809 /*****************************************************************
810 * Callable functions for files. *
811 * Each callable has a function signature typedef, a declaration *
812 * for the getter, and a declaration for the setter. *
813 *****************************************************************/
815 typedef SMBCFILE * (*smbc_open_fn)(SMBCCTX *c,
816 const char *fname,
817 int flags,
818 mode_t mode);
819 smbc_open_fn smbc_getFunctionOpen(SMBCCTX *c);
820 void smbc_setFunctionOpen(SMBCCTX *c, smbc_open_fn fn);
822 typedef SMBCFILE * (*smbc_creat_fn)(SMBCCTX *c,
823 const char *path,
824 mode_t mode);
825 smbc_creat_fn smbc_getFunctionCreat(SMBCCTX *c);
826 void smbc_setFunctionCreat(SMBCCTX *c, smbc_creat_fn);
828 typedef ssize_t (*smbc_read_fn)(SMBCCTX *c,
829 SMBCFILE *file,
830 void *buf,
831 size_t count);
832 smbc_read_fn smbc_getFunctionRead(SMBCCTX *c);
833 void smbc_setFunctionRead(SMBCCTX *c, smbc_read_fn fn);
835 typedef ssize_t (*smbc_write_fn)(SMBCCTX *c,
836 SMBCFILE *file,
837 const void *buf,
838 size_t count);
839 smbc_write_fn smbc_getFunctionWrite(SMBCCTX *c);
840 void smbc_setFunctionWrite(SMBCCTX *c, smbc_write_fn fn);
842 typedef int (*smbc_unlink_fn)(SMBCCTX *c,
843 const char *fname);
844 smbc_unlink_fn smbc_getFunctionUnlink(SMBCCTX *c);
845 void smbc_setFunctionUnlink(SMBCCTX *c, smbc_unlink_fn fn);
847 typedef int (*smbc_rename_fn)(SMBCCTX *ocontext,
848 const char *oname,
849 SMBCCTX *ncontext,
850 const char *nname);
851 smbc_rename_fn smbc_getFunctionRename(SMBCCTX *c);
852 void smbc_setFunctionRename(SMBCCTX *c, smbc_rename_fn fn);
854 typedef off_t (*smbc_lseek_fn)(SMBCCTX *c,
855 SMBCFILE * file,
856 off_t offset,
857 int whence);
858 smbc_lseek_fn smbc_getFunctionLseek(SMBCCTX *c);
859 void smbc_setFunctionLseek(SMBCCTX *c, smbc_lseek_fn fn);
861 typedef int (*smbc_stat_fn)(SMBCCTX *c,
862 const char *fname,
863 struct stat *st);
864 smbc_stat_fn smbc_getFunctionStat(SMBCCTX *c);
865 void smbc_setFunctionStat(SMBCCTX *c, smbc_stat_fn fn);
867 typedef int (*smbc_fstat_fn)(SMBCCTX *c,
868 SMBCFILE *file,
869 struct stat *st);
870 smbc_fstat_fn smbc_getFunctionFstat(SMBCCTX *c);
871 void smbc_setFunctionFstat(SMBCCTX *c, smbc_fstat_fn fn);
873 typedef int (*smbc_statvfs_fn)(SMBCCTX *c,
874 char *path,
875 struct statvfs *st);
876 smbc_statvfs_fn smbc_getFunctionStatVFS(SMBCCTX *c);
877 void smbc_setFunctionStatVFS(SMBCCTX *c, smbc_statvfs_fn fn);
879 typedef int (*smbc_fstatvfs_fn)(SMBCCTX *c,
880 SMBCFILE *file,
881 struct statvfs *st);
882 smbc_fstatvfs_fn smbc_getFunctionFstatVFS(SMBCCTX *c);
883 void smbc_setFunctionFstatVFS(SMBCCTX *c, smbc_fstatvfs_fn fn);
885 typedef int (*smbc_ftruncate_fn)(SMBCCTX *c,
886 SMBCFILE *f,
887 off_t size);
888 smbc_ftruncate_fn smbc_getFunctionFtruncate(SMBCCTX *c);
889 void smbc_setFunctionFtruncate(SMBCCTX *c, smbc_ftruncate_fn fn);
891 typedef int (*smbc_close_fn)(SMBCCTX *c,
892 SMBCFILE *file);
893 smbc_close_fn smbc_getFunctionClose(SMBCCTX *c);
894 void smbc_setFunctionClose(SMBCCTX *c, smbc_close_fn fn);
898 /*****************************************************************
899 * Callable functions for directories. *
900 * Each callable has a function signature typedef, a declaration *
901 * for the getter, and a declaration for the setter. *
902 *****************************************************************/
904 typedef SMBCFILE * (*smbc_opendir_fn)(SMBCCTX *c,
905 const char *fname);
906 smbc_opendir_fn smbc_getFunctionOpendir(SMBCCTX *c);
907 void smbc_setFunctionOpendir(SMBCCTX *c, smbc_opendir_fn fn);
909 typedef int (*smbc_closedir_fn)(SMBCCTX *c,
910 SMBCFILE *dir);
911 smbc_closedir_fn smbc_getFunctionClosedir(SMBCCTX *c);
912 void smbc_setFunctionClosedir(SMBCCTX *c, smbc_closedir_fn fn);
914 typedef struct smbc_dirent * (*smbc_readdir_fn)(SMBCCTX *c,
915 SMBCFILE *dir);
916 smbc_readdir_fn smbc_getFunctionReaddir(SMBCCTX *c);
917 void smbc_setFunctionReaddir(SMBCCTX *c, smbc_readdir_fn fn);
919 typedef int (*smbc_getdents_fn)(SMBCCTX *c,
920 SMBCFILE *dir,
921 struct smbc_dirent *dirp,
922 int count);
923 smbc_getdents_fn smbc_getFunctionGetdents(SMBCCTX *c);
924 void smbc_setFunctionGetdents(SMBCCTX *c, smbc_getdents_fn fn);
926 typedef int (*smbc_mkdir_fn)(SMBCCTX *c,
927 const char *fname,
928 mode_t mode);
929 smbc_mkdir_fn smbc_getFunctionMkdir(SMBCCTX *c);
930 void smbc_setFunctionMkdir(SMBCCTX *c, smbc_mkdir_fn fn);
932 typedef int (*smbc_rmdir_fn)(SMBCCTX *c,
933 const char *fname);
934 smbc_rmdir_fn smbc_getFunctionRmdir(SMBCCTX *c);
935 void smbc_setFunctionRmdir(SMBCCTX *c, smbc_rmdir_fn fn);
937 typedef off_t (*smbc_telldir_fn)(SMBCCTX *c,
938 SMBCFILE *dir);
939 smbc_telldir_fn smbc_getFunctionTelldir(SMBCCTX *c);
940 void smbc_setFunctionTelldir(SMBCCTX *c, smbc_telldir_fn fn);
942 typedef int (*smbc_lseekdir_fn)(SMBCCTX *c,
943 SMBCFILE *dir,
944 off_t offset);
945 smbc_lseekdir_fn smbc_getFunctionLseekdir(SMBCCTX *c);
946 void smbc_setFunctionLseekdir(SMBCCTX *c, smbc_lseekdir_fn fn);
948 typedef int (*smbc_fstatdir_fn)(SMBCCTX *c,
949 SMBCFILE *dir,
950 struct stat *st);
951 smbc_fstatdir_fn smbc_getFunctionFstatdir(SMBCCTX *c);
952 void smbc_setFunctionFstatdir(SMBCCTX *c, smbc_fstatdir_fn fn);
956 /*****************************************************************
957 * Callable functions applicable to both files and directories. *
958 * Each callable has a function signature typedef, a declaration *
959 * for the getter, and a declaration for the setter. *
960 *****************************************************************/
962 typedef int (*smbc_chmod_fn)(SMBCCTX *c,
963 const char *fname,
964 mode_t mode);
965 smbc_chmod_fn smbc_getFunctionChmod(SMBCCTX *c);
966 void smbc_setFunctionChmod(SMBCCTX *c, smbc_chmod_fn fn);
968 typedef int (*smbc_utimes_fn)(SMBCCTX *c,
969 const char *fname,
970 struct timeval *tbuf);
971 smbc_utimes_fn smbc_getFunctionUtimes(SMBCCTX *c);
972 void smbc_setFunctionUtimes(SMBCCTX *c, smbc_utimes_fn fn);
974 typedef int (*smbc_setxattr_fn)(SMBCCTX *context,
975 const char *fname,
976 const char *name,
977 const void *value,
978 size_t size,
979 int flags);
980 smbc_setxattr_fn smbc_getFunctionSetxattr(SMBCCTX *c);
981 void smbc_setFunctionSetxattr(SMBCCTX *c, smbc_setxattr_fn fn);
983 typedef int (*smbc_getxattr_fn)(SMBCCTX *context,
984 const char *fname,
985 const char *name,
986 const void *value,
987 size_t size);
988 smbc_getxattr_fn smbc_getFunctionGetxattr(SMBCCTX *c);
989 void smbc_setFunctionGetxattr(SMBCCTX *c, smbc_getxattr_fn fn);
991 typedef int (*smbc_removexattr_fn)(SMBCCTX *context,
992 const char *fname,
993 const char *name);
994 smbc_removexattr_fn smbc_getFunctionRemovexattr(SMBCCTX *c);
995 void smbc_setFunctionRemovexattr(SMBCCTX *c, smbc_removexattr_fn fn);
997 typedef int (*smbc_listxattr_fn)(SMBCCTX *context,
998 const char *fname,
999 char *list,
1000 size_t size);
1001 smbc_listxattr_fn smbc_getFunctionListxattr(SMBCCTX *c);
1002 void smbc_setFunctionListxattr(SMBCCTX *c, smbc_listxattr_fn fn);
1006 /*****************************************************************
1007 * Callable functions for printing. *
1008 * Each callable has a function signature typedef, a declaration *
1009 * for the getter, and a declaration for the setter. *
1010 *****************************************************************/
1012 typedef int (*smbc_print_file_fn)(SMBCCTX *c_file,
1013 const char *fname,
1014 SMBCCTX *c_print,
1015 const char *printq);
1016 smbc_print_file_fn smbc_getFunctionPrintFile(SMBCCTX *c);
1017 void smbc_setFunctionPrintFile(SMBCCTX *c, smbc_print_file_fn fn);
1019 typedef SMBCFILE * (*smbc_open_print_job_fn)(SMBCCTX *c,
1020 const char *fname);
1021 smbc_open_print_job_fn smbc_getFunctionOpenPrintJob(SMBCCTX *c);
1022 void smbc_setFunctionOpenPrintJob(SMBCCTX *c,
1023 smbc_open_print_job_fn fn);
1025 typedef int (*smbc_list_print_jobs_fn)(SMBCCTX *c,
1026 const char *fname,
1027 smbc_list_print_job_fn fn);
1028 smbc_list_print_jobs_fn smbc_getFunctionListPrintJobs(SMBCCTX *c);
1029 void smbc_setFunctionListPrintJobs(SMBCCTX *c,
1030 smbc_list_print_jobs_fn fn);
1032 typedef int (*smbc_unlink_print_job_fn)(SMBCCTX *c,
1033 const char *fname,
1034 int id);
1035 smbc_unlink_print_job_fn smbc_getFunctionUnlinkPrintJob(SMBCCTX *c);
1036 void smbc_setFunctionUnlinkPrintJob(SMBCCTX *c,
1037 smbc_unlink_print_job_fn fn);
1040 /**@ingroup misc
1041 * Create a new SBMCCTX (a context).
1043 * Must be called before the context is passed to smbc_context_init()
1045 * @return The given SMBCCTX pointer on success, NULL on error with errno set:
1046 * - ENOMEM Out of memory
1048 * @see smbc_free_context(), smbc_init_context()
1050 * @note Do not forget to smbc_init_context() the returned SMBCCTX pointer !
1052 SMBCCTX * smbc_new_context(void);
1054 /**@ingroup misc
1055 * Delete a SBMCCTX (a context) acquired from smbc_new_context().
1057 * The context will be deleted if possible.
1059 * @param context A pointer to a SMBCCTX obtained from smbc_new_context()
1061 * @param shutdown_ctx If 1, all connections and files will be closed even if they are busy.
1064 * @return Returns 0 on succes. Returns 1 on failure with errno set:
1065 * - EBUSY Server connections are still used, Files are open or cache
1066 * could not be purged
1067 * - EBADF context == NULL
1069 * @see smbc_new_context()
1071 * @note It is advised to clean up all the contexts with shutdown_ctx set to 1
1072 * just before exit()'ing. When shutdown_ctx is 0, this function can be
1073 * use in periodical cleanup functions for example.
1075 int smbc_free_context(SMBCCTX * context, int shutdown_ctx);
1078 /**@ingroup misc
1080 * @deprecated. Use smbc_setOption*() functions instead.
1082 void
1083 smbc_option_set(SMBCCTX *context,
1084 char *option_name,
1085 ... /* option_value */);
1088 * @deprecated. Use smbc_getOption*() functions instead.
1090 void *
1091 smbc_option_get(SMBCCTX *context,
1092 char *option_name);
1094 /**@ingroup misc
1095 * Initialize a SBMCCTX (a context).
1097 * Must be called before using any SMBCCTX API function
1099 * @param context A pointer to a SMBCCTX obtained from smbc_new_context()
1101 * @return A pointer to the given SMBCCTX on success,
1102 * NULL on error with errno set:
1103 * - EBADF NULL context given
1104 * - ENOMEM Out of memory
1105 * - ENOENT The smb.conf file would not load
1107 * @see smbc_new_context()
1109 * @note my_context = smbc_init_context(smbc_new_context())
1110 * is perfectly safe, but it might leak memory on
1111 * smbc_context_init() failure. Avoid this.
1112 * You'll have to call smbc_free_context() yourself
1113 * on failure.
1116 SMBCCTX * smbc_init_context(SMBCCTX * context);
1118 /**@ingroup misc
1119 * Initialize the samba client library.
1121 * Must be called before using any of the smbclient API function
1123 * @param fn The function that will be called to obtaion
1124 * authentication credentials.
1126 * @param debug Allows caller to set the debug level. Can be
1127 * changed in smb.conf file. Allows caller to set
1128 * debugging if no smb.conf.
1130 * @return 0 on success, < 0 on error with errno set:
1131 * - ENOMEM Out of memory
1132 * - ENOENT The smb.conf file would not load
1136 int smbc_init(smbc_get_auth_data_fn fn, int debug);
1138 /**@ingroup misc
1139 * Set or retrieve the compatibility library's context pointer
1141 * @param context New context to use, or NULL. If a new context is provided,
1142 * it must have allocated with smbc_new_context() and
1143 * initialized with smbc_init_context(), followed, optionally,
1144 * by some manual changes to some of the non-internal fields.
1146 * @return The old context.
1148 * @see smbc_new_context(), smbc_init_context(), smbc_init()
1150 * @note This function may be called prior to smbc_init() to force
1151 * use of the next context without any internal calls to
1152 * smbc_new_context() or smbc_init_context(). It may also
1153 * be called after smbc_init() has already called those two
1154 * functions, to replace the existing context with a new one.
1155 * Care should be taken, in this latter case, to ensure that
1156 * the server cache and any data allocated by the
1157 * authentication functions have been freed, if necessary.
1160 SMBCCTX * smbc_set_context(SMBCCTX * new_context);
1162 /**@ingroup file
1163 * Open a file on an SMB server.
1165 * @param furl The smb url of the file to be opened.
1167 * @param flags Is one of O_RDONLY, O_WRONLY or O_RDWR which
1168 * request opening the file read-only,write-only
1169 * or read/write. flags may also be bitwise-or'd with
1170 * one or more of the following:
1171 * O_CREAT - If the file does not exist it will be
1172 * created.
1173 * O_EXCL - When used with O_CREAT, if the file
1174 * already exists it is an error and the open will
1175 * fail.
1176 * O_TRUNC - If the file already exists it will be
1177 * truncated.
1178 * O_APPEND The file is opened in append mode
1180 * @param mode mode specifies the permissions to use if a new
1181 * file is created. It is modified by the
1182 * process's umask in the usual way: the permissions
1183 * of the created file are (mode & ~umask)
1185 * Not currently use, but there for future use.
1186 * We will map this to SYSTEM, HIDDEN, etc bits
1187 * that reverses the mapping that smbc_fstat does.
1189 * @return Valid file handle, < 0 on error with errno set:
1190 * - ENOMEM Out of memory
1191 * - EINVAL if an invalid parameter passed, like no
1192 * file, or smbc_init not called.
1193 * - EEXIST pathname already exists and O_CREAT and
1194 * O_EXCL were used.
1195 * - EISDIR pathname refers to a directory and
1196 * the access requested involved writing.
1197 * - EACCES The requested access to the file is not
1198 * allowed
1199 * - ENODEV The requested share does not exist
1200 * - ENOTDIR A file on the path is not a directory
1201 * - ENOENT A directory component in pathname does
1202 * not exist.
1204 * @see smbc_creat()
1206 * @note This call uses an underlying routine that may create
1207 * a new connection to the server specified in the URL.
1208 * If the credentials supplied in the URL, or via the
1209 * auth_fn in the smbc_init call, fail, this call will
1210 * try again with an empty username and password. This
1211 * often gets mapped to the guest account on some machines.
1214 int smbc_open(const char *furl, int flags, mode_t mode);
1216 /**@ingroup file
1217 * Create a file on an SMB server.
1219 * Same as calling smbc_open() with flags = O_CREAT|O_WRONLY|O_TRUNC
1221 * @param furl The smb url of the file to be created
1223 * @param mode mode specifies the permissions to use if a new
1224 * file is created. It is modified by the
1225 * process's umask in the usual way: the permissions
1226 * of the created file are (mode & ~umask)
1228 * NOTE, the above is not true. We are dealing with
1229 * an SMB server, which has no concept of a umask!
1231 * @return Valid file handle, < 0 on error with errno set:
1232 * - ENOMEM Out of memory
1233 * - EINVAL if an invalid parameter passed, like no
1234 * file, or smbc_init not called.
1235 * - EEXIST pathname already exists and O_CREAT and
1236 * O_EXCL were used.
1237 * - EISDIR pathname refers to a directory and
1238 * the access requested involved writing.
1239 * - EACCES The requested access to the file is not
1240 * allowed
1241 * - ENOENT A directory component in pathname does
1242 * not exist.
1243 * - ENODEV The requested share does not exist.
1244 * @see smbc_open()
1248 int smbc_creat(const char *furl, mode_t mode);
1250 /**@ingroup file
1251 * Read from a file using an opened file handle.
1253 * @param fd Open file handle from smbc_open() or smbc_creat()
1255 * @param buf Pointer to buffer to recieve read data
1257 * @param bufsize Size of buf in bytes
1259 * @return Number of bytes read, < 0 on error with errno set:
1260 * - EISDIR fd refers to a directory
1261 * - EBADF fd is not a valid file descriptor or
1262 * is not open for reading.
1263 * - EINVAL fd is attached to an object which is
1264 * unsuitable for reading, or no buffer passed or
1265 * smbc_init not called.
1267 * @see smbc_open(), smbc_write()
1270 ssize_t smbc_read(int fd, void *buf, size_t bufsize);
1273 /**@ingroup file
1274 * Write to a file using an opened file handle.
1276 * @param fd Open file handle from smbc_open() or smbc_creat()
1278 * @param buf Pointer to buffer to recieve read data
1280 * @param bufsize Size of buf in bytes
1282 * @return Number of bytes written, < 0 on error with errno set:
1283 * - EISDIR fd refers to a directory.
1284 * - EBADF fd is not a valid file descriptor or
1285 * is not open for reading.
1286 * - EINVAL fd is attached to an object which is
1287 * unsuitable for reading, or no buffer passed or
1288 * smbc_init not called.
1290 * @see smbc_open(), smbc_read()
1293 ssize_t smbc_write(int fd, const void *buf, size_t bufsize);
1296 /**@ingroup file
1297 * Seek to a specific location in a file.
1299 * @param fd Open file handle from smbc_open() or smbc_creat()
1301 * @param offset Offset in bytes from whence
1303 * @param whence A location in the file:
1304 * - SEEK_SET The offset is set to offset bytes from
1305 * the beginning of the file
1306 * - SEEK_CUR The offset is set to current location
1307 * plus offset bytes.
1308 * - SEEK_END The offset is set to the size of the
1309 * file plus offset bytes.
1311 * @return Upon successful completion, lseek returns the
1312 * resulting offset location as measured in bytes
1313 * from the beginning of the file. Otherwise, a value
1314 * of (off_t)-1 is returned and errno is set to
1315 * indicate the error:
1316 * - EBADF Fildes is not an open file descriptor.
1317 * - EINVAL Whence is not a proper value or smbc_init
1318 * not called.
1320 * @todo Are all the whence values really supported?
1322 * @todo Are errno values complete and correct?
1324 off_t smbc_lseek(int fd, off_t offset, int whence);
1327 /**@ingroup file
1328 * Close an open file handle.
1330 * @param fd The file handle to close
1332 * @return 0 on success, < 0 on error with errno set:
1333 * - EBADF fd isn't a valid open file descriptor
1334 * - EINVAL smbc_init() failed or has not been called
1336 * @see smbc_open(), smbc_creat()
1338 int smbc_close(int fd);
1341 /**@ingroup directory
1342 * Unlink (delete) a file or directory.
1344 * @param furl The smb url of the file to delete
1346 * @return 0 on success, < 0 on error with errno set:
1347 * - EACCES or EPERM Write access to the directory
1348 * containing pathname is not allowed or one
1349 * of the directories in pathname did not allow
1350 * search (execute) permission
1351 * - ENOENT A directory component in pathname does
1352 * not exist
1353 * - EINVAL NULL was passed in the file param or
1354 * smbc_init not called.
1355 * - EACCES You do not have access to the file
1356 * - ENOMEM Insufficient kernel memory was available
1358 * @see smbc_rmdir()s
1360 * @todo Are errno values complete and correct?
1362 int smbc_unlink(const char *furl);
1365 /**@ingroup directory
1366 * Rename or move a file or directory.
1368 * @param ourl The original smb url (source url) of file or
1369 * directory to be moved
1371 * @param nurl The new smb url (destination url) of the file
1372 * or directory after the move. Currently nurl must
1373 * be on the same share as ourl.
1375 * @return 0 on success, < 0 on error with errno set:
1376 * - EISDIR nurl is an existing directory, but ourl is
1377 * not a directory.
1378 * - EEXIST nurl is a non-empty directory,
1379 * i.e., contains entries other than "." and ".."
1380 * - EINVAL The new url contained a path prefix
1381 * of the old, or, more generally, an attempt was
1382 * made to make a directory a subdirectory of itself
1383 * or smbc_init not called.
1384 * - ENOTDIR A component used as a directory in ourl
1385 * or nurl path is not, in fact, a directory. Or,
1386 * ourl is a directory, and newpath exists but is not
1387 * a directory.
1388 * - EACCES or EPERM Write access to the directory
1389 * containing ourl or nurl is not allowed for the
1390 * process's effective uid, or one of the
1391 * directories in ourl or nurl did not allow search
1392 * (execute) permission, or ourl was a directory
1393 * and did not allow write permission.
1394 * - ENOENT A directory component in ourl or nurl
1395 * does not exist.
1396 * - EXDEV Rename across shares not supported.
1397 * - ENOMEM Insufficient kernel memory was available.
1398 * - EEXIST The target file, nurl, already exists.
1401 * @todo Are we going to support copying when urls are not on the same
1402 * share? I say no... NOTE. I agree for the moment.
1405 int smbc_rename(const char *ourl, const char *nurl);
1408 /**@ingroup directory
1409 * Open a directory used to obtain directory entries.
1411 * @param durl The smb url of the directory to open
1413 * @return Valid directory handle. < 0 on error with errno set:
1414 * - EACCES Permission denied.
1415 * - EINVAL A NULL file/URL was passed, or the URL would
1416 * not parse, or was of incorrect form or smbc_init not
1417 * called.
1418 * - ENOENT durl does not exist, or name is an
1419 * - ENOMEM Insufficient memory to complete the
1420 * operation.
1421 * - ENOTDIR name is not a directory.
1422 * - EPERM the workgroup could not be found.
1423 * - ENODEV the workgroup or server could not be found.
1425 * @see smbc_getdents(), smbc_readdir(), smbc_closedir()
1428 int smbc_opendir(const char *durl);
1431 /**@ingroup directory
1432 * Close a directory handle opened by smbc_opendir().
1434 * @param dh Directory handle to close
1436 * @return 0 on success, < 0 on error with errno set:
1437 * - EBADF dh is an invalid directory handle
1439 * @see smbc_opendir()
1441 int smbc_closedir(int dh);
1444 /**@ingroup directory
1445 * Get multiple directory entries.
1447 * smbc_getdents() reads as many dirent structures from the an open
1448 * directory handle into a specified memory area as will fit.
1450 * @param dh Valid directory as returned by smbc_opendir()
1452 * @param dirp pointer to buffer that will receive the directory
1453 * entries.
1455 * @param count The size of the dirp buffer in bytes
1457 * @returns If any dirents returned, return will indicate the
1458 * total size. If there were no more dirents available,
1459 * 0 is returned. < 0 indicates an error.
1460 * - EBADF Invalid directory handle
1461 * - EINVAL Result buffer is too small or smbc_init
1462 * not called.
1463 * - ENOENT No such directory.
1464 * @see , smbc_dirent, smbc_readdir(), smbc_open()
1466 * @todo Are errno values complete and correct?
1468 * @todo Add example code so people know how to parse buffers.
1470 int smbc_getdents(unsigned int dh, struct smbc_dirent *dirp, int count);
1473 /**@ingroup directory
1474 * Get a single directory entry.
1476 * @param dh Valid directory as returned by smbc_opendir()
1478 * @return A pointer to a smbc_dirent structure, or NULL if an
1479 * error occurs or end-of-directory is reached:
1480 * - EBADF Invalid directory handle
1481 * - EINVAL smbc_init() failed or has not been called
1483 * @see smbc_dirent, smbc_getdents(), smbc_open()
1485 struct smbc_dirent* smbc_readdir(unsigned int dh);
1488 /**@ingroup directory
1489 * Get the current directory offset.
1491 * smbc_telldir() may be used in conjunction with smbc_readdir() and
1492 * smbc_lseekdir().
1494 * @param dh Valid directory as returned by smbc_opendir()
1496 * @return The current location in the directory stream or -1
1497 * if an error occur. The current location is not
1498 * an offset. Becuase of the implementation, it is a
1499 * handle that allows the library to find the entry
1500 * later.
1501 * - EBADF dh is not a valid directory handle
1502 * - EINVAL smbc_init() failed or has not been called
1503 * - ENOTDIR if dh is not a directory
1505 * @see smbc_readdir()
1508 off_t smbc_telldir(int dh);
1511 /**@ingroup directory
1512 * lseek on directories.
1514 * smbc_lseekdir() may be used in conjunction with smbc_readdir() and
1515 * smbc_telldir(). (rewind by smbc_lseekdir(fd, NULL))
1517 * @param fd Valid directory as returned by smbc_opendir()
1519 * @param offset The offset (as returned by smbc_telldir). Can be
1520 * NULL, in which case we will rewind
1522 * @return 0 on success, -1 on failure
1523 * - EBADF dh is not a valid directory handle
1524 * - ENOTDIR if dh is not a directory
1525 * - EINVAL offset did not refer to a valid dirent or
1526 * smbc_init not called.
1528 * @see smbc_telldir()
1531 * @todo In what does the reture and errno values mean?
1533 int smbc_lseekdir(int fd, off_t offset);
1535 /**@ingroup directory
1536 * Create a directory.
1538 * @param durl The url of the directory to create
1540 * @param mode Specifies the permissions to use. It is modified
1541 * by the process's umask in the usual way: the
1542 * permissions of the created file are (mode & ~umask).
1544 * @return 0 on success, < 0 on error with errno set:
1545 * - EEXIST directory url already exists
1546 * - EACCES The parent directory does not allow write
1547 * permission to the process, or one of the directories
1548 * - ENOENT A directory component in pathname does not
1549 * exist.
1550 * - EINVAL NULL durl passed or smbc_init not called.
1551 * - ENOMEM Insufficient memory was available.
1553 * @see smbc_rmdir()
1556 int smbc_mkdir(const char *durl, mode_t mode);
1559 /**@ingroup directory
1560 * Remove a directory.
1562 * @param durl The smb url of the directory to remove
1564 * @return 0 on success, < 0 on error with errno set:
1565 * - EACCES or EPERM Write access to the directory
1566 * containing pathname was not allowed.
1567 * - EINVAL durl is NULL or smbc_init not called.
1568 * - ENOENT A directory component in pathname does not
1569 * exist.
1570 * - ENOTEMPTY directory contains entries.
1571 * - ENOMEM Insufficient kernel memory was available.
1573 * @see smbc_mkdir(), smbc_unlink()
1575 * @todo Are errno values complete and correct?
1577 int smbc_rmdir(const char *durl);
1580 /**@ingroup attribute
1581 * Get information about a file or directory.
1583 * @param url The smb url to get information for
1585 * @param st pointer to a buffer that will be filled with
1586 * standard Unix struct stat information.
1588 * @return 0 on success, < 0 on error with errno set:
1589 * - ENOENT A component of the path file_name does not
1590 * exist.
1591 * - EINVAL a NULL url was passed or smbc_init not called.
1592 * - EACCES Permission denied.
1593 * - ENOMEM Out of memory
1594 * - ENOTDIR The target dir, url, is not a directory.
1596 * @see Unix stat()
1599 int smbc_stat(const char *url, struct stat *st);
1602 /**@ingroup attribute
1603 * Get file information via an file descriptor.
1605 * @param fd Open file handle from smbc_open() or smbc_creat()
1607 * @param st pointer to a buffer that will be filled with
1608 * standard Unix struct stat information.
1610 * @return EBADF filedes is bad.
1611 * - EACCES Permission denied.
1612 * - EBADF fd is not a valid file descriptor
1613 * - EINVAL Problems occurred in the underlying routines
1614 * or smbc_init not called.
1615 * - ENOMEM Out of memory
1617 * @see smbc_stat(), Unix stat()
1620 int smbc_fstat(int fd, struct stat *st);
1623 /**@ingroup attribute
1624 * Get file system information for a specified path.
1626 * @param url The smb url to get information for
1628 * @param st pointer to a buffer that will be filled with
1629 * standard Unix struct statvfs information.
1631 * @return EBADF filedes is bad.
1632 * - EACCES Permission denied.
1633 * - EBADF fd is not a valid file descriptor
1634 * - EINVAL Problems occurred in the underlying routines
1635 * or smbc_init not called.
1636 * - ENOMEM Out of memory
1638 * @see Unix fstatvfs()
1642 smbc_statvfs(char *url,
1643 struct statvfs *st);
1645 /**@ingroup attribute
1646 * Get file system information via an file descriptor.
1648 * @param fd Open file handle from smbc_open(), smbc_creat(),
1649 * or smbc_opendir()
1651 * @param st pointer to a buffer that will be filled with
1652 * standard Unix struct statvfs information.
1654 * @return EBADF filedes is bad.
1655 * - EACCES Permission denied.
1656 * - EBADF fd is not a valid file descriptor
1657 * - EINVAL Problems occurred in the underlying routines
1658 * or smbc_init not called.
1659 * - ENOMEM Out of memory
1661 * @see Unix fstatvfs()
1665 smbc_fstatvfs(int fd,
1666 struct statvfs *st);
1669 /**@ingroup attribute
1670 * Truncate a file given a file descriptor
1672 * @param fd Open file handle from smbc_open() or smbc_creat()
1674 * @param size size to truncate the file to
1676 * @return EBADF filedes is bad.
1677 * - EACCES Permission denied.
1678 * - EBADF fd is not a valid file descriptor
1679 * - EINVAL Problems occurred in the underlying routines
1680 * or smbc_init not called.
1681 * - ENOMEM Out of memory
1683 * @see , Unix ftruncate()
1686 int smbc_ftruncate(int fd, off_t size);
1689 /**@ingroup attribute
1690 * Change the permissions of a file.
1692 * @param url The smb url of the file or directory to change
1693 * permissions of
1695 * @param mode The permissions to set:
1696 * - Put good explaination of permissions here!
1698 * @return 0 on success, < 0 on error with errno set:
1699 * - EPERM The effective UID does not match the owner
1700 * of the file, and is not zero
1701 * - ENOENT The file does not exist.
1702 * - ENOMEM Insufficient was available.
1703 * - ENOENT file or directory does not exist
1705 * @todo Actually implement this fuction?
1707 * @todo Are errno values complete and correct?
1709 int smbc_chmod(const char *url, mode_t mode);
1712 * @ingroup attribute
1713 * Change the last modification time on a file
1715 * @param url The smb url of the file or directory to change
1716 * the modification time of
1718 * @param tbuf An array of two timeval structures which contains,
1719 * respectively, the desired access and modification times.
1720 * NOTE: Only the tv_sec field off each timeval structure is
1721 * used. The tv_usec (microseconds) portion is ignored.
1723 * @return 0 on success, < 0 on error with errno set:
1724 * - EINVAL The client library is not properly initialized
1725 * - EPERM Permission was denied.
1728 int smbc_utimes(const char *url, struct timeval *tbuf);
1730 #ifdef HAVE_UTIME_H
1732 * @ingroup attribute
1733 * Change the last modification time on a file
1735 * @param url The smb url of the file or directory to change
1736 * the modification time of
1738 * @param utbuf A pointer to a utimebuf structure which contains the
1739 * desired access and modification times.
1741 * @return 0 on success, < 0 on error with errno set:
1742 * - EINVAL The client library is not properly initialized
1743 * - ENOMEM No memory was available for internal needs
1744 * - EPERM Permission was denied.
1747 int smbc_utime(const char *fname, struct utimbuf *utbuf);
1748 #endif
1750 /**@ingroup attribute
1751 * Set extended attributes for a file. This is used for modifying a file's
1752 * security descriptor (i.e. owner, group, and access control list)
1754 * @param url The smb url of the file or directory to set extended
1755 * attributes for.
1757 * @param name The name of an attribute to be changed. Names are of
1758 * one of the following forms:
1760 * system.nt_sec_desc.<attribute name>
1761 * system.nt_sec_desc.*
1762 * system.nt_sec_desc.*+
1764 * where <attribute name> is one of:
1766 * revision
1767 * owner
1768 * owner+
1769 * group
1770 * group+
1771 * acl:<name or sid>
1772 * acl+:<name or sid>
1774 * In the forms "system.nt_sec_desc.*" and
1775 * "system.nt_sec_desc.*+", the asterisk and plus signs are
1776 * literal, i.e. the string is provided exactly as shown, and
1777 * the value parameter should contain a complete security
1778 * descriptor with name:value pairs separated by tabs,
1779 * commas, or newlines (not spaces!).
1781 * The plus sign ('+') indicates that SIDs should be mapped
1782 * to names. Without the plus sign, SIDs are not mapped;
1783 * rather they are simply converted to a string format.
1785 * @param value The value to be assigned to the specified attribute name.
1786 * This buffer should contain only the attribute value if the
1787 * name was of the "system.nt_sec_desc.<attribute_name>"
1788 * form. If the name was of the "system.nt_sec_desc.*" form
1789 * then a complete security descriptor, with name:value pairs
1790 * separated by tabs, commas, or newlines (not spaces!),
1791 * should be provided in this value buffer. A complete
1792 * security descriptor will contain one or more entries
1793 * selected from the following:
1795 * REVISION:<revision number>
1796 * OWNER:<sid or name>
1797 * GROUP:<sid or name>
1798 * ACL:<sid or name>:<type>/<flags>/<mask>
1800 * The revision of the ACL specifies the internal Windows NT
1801 * ACL revision for the security descriptor. If not specified
1802 * it defaults to 1. Using values other than 1 may cause
1803 * strange behaviour.
1805 * The owner and group specify the owner and group sids for
1806 * the object. If the attribute name (either '*+' with a
1807 * complete security descriptor, or individual 'owner+' or
1808 * 'group+' attribute names) ended with a plus sign, the
1809 * specified name is resolved to a SID value, using the
1810 * server on which the file or directory resides. Otherwise,
1811 * the value should be provided in SID-printable format as
1812 * S-1-x-y-z, and is used directly. The <sid or name>
1813 * associated with the ACL: attribute should be provided
1814 * similarly.
1816 * @param size The number of the bytes of data in the value buffer
1818 * @param flags A bit-wise OR of zero or more of the following:
1819 * SMBC_XATTR_FLAG_CREATE -
1820 * fail if the named attribute already exists
1821 * SMBC_XATTR_FLAG_REPLACE -
1822 * fail if the attribute does not already exist
1824 * If neither flag is specified, the specified attributes
1825 * will be added or replace existing attributes of the same
1826 * name, as necessary.
1828 * @return 0 on success, < 0 on error with errno set:
1829 * - EINVAL The client library is not properly initialized
1830 * or one of the parameters is not of a correct
1831 * form
1832 * - ENOMEM No memory was available for internal needs
1833 * - EEXIST If the attribute already exists and the flag
1834 * SMBC_XATTR_FLAG_CREAT was specified
1835 * - ENOATTR If the attribute does not exist and the flag
1836 * SMBC_XATTR_FLAG_REPLACE was specified
1837 * - EPERM Permission was denied.
1838 * - ENOTSUP The referenced file system does not support
1839 * extended attributes
1841 * @note Attribute names are compared in a case-insensitive
1842 * fashion. All of the following are equivalent, although
1843 * the all-lower-case name is the preferred format:
1844 * system.nt_sec_desc.owner
1845 * SYSTEM.NT_SEC_DESC.OWNER
1846 * sYsTeM.nt_sEc_desc.owNER
1849 int smbc_setxattr(const char *url,
1850 const char *name,
1851 const void *value,
1852 size_t size,
1853 int flags);
1856 /**@ingroup attribute
1857 * Set extended attributes for a file. This is used for modifying a file's
1858 * security descriptor (i.e. owner, group, and access control list). The
1859 * POSIX function which this maps to would act on a symbolic link rather than
1860 * acting on what the symbolic link points to, but with no symbolic links in
1861 * SMB file systems, this function is functionally identical to
1862 * smbc_setxattr().
1864 * @param url The smb url of the file or directory to set extended
1865 * attributes for.
1867 * @param name The name of an attribute to be changed. Names are of
1868 * one of the following forms:
1870 * system.nt_sec_desc.<attribute name>
1871 * system.nt_sec_desc.*
1872 * system.nt_sec_desc.*+
1874 * where <attribute name> is one of:
1876 * revision
1877 * owner
1878 * owner+
1879 * group
1880 * group+
1881 * acl:<name or sid>
1882 * acl+:<name or sid>
1884 * In the forms "system.nt_sec_desc.*" and
1885 * "system.nt_sec_desc.*+", the asterisk and plus signs are
1886 * literal, i.e. the string is provided exactly as shown, and
1887 * the value parameter should contain a complete security
1888 * descriptor with name:value pairs separated by tabs,
1889 * commas, or newlines (not spaces!).
1891 * The plus sign ('+') indicates that SIDs should be mapped
1892 * to names. Without the plus sign, SIDs are not mapped;
1893 * rather they are simply converted to a string format.
1895 * @param value The value to be assigned to the specified attribute name.
1896 * This buffer should contain only the attribute value if the
1897 * name was of the "system.nt_sec_desc.<attribute_name>"
1898 * form. If the name was of the "system.nt_sec_desc.*" form
1899 * then a complete security descriptor, with name:value pairs
1900 * separated by tabs, commas, or newlines (not spaces!),
1901 * should be provided in this value buffer. A complete
1902 * security descriptor will contain one or more entries
1903 * selected from the following:
1905 * REVISION:<revision number>
1906 * OWNER:<sid or name>
1907 * GROUP:<sid or name>
1908 * ACL:<sid or name>:<type>/<flags>/<mask>
1910 * The revision of the ACL specifies the internal Windows NT
1911 * ACL revision for the security descriptor. If not specified
1912 * it defaults to 1. Using values other than 1 may cause
1913 * strange behaviour.
1915 * The owner and group specify the owner and group sids for
1916 * the object. If the attribute name (either '*+' with a
1917 * complete security descriptor, or individual 'owner+' or
1918 * 'group+' attribute names) ended with a plus sign, the
1919 * specified name is resolved to a SID value, using the
1920 * server on which the file or directory resides. Otherwise,
1921 * the value should be provided in SID-printable format as
1922 * S-1-x-y-z, and is used directly. The <sid or name>
1923 * associated with the ACL: attribute should be provided
1924 * similarly.
1926 * @param size The number of the bytes of data in the value buffer
1928 * @param flags A bit-wise OR of zero or more of the following:
1929 * SMBC_XATTR_FLAG_CREATE -
1930 * fail if the named attribute already exists
1931 * SMBC_XATTR_FLAG_REPLACE -
1932 * fail if the attribute does not already exist
1934 * If neither flag is specified, the specified attributes
1935 * will be added or replace existing attributes of the same
1936 * name, as necessary.
1938 * @return 0 on success, < 0 on error with errno set:
1939 * - EINVAL The client library is not properly initialized
1940 * or one of the parameters is not of a correct
1941 * form
1942 * - ENOMEM No memory was available for internal needs
1943 * - EEXIST If the attribute already exists and the flag
1944 * SMBC_XATTR_FLAG_CREAT was specified
1945 * - ENOATTR If the attribute does not exist and the flag
1946 * SMBC_XATTR_FLAG_REPLACE was specified
1947 * - EPERM Permission was denied.
1948 * - ENOTSUP The referenced file system does not support
1949 * extended attributes
1951 * @note Attribute names are compared in a case-insensitive
1952 * fashion. All of the following are equivalent, although
1953 * the all-lower-case name is the preferred format:
1954 * system.nt_sec_desc.owner
1955 * SYSTEM.NT_SEC_DESC.OWNER
1956 * sYsTeM.nt_sEc_desc.owNER
1959 int smbc_lsetxattr(const char *url,
1960 const char *name,
1961 const void *value,
1962 size_t size,
1963 int flags);
1966 /**@ingroup attribute
1967 * Set extended attributes for a file. This is used for modifying a file's
1968 * security descriptor (i.e. owner, group, and access control list)
1970 * @param fd A file descriptor associated with an open file (as
1971 * previously returned by smbc_open(), to get extended
1972 * attributes for.
1974 * @param name The name of an attribute to be changed. Names are of
1975 * one of the following forms:
1977 * system.nt_sec_desc.<attribute name>
1978 * system.nt_sec_desc.*
1979 * system.nt_sec_desc.*+
1981 * where <attribute name> is one of:
1983 * revision
1984 * owner
1985 * owner+
1986 * group
1987 * group+
1988 * acl:<name or sid>
1989 * acl+:<name or sid>
1991 * In the forms "system.nt_sec_desc.*" and
1992 * "system.nt_sec_desc.*+", the asterisk and plus signs are
1993 * literal, i.e. the string is provided exactly as shown, and
1994 * the value parameter should contain a complete security
1995 * descriptor with name:value pairs separated by tabs,
1996 * commas, or newlines (not spaces!).
1998 * The plus sign ('+') indicates that SIDs should be mapped
1999 * to names. Without the plus sign, SIDs are not mapped;
2000 * rather they are simply converted to a string format.
2002 * @param value The value to be assigned to the specified attribute name.
2003 * This buffer should contain only the attribute value if the
2004 * name was of the "system.nt_sec_desc.<attribute_name>"
2005 * form. If the name was of the "system.nt_sec_desc.*" form
2006 * then a complete security descriptor, with name:value pairs
2007 * separated by tabs, commas, or newlines (not spaces!),
2008 * should be provided in this value buffer. A complete
2009 * security descriptor will contain one or more entries
2010 * selected from the following:
2012 * REVISION:<revision number>
2013 * OWNER:<sid or name>
2014 * GROUP:<sid or name>
2015 * ACL:<sid or name>:<type>/<flags>/<mask>
2017 * The revision of the ACL specifies the internal Windows NT
2018 * ACL revision for the security descriptor. If not specified
2019 * it defaults to 1. Using values other than 1 may cause
2020 * strange behaviour.
2022 * The owner and group specify the owner and group sids for
2023 * the object. If the attribute name (either '*+' with a
2024 * complete security descriptor, or individual 'owner+' or
2025 * 'group+' attribute names) ended with a plus sign, the
2026 * specified name is resolved to a SID value, using the
2027 * server on which the file or directory resides. Otherwise,
2028 * the value should be provided in SID-printable format as
2029 * S-1-x-y-z, and is used directly. The <sid or name>
2030 * associated with the ACL: attribute should be provided
2031 * similarly.
2033 * @param size The number of the bytes of data in the value buffer
2035 * @param flags A bit-wise OR of zero or more of the following:
2036 * SMBC_XATTR_FLAG_CREATE -
2037 * fail if the named attribute already exists
2038 * SMBC_XATTR_FLAG_REPLACE -
2039 * fail if the attribute does not already exist
2041 * If neither flag is specified, the specified attributes
2042 * will be added or replace existing attributes of the same
2043 * name, as necessary.
2045 * @return 0 on success, < 0 on error with errno set:
2046 * - EINVAL The client library is not properly initialized
2047 * or one of the parameters is not of a correct
2048 * form
2049 * - ENOMEM No memory was available for internal needs
2050 * - EEXIST If the attribute already exists and the flag
2051 * SMBC_XATTR_FLAG_CREAT was specified
2052 * - ENOATTR If the attribute does not exist and the flag
2053 * SMBC_XATTR_FLAG_REPLACE was specified
2054 * - EPERM Permission was denied.
2055 * - ENOTSUP The referenced file system does not support
2056 * extended attributes
2058 * @note Attribute names are compared in a case-insensitive
2059 * fashion. All of the following are equivalent, although
2060 * the all-lower-case name is the preferred format:
2061 * system.nt_sec_desc.owner
2062 * SYSTEM.NT_SEC_DESC.OWNER
2063 * sYsTeM.nt_sEc_desc.owNER
2066 int smbc_fsetxattr(int fd,
2067 const char *name,
2068 const void *value,
2069 size_t size,
2070 int flags);
2073 /**@ingroup attribute
2074 * Get extended attributes for a file.
2076 * @param url The smb url of the file or directory to get extended
2077 * attributes for.
2079 * @param name The name of an attribute to be retrieved. Names are of
2080 * one of the following forms:
2082 * system.nt_sec_desc.<attribute name>
2083 * system.nt_sec_desc.*
2084 * system.nt_sec_desc.*+
2086 * where <attribute name> is one of:
2088 * revision
2089 * owner
2090 * owner+
2091 * group
2092 * group+
2093 * acl:<name or sid>
2094 * acl+:<name or sid>
2096 * In the forms "system.nt_sec_desc.*" and
2097 * "system.nt_sec_desc.*+", the asterisk and plus signs are
2098 * literal, i.e. the string is provided exactly as shown, and
2099 * the value parameter will return a complete security
2100 * descriptor with name:value pairs separated by tabs,
2101 * commas, or newlines (not spaces!).
2103 * The plus sign ('+') indicates that SIDs should be mapped
2104 * to names. Without the plus sign, SIDs are not mapped;
2105 * rather they are simply converted to a string format.
2107 * @param value A pointer to a buffer in which the value of the specified
2108 * attribute will be placed (unless size is zero).
2110 * @param size The size of the buffer pointed to by value. This parameter
2111 * may also be zero, in which case the size of the buffer
2112 * required to hold the attribute value will be returned,
2113 * but nothing will be placed into the value buffer.
2115 * @return 0 on success, < 0 on error with errno set:
2116 * - EINVAL The client library is not properly initialized
2117 * or one of the parameters is not of a correct
2118 * form
2119 * - ENOMEM No memory was available for internal needs
2120 * - EEXIST If the attribute already exists and the flag
2121 * SMBC_XATTR_FLAG_CREAT was specified
2122 * - ENOATTR If the attribute does not exist and the flag
2123 * SMBC_XATTR_FLAG_REPLACE was specified
2124 * - EPERM Permission was denied.
2125 * - ENOTSUP The referenced file system does not support
2126 * extended attributes
2129 int smbc_getxattr(const char *url,
2130 const char *name,
2131 const void *value,
2132 size_t size);
2135 /**@ingroup attribute
2136 * Get extended attributes for a file. The POSIX function which this maps to
2137 * would act on a symbolic link rather than acting on what the symbolic link
2138 * points to, but with no symbolic links in SMB file systems, this function
2139 * is functionally identical to smbc_getxattr().
2141 * @param url The smb url of the file or directory to get extended
2142 * attributes for.
2144 * @param name The name of an attribute to be retrieved. Names are of
2145 * one of the following forms:
2147 * system.nt_sec_desc.<attribute name>
2148 * system.nt_sec_desc.*
2149 * system.nt_sec_desc.*+
2151 * where <attribute name> is one of:
2153 * revision
2154 * owner
2155 * owner+
2156 * group
2157 * group+
2158 * acl:<name or sid>
2159 * acl+:<name or sid>
2161 * In the forms "system.nt_sec_desc.*" and
2162 * "system.nt_sec_desc.*+", the asterisk and plus signs are
2163 * literal, i.e. the string is provided exactly as shown, and
2164 * the value parameter will return a complete security
2165 * descriptor with name:value pairs separated by tabs,
2166 * commas, or newlines (not spaces!).
2168 * The plus sign ('+') indicates that SIDs should be mapped
2169 * to names. Without the plus sign, SIDs are not mapped;
2170 * rather they are simply converted to a string format.
2172 * @param value A pointer to a buffer in which the value of the specified
2173 * attribute will be placed (unless size is zero).
2175 * @param size The size of the buffer pointed to by value. This parameter
2176 * may also be zero, in which case the size of the buffer
2177 * required to hold the attribute value will be returned,
2178 * but nothing will be placed into the value buffer.
2180 * @return 0 on success, < 0 on error with errno set:
2181 * - EINVAL The client library is not properly initialized
2182 * or one of the parameters is not of a correct
2183 * form
2184 * - ENOMEM No memory was available for internal needs
2185 * - EEXIST If the attribute already exists and the flag
2186 * SMBC_XATTR_FLAG_CREAT was specified
2187 * - ENOATTR If the attribute does not exist and the flag
2188 * SMBC_XATTR_FLAG_REPLACE was specified
2189 * - EPERM Permission was denied.
2190 * - ENOTSUP The referenced file system does not support
2191 * extended attributes
2194 int smbc_lgetxattr(const char *url,
2195 const char *name,
2196 const void *value,
2197 size_t size);
2200 /**@ingroup attribute
2201 * Get extended attributes for a file.
2203 * @param fd A file descriptor associated with an open file (as
2204 * previously returned by smbc_open(), to get extended
2205 * attributes for.
2207 * @param name The name of an attribute to be retrieved. Names are of
2208 * one of the following forms:
2210 * system.nt_sec_desc.<attribute name>
2211 * system.nt_sec_desc.*
2212 * system.nt_sec_desc.*+
2214 * where <attribute name> is one of:
2216 * revision
2217 * owner
2218 * owner+
2219 * group
2220 * group+
2221 * acl:<name or sid>
2222 * acl+:<name or sid>
2224 * In the forms "system.nt_sec_desc.*" and
2225 * "system.nt_sec_desc.*+", the asterisk and plus signs are
2226 * literal, i.e. the string is provided exactly as shown, and
2227 * the value parameter will return a complete security
2228 * descriptor with name:value pairs separated by tabs,
2229 * commas, or newlines (not spaces!).
2231 * The plus sign ('+') indicates that SIDs should be mapped
2232 * to names. Without the plus sign, SIDs are not mapped;
2233 * rather they are simply converted to a string format.
2235 * @param value A pointer to a buffer in which the value of the specified
2236 * attribute will be placed (unless size is zero).
2238 * @param size The size of the buffer pointed to by value. This parameter
2239 * may also be zero, in which case the size of the buffer
2240 * required to hold the attribute value will be returned,
2241 * but nothing will be placed into the value buffer.
2243 * @return 0 on success, < 0 on error with errno set:
2244 * - EINVAL The client library is not properly initialized
2245 * or one of the parameters is not of a correct
2246 * form
2247 * - ENOMEM No memory was available for internal needs
2248 * - EEXIST If the attribute already exists and the flag
2249 * SMBC_XATTR_FLAG_CREAT was specified
2250 * - ENOATTR If the attribute does not exist and the flag
2251 * SMBC_XATTR_FLAG_REPLACE was specified
2252 * - EPERM Permission was denied.
2253 * - ENOTSUP The referenced file system does not support
2254 * extended attributes
2257 int smbc_fgetxattr(int fd,
2258 const char *name,
2259 const void *value,
2260 size_t size);
2263 /**@ingroup attribute
2264 * Remove extended attributes for a file. This is used for modifying a file's
2265 * security descriptor (i.e. owner, group, and access control list)
2267 * @param url The smb url of the file or directory to remove the extended
2268 * attributes for.
2270 * @param name The name of an attribute to be removed. Names are of
2271 * one of the following forms:
2273 * system.nt_sec_desc.<attribute name>
2274 * system.nt_sec_desc.*
2275 * system.nt_sec_desc.*+
2277 * where <attribute name> is one of:
2279 * revision
2280 * owner
2281 * owner+
2282 * group
2283 * group+
2284 * acl:<name or sid>
2285 * acl+:<name or sid>
2287 * In the forms "system.nt_sec_desc.*" and
2288 * "system.nt_sec_desc.*+", the asterisk and plus signs are
2289 * literal, i.e. the string is provided exactly as shown, and
2290 * the value parameter will return a complete security
2291 * descriptor with name:value pairs separated by tabs,
2292 * commas, or newlines (not spaces!).
2294 * The plus sign ('+') indicates that SIDs should be mapped
2295 * to names. Without the plus sign, SIDs are not mapped;
2296 * rather they are simply converted to a string format.
2298 * @return 0 on success, < 0 on error with errno set:
2299 * - EINVAL The client library is not properly initialized
2300 * - ENOMEM No memory was available for internal needs
2301 * - EPERM Permission was denied.
2302 * - ENOTSUP The referenced file system does not support
2303 * extended attributes
2306 int smbc_removexattr(const char *url,
2307 const char *name);
2310 /**@ingroup attribute
2311 * Remove extended attributes for a file. This is used for modifying a file's
2312 * security descriptor (i.e. owner, group, and access control list) The POSIX
2313 * function which this maps to would act on a symbolic link rather than acting
2314 * on what the symbolic link points to, but with no symbolic links in SMB file
2315 * systems, this function is functionally identical to smbc_removexattr().
2317 * @param url The smb url of the file or directory to remove the extended
2318 * attributes for.
2320 * @param name The name of an attribute to be removed. 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:
2329 * revision
2330 * owner
2331 * owner+
2332 * group
2333 * group+
2334 * acl:<name or sid>
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 * @return 0 on success, < 0 on error with errno set:
2349 * - EINVAL The client library is not properly initialized
2350 * - ENOMEM No memory was available for internal needs
2351 * - EPERM Permission was denied.
2352 * - ENOTSUP The referenced file system does not support
2353 * extended attributes
2356 int smbc_lremovexattr(const char *url,
2357 const char *name);
2360 /**@ingroup attribute
2361 * Remove extended attributes for a file. This is used for modifying a file's
2362 * security descriptor (i.e. owner, group, and access control list)
2364 * @param fd A file descriptor associated with an open file (as
2365 * previously returned by smbc_open(), to get extended
2366 * attributes for.
2368 * @param name The name of an attribute to be removed. Names are of
2369 * one of the following forms:
2371 * system.nt_sec_desc.<attribute name>
2372 * system.nt_sec_desc.*
2373 * system.nt_sec_desc.*+
2375 * where <attribute name> is one of:
2377 * revision
2378 * owner
2379 * owner+
2380 * group
2381 * group+
2382 * acl:<name or sid>
2383 * acl+:<name or sid>
2385 * In the forms "system.nt_sec_desc.*" and
2386 * "system.nt_sec_desc.*+", the asterisk and plus signs are
2387 * literal, i.e. the string is provided exactly as shown, and
2388 * the value parameter will return a complete security
2389 * descriptor with name:value pairs separated by tabs,
2390 * commas, or newlines (not spaces!).
2392 * The plus sign ('+') indicates that SIDs should be mapped
2393 * to names. Without the plus sign, SIDs are not mapped;
2394 * rather they are simply converted to a string format.
2396 * @return 0 on success, < 0 on error with errno set:
2397 * - EINVAL The client library is not properly initialized
2398 * - ENOMEM No memory was available for internal needs
2399 * - EPERM Permission was denied.
2400 * - ENOTSUP The referenced file system does not support
2401 * extended attributes
2404 int smbc_fremovexattr(int fd,
2405 const char *name);
2408 /**@ingroup attribute
2409 * List the supported extended attribute names associated with a file
2411 * @param url The smb url of the file or directory to list the extended
2412 * attributes for.
2414 * @param list A pointer to a buffer in which the list of attributes for
2415 * the specified file or directory will be placed (unless
2416 * size is zero).
2418 * @param size The size of the buffer pointed to by list. This parameter
2419 * may also be zero, in which case the size of the buffer
2420 * required to hold all of the attribute names will be
2421 * returned, but nothing will be placed into the list buffer.
2423 * @return 0 on success, < 0 on error with errno set:
2424 * - EINVAL The client library is not properly initialized
2425 * - ENOMEM No memory was available for internal needs
2426 * - EPERM Permission was denied.
2427 * - ENOTSUP The referenced file system does not support
2428 * extended attributes
2430 * @note This function always returns all attribute names supported
2431 * by NT file systems, regardless of whether the referenced
2432 * file system supports extended attributes (e.g. a Windows
2433 * 2000 machine supports extended attributes if NTFS is used,
2434 * but not if FAT is used, and Windows 98 doesn't support
2435 * extended attributes at all. Whether this is a feature or
2436 * a bug is yet to be decided.
2438 int smbc_listxattr(const char *url,
2439 char *list,
2440 size_t size);
2442 /**@ingroup attribute
2443 * List the supported extended attribute names associated with a file The
2444 * POSIX function which this maps to would act on a symbolic link rather than
2445 * acting on what the symbolic link points to, but with no symbolic links in
2446 * SMB file systems, this function is functionally identical to
2447 * smbc_listxattr().
2449 * @param url The smb url of the file or directory to list the extended
2450 * attributes for.
2452 * @param list A pointer to a buffer in which the list of attributes for
2453 * the specified file or directory will be placed (unless
2454 * size is zero).
2456 * @param size The size of the buffer pointed to by list. This parameter
2457 * may also be zero, in which case the size of the buffer
2458 * required to hold all of the attribute names will be
2459 * returned, but nothing will be placed into the list buffer.
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
2468 * @note This function always returns all attribute names supported
2469 * by NT file systems, regardless of wether the referenced
2470 * file system supports extended attributes (e.g. a Windows
2471 * 2000 machine supports extended attributes if NTFS is used,
2472 * but not if FAT is used, and Windows 98 doesn't support
2473 * extended attributes at all. Whether this is a feature or
2474 * a bug is yet to be decided.
2476 int smbc_llistxattr(const char *url,
2477 char *list,
2478 size_t size);
2480 /**@ingroup attribute
2481 * List the supported extended attribute names associated with a file
2483 * @param fd A file descriptor associated with an open file (as
2484 * previously returned by smbc_open(), to get extended
2485 * attributes for.
2487 * @param list A pointer to a buffer in which the list of attributes for
2488 * the specified file or directory will be placed (unless
2489 * size is zero).
2491 * @param size The size of the buffer pointed to by list. This parameter
2492 * may also be zero, in which case the size of the buffer
2493 * required to hold all of the attribute names will be
2494 * returned, but nothing will be placed into the list buffer.
2496 * @return 0 on success, < 0 on error with errno set:
2497 * - EINVAL The client library is not properly initialized
2498 * - ENOMEM No memory was available for internal needs
2499 * - EPERM Permission was denied.
2500 * - ENOTSUP The referenced file system does not support
2501 * extended attributes
2503 * @note This function always returns all attribute names supported
2504 * by NT file systems, regardless of wether the referenced
2505 * file system supports extended attributes (e.g. a Windows
2506 * 2000 machine supports extended attributes if NTFS is used,
2507 * but not if FAT is used, and Windows 98 doesn't support
2508 * extended attributes at all. Whether this is a feature or
2509 * a bug is yet to be decided.
2511 int smbc_flistxattr(int fd,
2512 char *list,
2513 size_t size);
2515 /**@ingroup print
2516 * Print a file given the name in fname. It would be a URL ...
2518 * @param fname The URL of a file on a remote SMB server that the
2519 * caller wants printed
2521 * @param printq The URL of the print share to print the file to.
2523 * @return 0 on success, < 0 on error with errno set:
2525 * - EINVAL fname or printq was NULL or smbc_init not
2526 * not called.
2527 * and errors returned by smbc_open
2530 int smbc_print_file(const char *fname, const char *printq);
2532 /**@ingroup print
2533 * Open a print file that can be written to by other calls. This simply
2534 * does an smbc_open call after checking if there is a file name on the
2535 * URI. If not, a temporary name is added ...
2537 * @param fname The URL of the print share to print to?
2539 * @returns A file handle for the print file if successful.
2540 * Returns -1 if an error ocurred and errno has the values
2541 * - EINVAL fname was NULL or smbc_init not called.
2542 * - all errors returned by smbc_open
2545 int smbc_open_print_job(const char *fname);
2547 /**@ingroup print
2548 * List the print jobs on a print share, for the moment, pass a callback
2550 * @param purl The url of the print share to list the jobs of
2552 * @param fn Callback function the receives printjob info
2554 * @return 0 on success, < 0 on error with errno set:
2555 * - EINVAL fname was NULL or smbc_init not called
2556 * - EACCES ???
2558 int smbc_list_print_jobs(const char *purl, smbc_list_print_job_fn fn);
2560 /**@ingroup print
2561 * Delete a print job
2563 * @param purl Url of the print share
2565 * @param id The id of the job to delete
2567 * @return 0 on success, < 0 on error with errno set:
2568 * - EINVAL fname was NULL or smbc_init not called
2570 * @todo what errno values are possible here?
2572 int smbc_unlink_print_job(const char *purl, int id);
2574 /**@ingroup callback
2575 * Remove a server from the cached server list it's unused.
2577 * @param context pointer to smb context
2579 * @param srv pointer to server to remove
2581 * @return On success, 0 is returned. 1 is returned if the server could not
2582 * be removed. Also useable outside libsmbclient.
2584 int smbc_remove_unused_server(SMBCCTX * context, SMBCSRV * srv);
2586 #ifdef __cplusplus
2588 #endif
2590 /**@ingroup directory
2591 * Convert strings of %xx to their single character equivalent.
2593 * @param dest A pointer to a buffer in which the resulting decoded
2594 * string should be placed. This may be a pointer to the
2595 * same buffer as src_segment.
2597 * @param src A pointer to the buffer containing the URL to be decoded.
2598 * Any %xx sequences herein are converted to their single
2599 * character equivalent. Each 'x' must be a valid hexadecimal
2600 * digit, or that % sequence is left undecoded.
2602 * @param max_dest_len
2603 * The size of the buffer pointed to by dest_segment.
2605 * @return The number of % sequences which could not be converted
2606 * due to lack of two following hexadecimal digits.
2608 #ifdef __cplusplus
2609 extern "C" {
2610 #endif
2612 smbc_urldecode(char *dest, char * src, size_t max_dest_len);
2613 #ifdef __cplusplus
2615 #endif
2619 * Convert any characters not specifically allowed in a URL into their %xx
2620 * equivalent.
2622 * @param dest A pointer to a buffer in which the resulting encoded
2623 * string should be placed. Unlike smbc_urldecode(), this
2624 * must be a buffer unique from src.
2626 * @param src A pointer to the buffer containing the string to be encoded.
2627 * Any character not specifically allowed in a URL is converted
2628 * into its hexadecimal value and encoded as %xx.
2630 * @param max_dest_len
2631 * The size of the buffer pointed to by dest_segment.
2633 * @returns The remaining buffer length.
2635 #ifdef __cplusplus
2636 extern "C" {
2637 #endif
2639 smbc_urlencode(char * dest, char * src, int max_dest_len);
2640 #ifdef __cplusplus
2642 #endif
2645 /**@ingroup directory
2646 * Return the version of the linked Samba code, and thus the version of the
2647 * libsmbclient code.
2649 * @return The version string.
2651 #ifdef __cplusplus
2652 extern "C" {
2653 #endif
2654 const char *
2655 smbc_version(void);
2656 #ifdef __cplusplus
2658 #endif
2660 /**@ingroup misc
2661 * Set the users credentials globally so they can be used for DFS
2662 * referrals. Probably best to use this function in the smbc_get_auth_data_fn
2663 * callback.
2665 * @param workgroup Workgroup of the user.
2667 * @param user Username of user.
2669 * @param password Password of user.
2671 * @param use_kerberos Whether to use Kerberos
2673 * @param signing_state One of these strings (all equivalents on same line):
2674 * "off", "no", "false"
2675 * "on", "yes", "true", "auto"
2676 * "force", "required", "forced"
2679 void
2680 smbc_set_credentials(const char *workgroup,
2681 const char *user,
2682 const char *password,
2683 smbc_bool use_kerberos,
2684 const char *signing_state);
2687 * Wrapper around smbc_set_credentials.
2688 * Used to set correct credentials that will
2689 * be used to connect to DFS target share
2690 * in libsmbclient
2693 void
2694 smbc_set_credentials_with_fallback(SMBCCTX *ctx,
2695 const char *workgroup,
2696 const char *user,
2697 const char *password);
2701 * @ingroup threads
2703 * Initialize for threads using the Posix Threads (pthread)
2704 * implementation. This is a built-in implementation, avoiding the need to
2705 * implement the component functions of the thread interface. If this function
2706 * is used, it is not necessary to call smbc_thread_impl().
2708 * @return {void}
2710 void
2711 smbc_thread_posix(void);
2714 * @ingroup threads
2716 * Initialize for an arbitrary thread implementation. The caller should
2717 * provide, as parameters, pointers to functions to implement the requisite
2718 * low-level thread functionality. A function must be provided for each
2719 * parameter; none may be null.
2721 * If the thread implementation is POSIX Threads (pthreads), then the much
2722 * simpler smbc_thread_pthread() function may be used instead of this one.
2724 * @param create_mutex
2725 * Create a mutex. This function should expect three parameters: lockname,
2726 * pplock, and location. It should create a unique mutex for each unique
2727 * lockname it is provided, and return the mutex identifier in *pplock. The
2728 * location parameter can be used for debugging, as it contains the
2729 * compiler-provided __location__ of the call.
2731 * @param destroy_mutex
2732 * Destroy a mutex. This function should expect two parameters: plock and
2733 * location. It should destroy the mutex associated with the identifier
2734 * plock. The location parameter can be used for debugging, as it contains
2735 * the compiler-provided __location__ of the call.
2737 * @param lock_mutex
2738 * Lock a mutex. This function should expect three parameters: plock,
2739 * lock_type, and location. The mutex aassociated with identifier plock
2740 * should be locked if lock_type is 1, and unlocked if lock_type is 2. The
2741 * location parameter can be used for debugging, as it contains the
2742 * compiler-provided __location__ of the call.
2744 * @param create_tls
2745 * Create thread local storage. This function should expect three
2746 * parameters: keyname, ppkey, and location. It should allocate an
2747 * implementation-specific amount of memory and assign the pointer to that
2748 * allocated memory to *ppkey. The location parameter can be used for
2749 * debugging, as it contains the compiler-provided __location__ of the
2750 * call. This function should return 0 upon success, non-zero upon failure.
2752 * @param destroy_tls
2753 * Destroy thread local storage. This function should expect two parameters:
2754 * ppkey and location. The ppkey parameter points to a variable containing a
2755 * thread local storage key previously provided by the create_tls
2756 * function. The location parameter can be used for debugging, as it
2757 * contains the compiler-provided __location__ of the call.
2759 * @param set_tls
2760 * Set a thread local storage variable's value. This function should expect
2761 * three parameters: pkey, pval, and location. The pkey parameter is a
2762 * thread local storage key previously provided by the create_tls
2763 * function. The (void *) pval parameter contains the value to be placed in
2764 * the thread local storage variable identified by pkey. The location
2765 * parameter can be used for debugging, as it contains the compiler-provided
2766 * __location__ of the call. This function should return 0 upon success;
2767 * non-zero otherwise.
2769 * @param get_tls
2770 * Retrieve a thread local storage variable's value. This function should
2771 * expect two parameters: pkey and location. The pkey parameter is a thread
2772 * local storage key previously provided by the create_tls function, and
2773 * which has previously been used in a call to the set_tls function to
2774 * initialize a thread local storage variable. The location parameter can be
2775 * used for debugging, as it contains the compiler-provided __location__ of
2776 * the call. This function should return the (void *) value stored in the
2777 * variable identified by pkey.
2779 * @return {void}
2781 void
2782 smbc_thread_impl(
2783 /* Mutex functions. */
2784 int (*create_mutex)(const char *lockname,
2785 void **pplock,
2786 const char *location),
2787 void (*destroy_mutex)(void *plock,
2788 const char *location),
2789 int (*lock_mutex)(void *plock,
2790 int lock_type,
2791 const char *location),
2793 /* Thread local storage. */
2794 int (*create_tls)(const char *keyname,
2795 void **ppkey,
2796 const char *location),
2797 void (*destroy_tls)(void **ppkey,
2798 const char *location),
2799 int (*set_tls)(void *pkey,
2800 const void *pval,
2801 const char *location),
2802 void *(*get_tls)(void *pkey,
2803 const char *location)
2809 * @ingroup structure
2810 * Structure that contains a client context information
2811 * This structure is known as SMBCCTX
2813 * DO NOT DIRECTLY MANIPULATE THE CONTEXT STRUCTURE! The data in the context
2814 * structure should all be considered private to the library. It remains here
2815 * only for backward compatibility.
2817 * See the comments herein for use of the setter and getter functions which
2818 * should now be used for manipulating these values. New features, functions,
2819 * etc., are not added here but rather in _internal where they are not
2820 * directly visible to applications. This makes it much easier to maintain
2821 * ABI compatibility.
2823 struct _SMBCCTX
2826 * debug level
2828 * DEPRECATED:
2829 * Use smbc_getDebug() and smbc_setDebug()
2831 int debug DEPRECATED_SMBC_INTERFACE;
2834 * netbios name used for making connections
2836 * DEPRECATED:
2837 * Use smbc_getNetbiosName() and smbc_setNetbiosName()
2839 char * netbios_name DEPRECATED_SMBC_INTERFACE;
2842 * workgroup name used for making connections
2844 * DEPRECATED:
2845 * Use smbc_getWorkgroup() and smbc_setWorkgroup()
2847 char * workgroup DEPRECATED_SMBC_INTERFACE;
2850 * username used for making connections
2852 * DEPRECATED:
2853 * Use smbc_getUser() and smbc_setUser()
2855 char * user DEPRECATED_SMBC_INTERFACE;
2858 * timeout used for waiting on connections / response data (in
2859 * milliseconds)
2861 * DEPRECATED:
2862 * Use smbc_getTimeout() and smbc_setTimeout()
2864 int timeout DEPRECATED_SMBC_INTERFACE;
2867 * callable functions for files:
2868 * For usage and return values see the SMBC_* functions
2870 * DEPRECATED:
2872 * Use smbc_getFunction*() and smbc_setFunction*(), e.g.
2873 * smbc_getFunctionOpen(), smbc_setFunctionUnlink(), etc.
2875 smbc_open_fn open DEPRECATED_SMBC_INTERFACE;
2876 smbc_creat_fn creat DEPRECATED_SMBC_INTERFACE;
2877 smbc_read_fn read DEPRECATED_SMBC_INTERFACE;
2878 smbc_write_fn write DEPRECATED_SMBC_INTERFACE;
2879 smbc_unlink_fn unlink DEPRECATED_SMBC_INTERFACE;
2880 smbc_rename_fn rename DEPRECATED_SMBC_INTERFACE;
2881 smbc_lseek_fn lseek DEPRECATED_SMBC_INTERFACE;
2882 smbc_stat_fn stat DEPRECATED_SMBC_INTERFACE;
2883 smbc_fstat_fn fstat DEPRECATED_SMBC_INTERFACE;
2884 #if 0 /* internal */
2885 smbc_ftruncate_fn ftruncate_fn;
2886 #endif
2887 smbc_close_fn close_fn DEPRECATED_SMBC_INTERFACE;
2888 smbc_opendir_fn opendir DEPRECATED_SMBC_INTERFACE;
2889 smbc_closedir_fn closedir DEPRECATED_SMBC_INTERFACE;
2890 smbc_readdir_fn readdir DEPRECATED_SMBC_INTERFACE;
2891 smbc_getdents_fn getdents DEPRECATED_SMBC_INTERFACE;
2892 smbc_mkdir_fn mkdir DEPRECATED_SMBC_INTERFACE;
2893 smbc_rmdir_fn rmdir DEPRECATED_SMBC_INTERFACE;
2894 smbc_telldir_fn telldir DEPRECATED_SMBC_INTERFACE;
2895 smbc_lseekdir_fn lseekdir DEPRECATED_SMBC_INTERFACE;
2896 smbc_fstatdir_fn fstatdir DEPRECATED_SMBC_INTERFACE;
2897 smbc_chmod_fn chmod DEPRECATED_SMBC_INTERFACE;
2898 smbc_utimes_fn utimes DEPRECATED_SMBC_INTERFACE;
2899 smbc_setxattr_fn setxattr DEPRECATED_SMBC_INTERFACE;
2900 smbc_getxattr_fn getxattr DEPRECATED_SMBC_INTERFACE;
2901 smbc_removexattr_fn removexattr DEPRECATED_SMBC_INTERFACE;
2902 smbc_listxattr_fn listxattr DEPRECATED_SMBC_INTERFACE;
2904 /* Printing-related functions */
2905 smbc_print_file_fn print_file DEPRECATED_SMBC_INTERFACE;
2906 smbc_open_print_job_fn open_print_job DEPRECATED_SMBC_INTERFACE;
2907 smbc_list_print_jobs_fn list_print_jobs DEPRECATED_SMBC_INTERFACE;
2908 smbc_unlink_print_job_fn unlink_print_job DEPRECATED_SMBC_INTERFACE;
2911 ** Callbacks
2913 * DEPRECATED:
2915 * See the comment above each field, for the getter and setter
2916 * functions that should now be used.
2918 struct _smbc_callbacks
2921 * authentication function callback: called upon auth requests
2923 * DEPRECATED:
2924 * Use smbc_getFunctionAuthData(), smbc_setFunctionAuthData()
2926 smbc_get_auth_data_fn auth_fn DEPRECATED_SMBC_INTERFACE;
2929 * check if a server is still good
2931 * DEPRECATED:
2932 * Use smbc_getFunctionCheckServer(),
2933 * smbc_setFunctionCheckServer()
2935 smbc_check_server_fn check_server_fn DEPRECATED_SMBC_INTERFACE;
2938 * remove a server if unused
2940 * DEPRECATED:
2941 * Use smbc_getFunctionRemoveUnusedServer(),
2942 * smbc_setFunctionCheckServer()
2944 smbc_remove_unused_server_fn remove_unused_server_fn DEPRECATED_SMBC_INTERFACE;
2946 /** Cache subsystem
2948 * For an example cache system see
2949 * samba/source/libsmb/libsmb_cache.c
2951 * Cache subsystem * functions follow.
2955 * server cache addition
2957 * DEPRECATED:
2958 * Use smbc_getFunctionAddCachedServer(),
2959 * smbc_setFunctionAddCachedServer()
2961 smbc_add_cached_srv_fn add_cached_srv_fn DEPRECATED_SMBC_INTERFACE;
2964 * server cache lookup
2966 * DEPRECATED:
2967 * Use smbc_getFunctionGetCachedServer(),
2968 * smbc_setFunctionGetCachedServer()
2970 smbc_get_cached_srv_fn get_cached_srv_fn DEPRECATED_SMBC_INTERFACE;
2973 * server cache removal
2975 * DEPRECATED:
2976 * Use smbc_getFunctionRemoveCachedServer(),
2977 * smbc_setFunctionRemoveCachedServer()
2979 smbc_remove_cached_srv_fn remove_cached_srv_fn DEPRECATED_SMBC_INTERFACE;
2982 * server cache purging, try to remove all cached servers
2983 * (disconnect)
2985 * DEPRECATED:
2986 * Use smbc_getFunctionPurgeCachedServers(),
2987 * smbc_setFunctionPurgeCachedServers()
2989 smbc_purge_cached_fn purge_cached_fn DEPRECATED_SMBC_INTERFACE;
2990 } callbacks;
2993 * Space where the private data of the server cache used to be
2995 * DEPRECATED:
2996 * Use smbc_getServerCacheData(), smbc_setServerCacheData()
2998 void * reserved DEPRECATED_SMBC_INTERFACE;
3001 * Very old configuration options.
3003 * DEPRECATED:
3004 * Use one of the following functions instead:
3005 * smbc_setOptionUseKerberos()
3006 * smbc_getOptionUseKerberos()
3007 * smbc_setOptionFallbackAfterKerberos()
3008 * smbc_getOptionFallbackAfterKerberos()
3009 * smbc_setOptionNoAutoAnonymousLogin()
3010 * smbc_getOptionNoAutoAnonymousLogin()
3012 int flags DEPRECATED_SMBC_INTERFACE;
3015 * user options selections that apply to this session
3017 * NEW OPTIONS ARE NOT ADDED HERE!
3019 * DEPRECATED:
3020 * To set and retrieve options, use the smbc_setOption*() and
3021 * smbc_getOption*() functions.
3023 struct _smbc_options {
3024 int browse_max_lmb_count DEPRECATED_SMBC_INTERFACE;
3025 int urlencode_readdir_entries DEPRECATED_SMBC_INTERFACE;
3026 int one_share_per_server DEPRECATED_SMBC_INTERFACE;
3027 } options DEPRECATED_SMBC_INTERFACE;
3029 /** INTERNAL DATA
3030 * do _NOT_ touch this from your program !
3032 struct SMBC_internal_data * internal;
3036 #endif /* SMBCLIENT_H_INCLUDED */