s3 libsmbclient: Fix fstatvfs to be more portable
[jra/samba/.git] / source3 / include / libsmbclient.h
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
9
10    
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.
15    
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.
20    
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   =====================================================================*/
24
25 #ifndef SMBCLIENT_H_INCLUDED
26 #define SMBCLIENT_H_INCLUDED
27
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
34
35 #ifdef __cplusplus
36 extern "C" {
37 #endif
38
39 /*-------------------------------------------------------------------*/
40 /* The following are special comments to instruct DOXYGEN (automated 
41  * documentation tool:
42 */
43 /** \defgroup libsmbclient
44 */
45 /** \defgroup structure Data Structures Type and Constants
46 *   \ingroup libsmbclient
47 *   Data structures, types, and constants
48 */
49 /** \defgroup callback Callback function types
50 *   \ingroup libsmbclient
51 *   Callback functions
52 */
53 /** \defgroup file File Functions
54 *   \ingroup libsmbclient
55 *   Functions used to access individual file contents
56 */
57 /** \defgroup directory Directory Functions
58 *   \ingroup libsmbclient
59 *   Functions used to access directory entries
60 */
61 /** \defgroup attribute Attributes Functions
62 *   \ingroup libsmbclient
63 *   Functions used to view or change file and directory attributes
64 */
65 /** \defgroup print Print Functions
66 *   \ingroup libsmbclient
67 *   Functions used to access printing functionality
68 */
69 /** \defgroup misc Miscellaneous Functions
70 *   \ingroup libsmbclient
71 *   Functions that don't fit in to other categories
72 */
73 /*-------------------------------------------------------------------*/   
74
75 /* Make sure we have the following includes for now ... */
76 #include <sys/types.h>
77 #include <sys/stat.h>
78 #include <fcntl.h>
79 #include <utime.h>
80
81 #define SMBC_BASE_FD        10000 /* smallest file descriptor returned */
82
83 #define SMBC_WORKGROUP      1
84 #define SMBC_SERVER         2
85 #define SMBC_FILE_SHARE     3
86 #define SMBC_PRINTER_SHARE  4
87 #define SMBC_COMMS_SHARE    5
88 #define SMBC_IPC_SHARE      6
89 #define SMBC_DIR            7
90 #define SMBC_FILE           8
91 #define SMBC_LINK           9
92
93 /**@ingroup structure
94  * Structure that represents a directory entry.
95  *
96  */
97 struct smbc_dirent 
98 {
99         /** Type of entity.
100             SMBC_WORKGROUP=1,
101             SMBC_SERVER=2, 
102             SMBC_FILE_SHARE=3,
103             SMBC_PRINTER_SHARE=4,
104             SMBC_COMMS_SHARE=5,
105             SMBC_IPC_SHARE=6,
106             SMBC_DIR=7,
107             SMBC_FILE=8,
108             SMBC_LINK=9,*/ 
109         unsigned int smbc_type; 
110
111         /** Length of this smbc_dirent in bytes
112          */
113         unsigned int dirlen;
114         /** The length of the comment string in bytes (does not include
115          *  null terminator)
116          */
117         unsigned int commentlen;
118         /** Points to the null terminated comment string 
119          */
120         char *comment;
121         /** The length of the name string in bytes (does not include
122          *  null terminator)
123          */
124         unsigned int namelen;
125         /** Points to the null terminated name string 
126          */
127         char name[1];
128 };
129
130 /*
131  * Flags for smbc_setxattr()
132  *   Specify a bitwise OR of these, or 0 to add or replace as necessary
133  */
134 #define SMBC_XATTR_FLAG_CREATE       0x1 /* fail if attr already exists */
135 #define SMBC_XATTR_FLAG_REPLACE      0x2 /* fail if attr does not exist */
136
137
138 /*
139  * Mappings of the DOS mode bits, as returned by smbc_getxattr() when the
140  * attribute name "system.dos_attr.mode" (or "system.dos_attr.*" or
141  * "system.*") is specified.
142  */
143 #define SMBC_DOS_MODE_READONLY       0x01
144 #define SMBC_DOS_MODE_HIDDEN         0x02
145 #define SMBC_DOS_MODE_SYSTEM         0x04
146 #define SMBC_DOS_MODE_VOLUME_ID      0x08
147 #define SMBC_DOS_MODE_DIRECTORY      0x10
148 #define SMBC_DOS_MODE_ARCHIVE        0x20
149
150 /*
151  * Valid values for the option "open_share_mode", when calling
152  * smbc_setOptionOpenShareMode()
153  */
154 typedef enum smbc_share_mode
155 {
156     SMBC_SHAREMODE_DENY_DOS     = 0,
157     SMBC_SHAREMODE_DENY_ALL     = 1,
158     SMBC_SHAREMODE_DENY_WRITE   = 2,
159     SMBC_SHAREMODE_DENY_READ    = 3,
160     SMBC_SHAREMODE_DENY_NONE    = 4,
161     SMBC_SHAREMODE_DENY_FCB     = 7
162 } smbc_share_mode;
163
164
165 /**
166  * Values for option SMB Encryption Level, as set and retrieved with
167  * smbc_setOptionSmbEncryptionLevel() and smbc_getOptionSmbEncryptionLevel()
168  */
169 typedef enum smbc_smb_encrypt_level
170 {
171     SMBC_ENCRYPTLEVEL_NONE      = 0,
172     SMBC_ENCRYPTLEVEL_REQUEST   = 1,
173     SMBC_ENCRYPTLEVEL_REQUIRE   = 2
174 } smbc_smb_encrypt_level;
175
176 /**
177  * Use a system independent statvfs struct for smbclient.
178  */
179 struct smbc_statvfs {
180         fsblkcnt_t      f_bavail;
181         fsblkcnt_t      f_bfree;
182         fsblkcnt_t      f_blocks;
183         fsfilcnt_t      f_favail;
184         fsfilcnt_t      f_ffree;
185         fsfilcnt_t      f_files;
186         unsigned long   f_bsize;
187         unsigned long   f_flag;
188         unsigned long   f_frsize;
189         unsigned long   f_fsid;
190         unsigned long   f_namemax;
191 };
192
193 /**
194  * Capabilities set in the f_flag field of struct statvfs, from
195  * smbc_statvfs(). These may be OR-ed together to reflect a full set of
196  * available capabilities.
197  */
198 typedef enum smbc_vfs_feature
199 {
200     /* Defined by POSIX or in Linux include files (low-order bits) */
201     SMBC_VFS_FEATURE_RDONLY         = (1 << 0),
202
203     /* Specific to libsmbclient (high-order bits) */
204     SMBC_VFS_FEATURE_DFS              = (1 << 29),
205     SMBC_VFS_FEATURE_CASE_INSENSITIVE = (1 << 30),
206     SMBC_VFS_FEATURE_NO_UNIXCIFS      = (1 << 31)
207 } smbc_vfs_feature;
208
209 typedef int smbc_bool;
210
211
212 #ifndef ENOATTR
213 # define ENOATTR ENOENT        /* No such attribute */
214 #endif
215
216
217
218
219 /**@ingroup structure
220  * Structure that represents a print job.
221  *
222  */
223 #ifndef _CLIENT_H
224 struct print_job_info 
225 {
226         /** numeric ID of the print job
227          */
228         unsigned short id;
229     
230         /** represents print job priority (lower numbers mean higher priority)
231          */
232         unsigned short priority;
233     
234         /** Size of the print job
235          */
236         size_t size;
237     
238         /** Name of the user that owns the print job
239          */
240         char user[128];
241   
242         /** Name of the print job. This will have no name if an anonymous print
243          *  file was opened. Ie smb://server/printer
244          */
245         char name[128];
246
247         /** Time the print job was spooled
248          */
249         time_t t;
250 };
251 #endif /* _CLIENT_H */
252
253
254 /**@ingroup structure
255  * Server handle 
256  */
257 typedef struct _SMBCSRV  SMBCSRV;
258
259 /**@ingroup structure
260  * File or directory handle 
261  */
262 typedef struct _SMBCFILE SMBCFILE;
263
264 /**@ingroup structure
265  * File or directory handle 
266  */
267 typedef struct _SMBCCTX SMBCCTX;
268
269
270 /*
271  * Flags for SMBCCTX->flags
272  *
273  * NEW CODE SHOULD NOT DIRECTLY MANIPULATE THE CONTEXT STRUCTURE.
274  * Instead, use:
275  *   smbc_setOptionUseKerberos()
276  *   smbc_getOptionUseKerberos()
277  *   smbc_setOptionFallbackAfterKerberos()
278  *   smbc_getOptionFallbackAFterKerberos()
279  *   smbc_setOptionNoAutoAnonymousLogin()
280  *   smbc_getOptionNoAutoAnonymousLogin()
281  */
282 # define SMB_CTX_FLAG_USE_KERBEROS (1 << 0)
283 # define SMB_CTX_FLAG_FALLBACK_AFTER_KERBEROS (1 << 1)
284 # define SMBCCTX_FLAG_NO_AUTO_ANONYMOUS_LOGON (1 << 2)
285
286
287
288 /**@ingroup callback
289  * Authentication callback function type (traditional method)
290  * 
291  * Type for the the authentication function called by the library to
292  * obtain authentication credentals
293  *
294  * For kerberos support the function should just be called without
295  * prompting the user for credentials. Which means a simple 'return'
296  * should work. Take a look at examples/libsmbclient/get_auth_data_fn.h
297  * and examples/libsmbclient/testbrowse.c.
298  *
299  * @param srv       Server being authenticated to
300  *
301  * @param shr       Share being authenticated to
302  *
303  * @param wg        Pointer to buffer containing a "hint" for the
304  *                  workgroup to be authenticated.  Should be filled in
305  *                  with the correct workgroup if the hint is wrong.
306  * 
307  * @param wglen     The size of the workgroup buffer in bytes
308  *
309  * @param un        Pointer to buffer containing a "hint" for the
310  *                  user name to be use for authentication. Should be
311  *                  filled in with the correct workgroup if the hint is
312  *                  wrong.
313  * 
314  * @param unlen     The size of the username buffer in bytes
315  *
316  * @param pw        Pointer to buffer containing to which password 
317  *                  copied
318  * 
319  * @param pwlen     The size of the password buffer in bytes
320  *           
321  */
322 typedef void (*smbc_get_auth_data_fn)(const char *srv, 
323                                       const char *shr,
324                                       char *wg, int wglen, 
325                                       char *un, int unlen,
326                                       char *pw, int pwlen);
327 /**@ingroup callback
328  * Authentication callback function type (method that includes context)
329  * 
330  * Type for the the authentication function called by the library to
331  * obtain authentication credentals
332  *
333  * For kerberos support the function should just be called without
334  * prompting the user for credentials. Which means a simple 'return'
335  * should work. Take a look at examples/libsmbclient/get_auth_data_fn.h
336  * and examples/libsmbclient/testbrowse.c.
337  *
338  * @param c         Pointer to the smb context
339  *
340  * @param srv       Server being authenticated to
341  *
342  * @param shr       Share being authenticated to
343  *
344  * @param wg        Pointer to buffer containing a "hint" for the
345  *                  workgroup to be authenticated.  Should be filled in
346  *                  with the correct workgroup if the hint is wrong.
347  * 
348  * @param wglen     The size of the workgroup buffer in bytes
349  *
350  * @param un        Pointer to buffer containing a "hint" for the
351  *                  user name to be use for authentication. Should be
352  *                  filled in with the correct workgroup if the hint is
353  *                  wrong.
354  * 
355  * @param unlen     The size of the username buffer in bytes
356  *
357  * @param pw        Pointer to buffer containing to which password 
358  *                  copied
359  * 
360  * @param pwlen     The size of the password buffer in bytes
361  *           
362  */
363 typedef void (*smbc_get_auth_data_with_context_fn)(SMBCCTX *c,
364                                                    const char *srv, 
365                                                    const char *shr,
366                                                    char *wg, int wglen, 
367                                                    char *un, int unlen,
368                                                    char *pw, int pwlen);
369
370
371 /**@ingroup callback
372  * Print job info callback function type.
373  *
374  * @param i         pointer to print job information structure
375  *
376  */ 
377 typedef void (*smbc_list_print_job_fn)(struct print_job_info *i);
378                 
379
380 /**@ingroup callback
381  * Check if a server is still good
382  *
383  * @param c         pointer to smb context
384  *
385  * @param srv       pointer to server to check
386  *
387  * @return          0 when connection is good. 1 on error.
388  *
389  */ 
390 typedef int (*smbc_check_server_fn)(SMBCCTX * c, SMBCSRV *srv);
391
392 /**@ingroup callback
393  * Remove a server if unused
394  *
395  * @param c         pointer to smb context
396  *
397  * @param srv       pointer to server to remove
398  *
399  * @return          0 on success. 1 on failure.
400  *
401  */ 
402 typedef int (*smbc_remove_unused_server_fn)(SMBCCTX * c, SMBCSRV *srv);
403
404
405 /**@ingroup callback
406  * Add a server to the cache system
407  *
408  * @param c         pointer to smb context
409  *
410  * @param srv       pointer to server to add
411  *
412  * @param server    server name 
413  *
414  * @param share     share name
415  *
416  * @param workgroup workgroup used to connect
417  *
418  * @param username  username used to connect
419  *
420  * @return          0 on success. 1 on failure.
421  *
422  */ 
423 typedef int (*smbc_add_cached_srv_fn)   (SMBCCTX * c, SMBCSRV *srv, 
424                                     const char * server, const char * share,
425                                     const char * workgroup, const char * username);
426
427 /**@ingroup callback
428  * Look up a server in the cache system
429  *
430  * @param c         pointer to smb context
431  *
432  * @param server    server name to match
433  *
434  * @param share     share name to match
435  *
436  * @param workgroup workgroup to match
437  *
438  * @param username  username to match
439  *
440  * @return          pointer to SMBCSRV on success. NULL on failure.
441  *
442  */ 
443 typedef SMBCSRV * (*smbc_get_cached_srv_fn)   (SMBCCTX * c, const char * server,
444                                                const char * share, const char * workgroup,
445                                                const char * username);
446
447 /**@ingroup callback
448  * Check if a server is still good
449  *
450  * @param c         pointer to smb context
451  *
452  * @param srv       pointer to server to remove
453  *
454  * @return          0 when found and removed. 1 on failure.
455  *
456  */ 
457 typedef int (*smbc_remove_cached_srv_fn)(SMBCCTX * c, SMBCSRV *srv);
458
459
460 /**@ingroup callback
461  * Try to remove all servers from the cache system and disconnect
462  *
463  * @param c         pointer to smb context
464  *
465  * @return          0 when found and removed. 1 on failure.
466  *
467  */ 
468 typedef int (*smbc_purge_cached_fn)     (SMBCCTX * c);
469
470
471
472 /*****************************************
473  * Getters and setters for CONFIGURATION *
474  *****************************************/
475
476 /** Get the debug level */
477 int
478 smbc_getDebug(SMBCCTX *c);
479
480 /** Set the debug level */
481 void
482 smbc_setDebug(SMBCCTX *c, int debug);
483
484 /** Get the netbios name used for making connections */
485 char *
486 smbc_getNetbiosName(SMBCCTX *c);
487
488 /** Set the netbios name used for making connections */
489 void
490 smbc_setNetbiosName(SMBCCTX *c, char * netbios_name);
491
492 /** Get the workgroup used for making connections */
493 char *
494 smbc_getWorkgroup(SMBCCTX *c);
495
496 /** Set the workgroup used for making connections */
497 void smbc_setWorkgroup(SMBCCTX *c, char * workgroup);
498
499 /** Get the username used for making connections */
500 char *
501 smbc_getUser(SMBCCTX *c);
502
503 /** Set the username used for making connections */
504 void
505 smbc_setUser(SMBCCTX *c, char * user);
506
507 /**
508  * Get the timeout used for waiting on connections and response data
509  * (in milliseconds)
510  */
511 int
512 smbc_getTimeout(SMBCCTX *c);
513
514 /**
515  * Set the timeout used for waiting on connections and response data
516  * (in milliseconds)
517  */
518 void
519 smbc_setTimeout(SMBCCTX *c, int timeout);
520
521
522
523 /***********************************
524  * Getters and setters for OPTIONS *
525  ***********************************/
526
527 /** Get whether to log to standard error instead of standard output */
528 smbc_bool
529 smbc_getOptionDebugToStderr(SMBCCTX *c);
530
531 /** Set whether to log to standard error instead of standard output */
532 void
533 smbc_setOptionDebugToStderr(SMBCCTX *c, smbc_bool b);
534
535 /**
536  * Get whether to use new-style time attribute names, e.g. WRITE_TIME rather
537  * than the old-style names such as M_TIME.  This allows also setting/getting
538  * CREATE_TIME which was previously unimplemented.  (Note that the old C_TIME
539  * was supposed to be CHANGE_TIME but was confused and sometimes referred to
540  * CREATE_TIME.)
541  */
542 smbc_bool
543 smbc_getOptionFullTimeNames(SMBCCTX *c);
544
545 /**
546  * Set whether to use new-style time attribute names, e.g. WRITE_TIME rather
547  * than the old-style names such as M_TIME.  This allows also setting/getting
548  * CREATE_TIME which was previously unimplemented.  (Note that the old C_TIME
549  * was supposed to be CHANGE_TIME but was confused and sometimes referred to
550  * CREATE_TIME.)
551  */
552 void
553 smbc_setOptionFullTimeNames(SMBCCTX *c, smbc_bool b);
554
555 /**
556  * Get the share mode to use for files opened with SMBC_open_ctx().  The
557  * default is SMBC_SHAREMODE_DENY_NONE.
558  */
559 smbc_share_mode
560 smbc_getOptionOpenShareMode(SMBCCTX *c);
561
562 /**
563  * Set the share mode to use for files opened with SMBC_open_ctx().  The
564  * default is SMBC_SHAREMODE_DENY_NONE.
565  */
566 void
567 smbc_setOptionOpenShareMode(SMBCCTX *c, smbc_share_mode share_mode);
568
569 /** Retrieve a previously saved user data handle */
570 void *
571 smbc_getOptionUserData(SMBCCTX *c);
572
573 /** Save a user data handle */
574 void
575 smbc_setOptionUserData(SMBCCTX *c, void *user_data);
576
577 /** Get the encoded value for encryption level. */
578 smbc_smb_encrypt_level
579 smbc_getOptionSmbEncryptionLevel(SMBCCTX *c);
580
581 /** Set the encoded value for encryption level. */
582 void
583 smbc_setOptionSmbEncryptionLevel(SMBCCTX *c, smbc_smb_encrypt_level level);
584
585 /**
586  * Get whether to treat file names as case-sensitive if we can't determine
587  * when connecting to the remote share whether the file system is case
588  * sensitive. This defaults to FALSE since it's most likely that if we can't
589  * retrieve the file system attributes, it's a very old file system that does
590  * not support case sensitivity.
591  */
592 smbc_bool
593 smbc_getOptionCaseSensitive(SMBCCTX *c);
594
595 /**
596  * Set whether to treat file names as case-sensitive if we can't determine
597  * when connecting to the remote share whether the file system is case
598  * sensitive. This defaults to FALSE since it's most likely that if we can't
599  * retrieve the file system attributes, it's a very old file system that does
600  * not support case sensitivity.
601  */
602 void
603 smbc_setOptionCaseSensitive(SMBCCTX *c, smbc_bool b);
604
605
606 /**
607  * Get from how many local master browsers should the list of workgroups be
608  * retrieved.  It can take up to 12 minutes or longer after a server becomes a
609  * local master browser, for it to have the entire browse list (the list of
610  * workgroups/domains) from an entire network.  Since a client never knows
611  * which local master browser will be found first, the one which is found
612  * first and used to retrieve a browse list may have an incomplete or empty
613  * browse list.  By requesting the browse list from multiple local master
614  * browsers, a more complete list can be generated.  For small networks (few
615  * workgroups), it is recommended that this value be set to 0, causing the
616  * browse lists from all found local master browsers to be retrieved and
617  * merged.  For networks with many workgroups, a suitable value for this
618  * variable is probably somewhere around 3. (Default: 3).
619  */
620 int
621 smbc_getOptionBrowseMaxLmbCount(SMBCCTX *c);
622
623 /**
624  * Set from how many local master browsers should the list of workgroups be
625  * retrieved.  It can take up to 12 minutes or longer after a server becomes a
626  * local master browser, for it to have the entire browse list (the list of
627  * workgroups/domains) from an entire network.  Since a client never knows
628  * which local master browser will be found first, the one which is found
629  * first and used to retrieve a browse list may have an incomplete or empty
630  * browse list.  By requesting the browse list from multiple local master
631  * browsers, a more complete list can be generated.  For small networks (few
632  * workgroups), it is recommended that this value be set to 0, causing the
633  * browse lists from all found local master browsers to be retrieved and
634  * merged.  For networks with many workgroups, a suitable value for this
635  * variable is probably somewhere around 3. (Default: 3).
636  */
637 void
638 smbc_setOptionBrowseMaxLmbCount(SMBCCTX *c, int count);
639
640 /**
641  * Get whether to url-encode readdir entries.
642  *
643  * There is a difference in the desired return strings from
644  * smbc_readdir() depending upon whether the filenames are to
645  * be displayed to the user, or whether they are to be
646  * appended to the path name passed to smbc_opendir() to call
647  * a further smbc_ function (e.g. open the file with
648  * smbc_open()).  In the former case, the filename should be
649  * in "human readable" form.  In the latter case, the smbc_
650  * functions expect a URL which must be url-encoded.  Those
651  * functions decode the URL.  If, for example, smbc_readdir()
652  * returned a file name of "abc%20def.txt", passing a path
653  * with this file name attached to smbc_open() would cause
654  * smbc_open to attempt to open the file "abc def.txt" since
655  * the %20 is decoded into a space.
656  *
657  * Set this option to True if the names returned by
658  * smbc_readdir() should be url-encoded such that they can be
659  * passed back to another smbc_ call.  Set it to False if the
660  * names returned by smbc_readdir() are to be presented to the
661  * user.
662  *
663  * For backwards compatibility, this option defaults to False.
664  */
665 smbc_bool
666 smbc_getOptionUrlEncodeReaddirEntries(SMBCCTX *c);
667
668 /**
669  * Set whether to url-encode readdir entries.
670  *
671  * There is a difference in the desired return strings from
672  * smbc_readdir() depending upon whether the filenames are to
673  * be displayed to the user, or whether they are to be
674  * appended to the path name passed to smbc_opendir() to call
675  * a further smbc_ function (e.g. open the file with
676  * smbc_open()).  In the former case, the filename should be
677  * in "human readable" form.  In the latter case, the smbc_
678  * functions expect a URL which must be url-encoded.  Those
679  * functions decode the URL.  If, for example, smbc_readdir()
680  * returned a file name of "abc%20def.txt", passing a path
681  * with this file name attached to smbc_open() would cause
682  * smbc_open to attempt to open the file "abc def.txt" since
683  * the %20 is decoded into a space.
684  *
685  * Set this option to True if the names returned by
686  * smbc_readdir() should be url-encoded such that they can be
687  * passed back to another smbc_ call.  Set it to False if the
688  * names returned by smbc_readdir() are to be presented to the
689  * user.
690  *
691  * For backwards compatibility, this option defaults to False.
692  */
693 void
694 smbc_setOptionUrlEncodeReaddirEntries(SMBCCTX *c, smbc_bool b);
695
696 /**
697  * Get whether to use the same connection for all shares on a server.
698  *
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.
707  */
708 smbc_bool
709 smbc_getOptionOneSharePerServer(SMBCCTX *c);
710
711 /**
712  * Set whether to use the same connection for all shares on a server.
713  *
714  * Some Windows versions appear to have a limit to the number
715  * of concurrent SESSIONs and/or TREE CONNECTions.  In
716  * one-shot programs (i.e. the program runs and then quickly
717  * ends, thereby shutting down all connections), it is
718  * probably reasonable to establish a new connection for each
719  * share.  In long-running applications, the limitation can be
720  * avoided by using only a single connection to each server,
721  * and issuing a new TREE CONNECT when the share is accessed.
722  */
723 void
724 smbc_setOptionOneSharePerServer(SMBCCTX *c, smbc_bool b);
725
726 /** Get whether to enable use of kerberos */
727 smbc_bool
728 smbc_getOptionUseKerberos(SMBCCTX *c);
729
730 /** Set whether to enable use of kerberos */
731 void
732 smbc_setOptionUseKerberos(SMBCCTX *c, smbc_bool b);
733
734 /** Get whether to fallback after kerberos */
735 smbc_bool
736 smbc_getOptionFallbackAfterKerberos(SMBCCTX *c);
737
738 /** Set whether to fallback after kerberos */
739 void
740 smbc_setOptionFallbackAfterKerberos(SMBCCTX *c, smbc_bool b);
741
742 /** Get whether to automatically select anonymous login */
743 smbc_bool
744 smbc_getOptionNoAutoAnonymousLogin(SMBCCTX *c);
745
746 /** Set whether to automatically select anonymous login */
747 void
748 smbc_setOptionNoAutoAnonymousLogin(SMBCCTX *c, smbc_bool b);
749
750
751
752 /*************************************
753  * Getters and setters for FUNCTIONS *
754  *************************************/
755
756 /** Get the function for obtaining authentication data */
757 smbc_get_auth_data_fn smbc_getFunctionAuthData(SMBCCTX *c);
758
759 /** Set the function for obtaining authentication data */
760 void smbc_setFunctionAuthData(SMBCCTX *c, smbc_get_auth_data_fn fn);
761
762 /** Get the new-style authentication function which includes the context. */
763 smbc_get_auth_data_with_context_fn
764 smbc_getFunctionAuthDataWithContext(SMBCCTX *c);
765
766 /** Set the new-style authentication function which includes the context. */
767 void
768 smbc_setFunctionAuthDataWithContext(SMBCCTX *c,
769                                     smbc_get_auth_data_with_context_fn fn);
770
771 /** Get the function for checking if a server is still good */
772 smbc_check_server_fn smbc_getFunctionCheckServer(SMBCCTX *c);
773
774 /** Set the function for checking if a server is still good */
775 void smbc_setFunctionCheckServer(SMBCCTX *c, smbc_check_server_fn fn);
776
777 /** Get the function for removing a server if unused */
778 smbc_remove_unused_server_fn smbc_getFunctionRemoveUnusedServer(SMBCCTX *c);
779
780 /** Set the function for removing a server if unused */
781 void smbc_setFunctionRemoveUnusedServer(SMBCCTX *c,
782                                         smbc_remove_unused_server_fn fn);
783
784 /** Get the function for adding a cached server */
785 smbc_add_cached_srv_fn smbc_getFunctionAddCachedServer(SMBCCTX *c);
786
787 /** Set the function for adding a cached server */
788 void smbc_setFunctionAddCachedServer(SMBCCTX *c, smbc_add_cached_srv_fn fn);
789
790 /** Get the function for server cache lookup */
791 smbc_get_cached_srv_fn smbc_getFunctionGetCachedServer(SMBCCTX *c);
792
793 /** Set the function for server cache lookup */
794 void smbc_setFunctionGetCachedServer(SMBCCTX *c, smbc_get_cached_srv_fn fn);
795
796 /** Get the function for server cache removal */
797 smbc_remove_cached_srv_fn smbc_getFunctionRemoveCachedServer(SMBCCTX *c);
798
799 /** Set the function for server cache removal */
800 void smbc_setFunctionRemoveCachedServer(SMBCCTX *c,
801                                         smbc_remove_cached_srv_fn fn);
802
803 /**
804  * Get the function for server cache purging.  This function tries to
805  * remove all cached servers (e.g. on disconnect)
806  */
807 smbc_purge_cached_fn smbc_getFunctionPurgeCachedServers(SMBCCTX *c);
808
809 /**
810  * Set the function for server cache purging.  This function tries to
811  * remove all cached servers (e.g. on disconnect)
812  */
813 void smbc_setFunctionPurgeCachedServers(SMBCCTX *c,
814                                         smbc_purge_cached_fn fn);
815
816 /** Get the function to store private data of the server cache */
817 struct smbc_server_cache * smbc_getServerCacheData(SMBCCTX *c);
818
819 /** Set the function to store private data of the server cache */
820 void smbc_setServerCacheData(SMBCCTX *c, struct smbc_server_cache * cache);
821
822
823
824 /*****************************************************************
825  * Callable functions for files.                                 *
826  * Each callable has a function signature typedef, a declaration *
827  * for the getter, and a declaration for the setter.             *
828  *****************************************************************/
829
830 typedef SMBCFILE * (*smbc_open_fn)(SMBCCTX *c,
831                                    const char *fname,
832                                    int flags,
833                                    mode_t mode);
834 smbc_open_fn smbc_getFunctionOpen(SMBCCTX *c);
835 void smbc_setFunctionOpen(SMBCCTX *c, smbc_open_fn fn);
836
837 typedef SMBCFILE * (*smbc_creat_fn)(SMBCCTX *c,
838                                     const char *path,
839                                     mode_t mode);
840 smbc_creat_fn smbc_getFunctionCreat(SMBCCTX *c);
841 void smbc_setFunctionCreat(SMBCCTX *c, smbc_creat_fn);
842
843 typedef ssize_t (*smbc_read_fn)(SMBCCTX *c,
844                                 SMBCFILE *file,
845                                 void *buf,
846                                 size_t count);
847 smbc_read_fn smbc_getFunctionRead(SMBCCTX *c);
848 void smbc_setFunctionRead(SMBCCTX *c, smbc_read_fn fn);
849
850 typedef ssize_t (*smbc_write_fn)(SMBCCTX *c,
851                                  SMBCFILE *file,
852                                  const void *buf,
853                                  size_t count);
854 smbc_write_fn smbc_getFunctionWrite(SMBCCTX *c);
855 void smbc_setFunctionWrite(SMBCCTX *c, smbc_write_fn fn);
856
857 typedef int (*smbc_unlink_fn)(SMBCCTX *c,
858                               const char *fname);
859 smbc_unlink_fn smbc_getFunctionUnlink(SMBCCTX *c);
860 void smbc_setFunctionUnlink(SMBCCTX *c, smbc_unlink_fn fn);
861
862 typedef int (*smbc_rename_fn)(SMBCCTX *ocontext,
863                               const char *oname,
864                               SMBCCTX *ncontext,
865                               const char *nname);
866 smbc_rename_fn smbc_getFunctionRename(SMBCCTX *c);
867 void smbc_setFunctionRename(SMBCCTX *c, smbc_rename_fn fn);
868
869 typedef off_t (*smbc_lseek_fn)(SMBCCTX *c,
870                                SMBCFILE * file,
871                                off_t offset,
872                                int whence);
873 smbc_lseek_fn smbc_getFunctionLseek(SMBCCTX *c);
874 void smbc_setFunctionLseek(SMBCCTX *c, smbc_lseek_fn fn);
875
876 typedef int (*smbc_stat_fn)(SMBCCTX *c,
877                             const char *fname,
878                             struct stat *st);
879 smbc_stat_fn smbc_getFunctionStat(SMBCCTX *c);
880 void smbc_setFunctionStat(SMBCCTX *c, smbc_stat_fn fn);
881
882 typedef int (*smbc_fstat_fn)(SMBCCTX *c,
883                              SMBCFILE *file,
884                              struct stat *st);
885 smbc_fstat_fn smbc_getFunctionFstat(SMBCCTX *c);
886 void smbc_setFunctionFstat(SMBCCTX *c, smbc_fstat_fn fn);
887
888 typedef int (*smbc_statvfs_fn)(SMBCCTX *c,
889                                char *path,
890                                struct smbc_statvfs *st);
891 smbc_statvfs_fn smbc_getFunctionStatVFS(SMBCCTX *c);
892 void smbc_setFunctionStatVFS(SMBCCTX *c, smbc_statvfs_fn fn);
893
894 typedef int (*smbc_fstatvfs_fn)(SMBCCTX *c,
895                                 SMBCFILE *file,
896                                 struct smbc_statvfs *st);
897 smbc_fstatvfs_fn smbc_getFunctionFstatVFS(SMBCCTX *c);
898 void smbc_setFunctionFstatVFS(SMBCCTX *c, smbc_fstatvfs_fn fn);
899
900 typedef int (*smbc_ftruncate_fn)(SMBCCTX *c,
901                                  SMBCFILE *f,
902                                  off_t size);
903 smbc_ftruncate_fn smbc_getFunctionFtruncate(SMBCCTX *c);
904 void smbc_setFunctionFtruncate(SMBCCTX *c, smbc_ftruncate_fn fn);
905
906 typedef int (*smbc_close_fn)(SMBCCTX *c,
907                              SMBCFILE *file);
908 smbc_close_fn smbc_getFunctionClose(SMBCCTX *c);
909 void smbc_setFunctionClose(SMBCCTX *c, smbc_close_fn fn);
910
911
912
913 /*****************************************************************
914  * Callable functions for directories.                           *
915  * Each callable has a function signature typedef, a declaration *
916  * for the getter, and a declaration for the setter.             *
917  *****************************************************************/
918
919 typedef SMBCFILE * (*smbc_opendir_fn)(SMBCCTX *c,
920                                       const char *fname);
921 smbc_opendir_fn smbc_getFunctionOpendir(SMBCCTX *c);
922 void smbc_setFunctionOpendir(SMBCCTX *c, smbc_opendir_fn fn);
923
924 typedef int (*smbc_closedir_fn)(SMBCCTX *c,
925                                 SMBCFILE *dir);
926 smbc_closedir_fn smbc_getFunctionClosedir(SMBCCTX *c);
927 void smbc_setFunctionClosedir(SMBCCTX *c, smbc_closedir_fn fn);
928
929 typedef struct smbc_dirent * (*smbc_readdir_fn)(SMBCCTX *c,
930                                                 SMBCFILE *dir);
931 smbc_readdir_fn smbc_getFunctionReaddir(SMBCCTX *c);
932 void smbc_setFunctionReaddir(SMBCCTX *c, smbc_readdir_fn fn);
933
934 typedef int (*smbc_getdents_fn)(SMBCCTX *c,
935                                 SMBCFILE *dir,
936                                 struct smbc_dirent *dirp,
937                                 int count);
938 smbc_getdents_fn smbc_getFunctionGetdents(SMBCCTX *c);
939 void smbc_setFunctionGetdents(SMBCCTX *c, smbc_getdents_fn fn);
940
941 typedef int (*smbc_mkdir_fn)(SMBCCTX *c,
942                              const char *fname,
943                              mode_t mode);
944 smbc_mkdir_fn smbc_getFunctionMkdir(SMBCCTX *c);
945 void smbc_setFunctionMkdir(SMBCCTX *c, smbc_mkdir_fn fn);
946
947 typedef int (*smbc_rmdir_fn)(SMBCCTX *c,
948                              const char *fname);
949 smbc_rmdir_fn smbc_getFunctionRmdir(SMBCCTX *c);
950 void smbc_setFunctionRmdir(SMBCCTX *c, smbc_rmdir_fn fn);
951
952 typedef off_t (*smbc_telldir_fn)(SMBCCTX *c,
953                                  SMBCFILE *dir);
954 smbc_telldir_fn smbc_getFunctionTelldir(SMBCCTX *c);
955 void smbc_setFunctionTelldir(SMBCCTX *c, smbc_telldir_fn fn);
956
957 typedef int (*smbc_lseekdir_fn)(SMBCCTX *c,
958                                 SMBCFILE *dir,
959                                 off_t offset);
960 smbc_lseekdir_fn smbc_getFunctionLseekdir(SMBCCTX *c);
961 void smbc_setFunctionLseekdir(SMBCCTX *c, smbc_lseekdir_fn fn);
962
963 typedef int (*smbc_fstatdir_fn)(SMBCCTX *c,
964                                 SMBCFILE *dir,
965                                 struct stat *st);
966 smbc_fstatdir_fn smbc_getFunctionFstatdir(SMBCCTX *c);
967 void smbc_setFunctionFstatdir(SMBCCTX *c, smbc_fstatdir_fn fn);
968
969
970
971 /*****************************************************************
972  * Callable functions applicable to both files and directories.  *
973  * Each callable has a function signature typedef, a declaration *
974  * for the getter, and a declaration for the setter.             *
975  *****************************************************************/
976
977 typedef int (*smbc_chmod_fn)(SMBCCTX *c,
978                              const char *fname,
979                              mode_t mode);
980 smbc_chmod_fn smbc_getFunctionChmod(SMBCCTX *c);
981 void smbc_setFunctionChmod(SMBCCTX *c, smbc_chmod_fn fn);
982
983 typedef int (*smbc_utimes_fn)(SMBCCTX *c,
984                               const char *fname,
985                               struct timeval *tbuf);
986 smbc_utimes_fn smbc_getFunctionUtimes(SMBCCTX *c);
987 void smbc_setFunctionUtimes(SMBCCTX *c, smbc_utimes_fn fn);
988
989 typedef int (*smbc_setxattr_fn)(SMBCCTX *context,
990                                 const char *fname,
991                                 const char *name,
992                                 const void *value,
993                                 size_t size,
994                                 int flags);
995 smbc_setxattr_fn smbc_getFunctionSetxattr(SMBCCTX *c);
996 void smbc_setFunctionSetxattr(SMBCCTX *c, smbc_setxattr_fn fn);
997
998 typedef int (*smbc_getxattr_fn)(SMBCCTX *context,
999                                 const char *fname,
1000                                 const char *name,
1001                                 const void *value,
1002                                 size_t size);
1003 smbc_getxattr_fn smbc_getFunctionGetxattr(SMBCCTX *c);
1004 void smbc_setFunctionGetxattr(SMBCCTX *c, smbc_getxattr_fn fn);
1005
1006 typedef int (*smbc_removexattr_fn)(SMBCCTX *context,
1007                                    const char *fname,
1008                                    const char *name);
1009 smbc_removexattr_fn smbc_getFunctionRemovexattr(SMBCCTX *c);
1010 void smbc_setFunctionRemovexattr(SMBCCTX *c, smbc_removexattr_fn fn);
1011
1012 typedef int (*smbc_listxattr_fn)(SMBCCTX *context,
1013                                  const char *fname,
1014                                  char *list,
1015                                  size_t size);
1016 smbc_listxattr_fn smbc_getFunctionListxattr(SMBCCTX *c);
1017 void smbc_setFunctionListxattr(SMBCCTX *c, smbc_listxattr_fn fn);
1018
1019
1020
1021 /*****************************************************************
1022  * Callable functions for printing.                              *
1023  * Each callable has a function signature typedef, a declaration *
1024  * for the getter, and a declaration for the setter.             *
1025  *****************************************************************/
1026
1027 typedef int (*smbc_print_file_fn)(SMBCCTX *c_file,
1028                                   const char *fname,
1029                                   SMBCCTX *c_print,
1030                                   const char *printq);
1031 smbc_print_file_fn smbc_getFunctionPrintFile(SMBCCTX *c);
1032 void smbc_setFunctionPrintFile(SMBCCTX *c, smbc_print_file_fn fn);
1033
1034 typedef SMBCFILE * (*smbc_open_print_job_fn)(SMBCCTX *c,
1035                                              const char *fname);
1036 smbc_open_print_job_fn smbc_getFunctionOpenPrintJob(SMBCCTX *c);
1037 void smbc_setFunctionOpenPrintJob(SMBCCTX *c,
1038                                   smbc_open_print_job_fn fn);
1039
1040 typedef int (*smbc_list_print_jobs_fn)(SMBCCTX *c,
1041                                        const char *fname,
1042                                        smbc_list_print_job_fn fn);
1043 smbc_list_print_jobs_fn smbc_getFunctionListPrintJobs(SMBCCTX *c);
1044 void smbc_setFunctionListPrintJobs(SMBCCTX *c,
1045                                    smbc_list_print_jobs_fn fn);
1046
1047 typedef int (*smbc_unlink_print_job_fn)(SMBCCTX *c,
1048                                         const char *fname,
1049                                         int id);
1050 smbc_unlink_print_job_fn smbc_getFunctionUnlinkPrintJob(SMBCCTX *c);
1051 void smbc_setFunctionUnlinkPrintJob(SMBCCTX *c,
1052                                     smbc_unlink_print_job_fn fn);
1053
1054
1055 /**@ingroup misc
1056  * Create a new SBMCCTX (a context).
1057  *
1058  * Must be called before the context is passed to smbc_context_init()
1059  *
1060  * @return          The given SMBCCTX pointer on success, NULL on error with errno set:
1061  *                  - ENOMEM Out of memory
1062  *
1063  * @see             smbc_free_context(), smbc_init_context()
1064  *
1065  * @note            Do not forget to smbc_init_context() the returned SMBCCTX pointer !
1066  */
1067 SMBCCTX * smbc_new_context(void);
1068
1069 /**@ingroup misc
1070  * Delete a SBMCCTX (a context) acquired from smbc_new_context().
1071  *
1072  * The context will be deleted if possible.
1073  *
1074  * @param context   A pointer to a SMBCCTX obtained from smbc_new_context()
1075  *
1076  * @param shutdown_ctx   If 1, all connections and files will be closed even if they are busy.
1077  *
1078  *
1079  * @return          Returns 0 on succes. Returns 1 on failure with errno set:
1080  *                  - EBUSY Server connections are still used, Files are open or cache 
1081  *                          could not be purged
1082  *                  - EBADF context == NULL
1083  *
1084  * @see             smbc_new_context()
1085  *
1086  * @note            It is advised to clean up all the contexts with shutdown_ctx set to 1
1087  *                  just before exit()'ing. When shutdown_ctx is 0, this function can be
1088  *                  use in periodical cleanup functions for example.
1089  */
1090 int smbc_free_context(SMBCCTX * context, int shutdown_ctx);
1091
1092
1093 /**@ingroup misc
1094  *
1095  * @deprecated.  Use smbc_setOption*() functions instead.
1096  */
1097 void
1098 smbc_option_set(SMBCCTX *context,
1099                 char *option_name,
1100                 ... /* option_value */);
1101
1102 /*
1103  * @deprecated.  Use smbc_getOption*() functions instead.
1104  */
1105 void *
1106 smbc_option_get(SMBCCTX *context,
1107                 char *option_name);
1108
1109 /**@ingroup misc
1110  * Initialize a SBMCCTX (a context).
1111  *
1112  * Must be called before using any SMBCCTX API function
1113  *
1114  * @param context   A pointer to a SMBCCTX obtained from smbc_new_context()
1115  *
1116  * @return          A pointer to the given SMBCCTX on success,
1117  *                  NULL on error with errno set:
1118  *                  - EBADF  NULL context given
1119  *                  - ENOMEM Out of memory
1120  *                  - ENOENT The smb.conf file would not load
1121  *
1122  * @see             smbc_new_context()
1123  *
1124  * @note            my_context = smbc_init_context(smbc_new_context())
1125  *                  is perfectly safe, but it might leak memory on
1126  *                  smbc_context_init() failure. Avoid this.
1127  *                  You'll have to call smbc_free_context() yourself
1128  *                  on failure.  
1129  */
1130
1131 SMBCCTX * smbc_init_context(SMBCCTX * context);
1132
1133 /**@ingroup misc
1134  * Initialize the samba client library.
1135  *
1136  * Must be called before using any of the smbclient API function
1137  *  
1138  * @param fn        The function that will be called to obtaion 
1139  *                  authentication credentials.
1140  *
1141  * @param debug     Allows caller to set the debug level. Can be
1142  *                  changed in smb.conf file. Allows caller to set
1143  *                  debugging if no smb.conf.
1144  *   
1145  * @return          0 on success, < 0 on error with errno set:
1146  *                  - ENOMEM Out of memory
1147  *                  - ENOENT The smb.conf file would not load
1148  *
1149  */
1150
1151 int smbc_init(smbc_get_auth_data_fn fn, int debug);
1152
1153 /**@ingroup misc
1154  * Set or retrieve the compatibility library's context pointer
1155  *
1156  * @param context   New context to use, or NULL.  If a new context is provided,
1157  *                  it must have allocated with smbc_new_context() and
1158  *                  initialized with smbc_init_context(), followed, optionally,
1159  *                  by some manual changes to some of the non-internal fields.
1160  *
1161  * @return          The old context.
1162  *
1163  * @see             smbc_new_context(), smbc_init_context(), smbc_init()
1164  *
1165  * @note            This function may be called prior to smbc_init() to force
1166  *                  use of the next context without any internal calls to
1167  *                  smbc_new_context() or smbc_init_context().  It may also
1168  *                  be called after smbc_init() has already called those two
1169  *                  functions, to replace the existing context with a new one.
1170  *                  Care should be taken, in this latter case, to ensure that
1171  *                  the server cache and any data allocated by the
1172  *                  authentication functions have been freed, if necessary.
1173  */
1174
1175 SMBCCTX * smbc_set_context(SMBCCTX * new_context);
1176
1177 /**@ingroup file
1178  * Open a file on an SMB server.
1179  *
1180  * @param furl      The smb url of the file to be opened. 
1181  *
1182  * @param flags     Is one of O_RDONLY, O_WRONLY or O_RDWR which 
1183  *                  request opening  the  file  read-only,write-only
1184  *                  or read/write. flags may also be bitwise-or'd with
1185  *                  one or  more of  the following: 
1186  *                  O_CREAT - If the file does not exist it will be 
1187  *                  created.
1188  *                  O_EXCL - When  used with O_CREAT, if the file 
1189  *                  already exists it is an error and the open will 
1190  *                  fail. 
1191  *                  O_TRUNC - If the file already exists it will be
1192  *                  truncated.
1193  *                  O_APPEND The  file  is  opened  in  append mode 
1194  *
1195  * @param mode      mode specifies the permissions to use if a new 
1196  *                  file is created.  It  is  modified  by  the 
1197  *                  process's umask in the usual way: the permissions
1198  *                  of the created file are (mode & ~umask) 
1199  *
1200  *                  Not currently use, but there for future use.
1201  *                  We will map this to SYSTEM, HIDDEN, etc bits
1202  *                  that reverses the mapping that smbc_fstat does.
1203  *
1204  * @return          Valid file handle, < 0 on error with errno set:
1205  *                  - ENOMEM  Out of memory
1206  *                  - EINVAL if an invalid parameter passed, like no 
1207  *                  file, or smbc_init not called.
1208  *                  - EEXIST  pathname already exists and O_CREAT and 
1209  *                  O_EXCL were used.
1210  *                  - EISDIR  pathname  refers  to  a  directory  and  
1211  *                  the access requested involved writing.
1212  *                  - EACCES  The requested access to the file is not 
1213  *                  allowed 
1214  *                  - ENODEV The requested share does not exist
1215  *                  - ENOTDIR A file on the path is not a directory
1216  *                  - ENOENT  A directory component in pathname does 
1217  *                  not exist.
1218  *
1219  * @see             smbc_creat()
1220  *
1221  * @note            This call uses an underlying routine that may create
1222  *                  a new connection to the server specified in the URL.
1223  *                  If the credentials supplied in the URL, or via the
1224  *                  auth_fn in the smbc_init call, fail, this call will
1225  *                  try again with an empty username and password. This 
1226  *                  often gets mapped to the guest account on some machines.
1227  */
1228
1229 int smbc_open(const char *furl, int flags, mode_t mode);
1230
1231 /**@ingroup file
1232  * Create a file on an SMB server.
1233  *
1234  * Same as calling smbc_open() with flags = O_CREAT|O_WRONLY|O_TRUNC 
1235  *   
1236  * @param furl      The smb url of the file to be created
1237  *  
1238  * @param mode      mode specifies the permissions to use if  a  new  
1239  *                  file is created.  It  is  modified  by  the 
1240  *                  process's umask in the usual way: the permissions
1241  *                  of the created file are (mode & ~umask)
1242  *
1243  *                  NOTE, the above is not true. We are dealing with 
1244  *                  an SMB server, which has no concept of a umask!
1245  *      
1246  * @return          Valid file handle, < 0 on error with errno set:
1247  *                  - ENOMEM  Out of memory
1248  *                  - EINVAL if an invalid parameter passed, like no 
1249  *                  file, or smbc_init not called.
1250  *                  - EEXIST  pathname already exists and O_CREAT and
1251  *                  O_EXCL were used.
1252  *                  - EISDIR  pathname  refers  to  a  directory  and
1253  *                  the access requested involved writing.
1254  *                  - EACCES  The requested access to the file is not
1255  *                  allowed 
1256  *                  - ENOENT  A directory component in pathname does 
1257  *                  not exist.
1258  *                  - ENODEV The requested share does not exist.
1259  * @see             smbc_open()
1260  *
1261  */
1262
1263 int smbc_creat(const char *furl, mode_t mode);
1264
1265 /**@ingroup file
1266  * Read from a file using an opened file handle.
1267  *
1268  * @param fd        Open file handle from smbc_open() or smbc_creat()
1269  *
1270  * @param buf       Pointer to buffer to recieve read data
1271  *
1272  * @param bufsize   Size of buf in bytes
1273  *
1274  * @return          Number of bytes read, < 0 on error with errno set:
1275  *                  - EISDIR fd refers to a directory
1276  *                  - EBADF  fd  is  not  a valid file descriptor or 
1277  *                  is not open for reading.
1278  *                  - EINVAL fd is attached to an object which is 
1279  *                  unsuitable for reading, or no buffer passed or
1280  *                  smbc_init not called.
1281  *
1282  * @see             smbc_open(), smbc_write()
1283  *
1284  */
1285 ssize_t smbc_read(int fd, void *buf, size_t bufsize);
1286
1287
1288 /**@ingroup file
1289  * Write to a file using an opened file handle.
1290  *
1291  * @param fd        Open file handle from smbc_open() or smbc_creat()
1292  *
1293  * @param buf       Pointer to buffer to recieve read data
1294  *
1295  * @param bufsize   Size of buf in bytes
1296  *
1297  * @return          Number of bytes written, < 0 on error with errno set:
1298  *                  - EISDIR fd refers to a directory.
1299  *                  - EBADF  fd  is  not  a valid file descriptor or 
1300  *                  is not open for reading.
1301  *                  - EINVAL fd is attached to an object which is 
1302  *                  unsuitable for reading, or no buffer passed or
1303  *                  smbc_init not called.
1304  *
1305  * @see             smbc_open(), smbc_read()
1306  *
1307  */
1308 ssize_t smbc_write(int fd, const void *buf, size_t bufsize);
1309
1310
1311 /**@ingroup file
1312  * Seek to a specific location in a file.
1313  *
1314  * @param fd        Open file handle from smbc_open() or smbc_creat()
1315  * 
1316  * @param offset    Offset in bytes from whence
1317  * 
1318  * @param whence    A location in the file:
1319  *                  - SEEK_SET The offset is set to offset bytes from
1320  *                  the beginning of the file
1321  *                  - SEEK_CUR The offset is set to current location 
1322  *                  plus offset bytes.
1323  *                  - SEEK_END The offset is set to the size of the 
1324  *                  file plus offset bytes.
1325  *
1326  * @return          Upon successful completion, lseek returns the 
1327  *                  resulting offset location as measured in bytes 
1328  *                  from the beginning  of the file. Otherwise, a value
1329  *                  of (off_t)-1 is returned and errno is set to 
1330  *                  indicate the error:
1331  *                  - EBADF  Fildes is not an open file descriptor.
1332  *                  - EINVAL Whence is not a proper value or smbc_init
1333  *                    not called.
1334  *
1335  * @todo Are all the whence values really supported?
1336  * 
1337  * @todo Are errno values complete and correct?
1338  */
1339 off_t smbc_lseek(int fd, off_t offset, int whence);
1340
1341
1342 /**@ingroup file
1343  * Close an open file handle.
1344  *
1345  * @param fd        The file handle to close
1346  *
1347  * @return          0 on success, < 0 on error with errno set:
1348  *                  - EBADF  fd isn't a valid open file descriptor
1349  *                  - EINVAL smbc_init() failed or has not been called
1350  *
1351  * @see             smbc_open(), smbc_creat()
1352  */
1353 int smbc_close(int fd);
1354
1355
1356 /**@ingroup directory
1357  * Unlink (delete) a file or directory.
1358  *
1359  * @param furl      The smb url of the file to delete
1360  *
1361  * @return          0 on success, < 0 on error with errno set:
1362  *                  - EACCES or EPERM Write  access  to the directory 
1363  *                  containing pathname is not allowed or one  
1364  *                  of  the  directories in pathname did not allow
1365  *                  search (execute) permission
1366  *                  - ENOENT A directory component in pathname does
1367  *                  not exist
1368  *                  - EINVAL NULL was passed in the file param or
1369  *                    smbc_init not called.
1370  *                  - EACCES You do not have access to the file
1371  *                  - ENOMEM Insufficient kernel memory was available
1372  *
1373  * @see             smbc_rmdir()s
1374  *
1375  * @todo Are errno values complete and correct?
1376  */
1377 int smbc_unlink(const char *furl);
1378
1379
1380 /**@ingroup directory
1381  * Rename or move a file or directory.
1382  * 
1383  * @param ourl      The original smb url (source url) of file or 
1384  *                  directory to be moved
1385  * 
1386  * @param nurl      The new smb url (destination url) of the file
1387  *                  or directory after the move.  Currently nurl must
1388  *                  be on the same share as ourl.
1389  *
1390  * @return          0 on success, < 0 on error with errno set:
1391  *                  - EISDIR nurl is an existing directory, but ourl is
1392  *                  not a directory.
1393  *                  - EEXIST nurl is  a  non-empty directory, 
1394  *                  i.e., contains entries other than "." and ".."
1395  *                  - EINVAL The  new  url  contained  a path prefix 
1396  *                  of the old, or, more generally, an  attempt was
1397  *                  made  to make a directory a subdirectory of itself
1398  *                  or smbc_init not called.
1399  *                  - ENOTDIR A component used as a directory in ourl 
1400  *                  or nurl path is not, in fact, a directory.  Or, 
1401  *                  ourl  is a directory, and newpath exists but is not
1402  *                  a directory.
1403  *                  - EACCES or EPERM Write access to the directory 
1404  *                  containing ourl or nurl is not allowed for the 
1405  *                  process's effective uid,  or  one of the 
1406  *                  directories in ourl or nurl did not allow search
1407  *                  (execute) permission,  or ourl  was  a  directory
1408  *                  and did not allow write permission.
1409  *                  - ENOENT A  directory component in ourl or nurl 
1410  *                  does not exist.
1411  *                  - EXDEV Rename across shares not supported.
1412  *                  - ENOMEM Insufficient kernel memory was available.
1413  *                  - EEXIST The target file, nurl, already exists.
1414  *
1415  *
1416  * @todo Are we going to support copying when urls are not on the same
1417  *       share?  I say no... NOTE. I agree for the moment.
1418  *
1419  */
1420 int smbc_rename(const char *ourl, const char *nurl);
1421
1422
1423 /**@ingroup directory
1424  * Open a directory used to obtain directory entries.
1425  *
1426  * @param durl      The smb url of the directory to open
1427  *
1428  * @return          Valid directory handle. < 0 on error with errno set:
1429  *                  - EACCES Permission denied.
1430  *                  - EINVAL A NULL file/URL was passed, or the URL would
1431  *                  not parse, or was of incorrect form or smbc_init not
1432  *                  called.
1433  *                  - ENOENT durl does not exist, or name is an 
1434  *                  - ENOMEM Insufficient memory to complete the 
1435  *                  operation.                              
1436  *                  - ENOTDIR name is not a directory.
1437  *                  - EPERM the workgroup could not be found.
1438  *                  - ENODEV the workgroup or server could not be found.
1439  *
1440  * @see             smbc_getdents(), smbc_readdir(), smbc_closedir()
1441  *
1442  */
1443 int smbc_opendir(const char *durl);
1444
1445
1446 /**@ingroup directory
1447  * Close a directory handle opened by smbc_opendir().
1448  *
1449  * @param dh        Directory handle to close
1450  *
1451  * @return          0 on success, < 0 on error with errno set:
1452  *                  - EBADF dh is an invalid directory handle
1453  *
1454  * @see             smbc_opendir()
1455  */
1456 int smbc_closedir(int dh);
1457
1458
1459 /**@ingroup directory
1460  * Get multiple directory entries.
1461  *
1462  * smbc_getdents() reads as many dirent structures from the an open 
1463  * directory handle into a specified memory area as will fit.
1464  *
1465  * @param dh        Valid directory as returned by smbc_opendir()
1466  *
1467  * @param dirp      pointer to buffer that will receive the directory
1468  *                  entries.
1469  * 
1470  * @param count     The size of the dirp buffer in bytes
1471  *
1472  * @returns         If any dirents returned, return will indicate the
1473  *                  total size. If there were no more dirents available,
1474  *                  0 is returned. < 0 indicates an error.
1475  *                  - EBADF  Invalid directory handle
1476  *                  - EINVAL Result buffer is too small or smbc_init
1477  *                  not called.
1478  *                  - ENOENT No such directory.
1479  * @see             , smbc_dirent, smbc_readdir(), smbc_open()
1480  *
1481  * @todo Are errno values complete and correct?
1482  *
1483  * @todo Add example code so people know how to parse buffers.
1484  */
1485 int smbc_getdents(unsigned int dh, struct smbc_dirent *dirp, int count);
1486
1487
1488 /**@ingroup directory
1489  * Get a single directory entry.
1490  *
1491  * @param dh        Valid directory as returned by smbc_opendir()
1492  *
1493  * @return          A pointer to a smbc_dirent structure, or NULL if an
1494  *                  error occurs or end-of-directory is reached:
1495  *                  - EBADF Invalid directory handle
1496  *                  - EINVAL smbc_init() failed or has not been called
1497  *
1498  * @see             smbc_dirent, smbc_getdents(), smbc_open()
1499  */
1500 struct smbc_dirent* smbc_readdir(unsigned int dh);
1501
1502
1503 /**@ingroup directory
1504  * Get the current directory offset.
1505  *
1506  * smbc_telldir() may be used in conjunction with smbc_readdir() and
1507  * smbc_lseekdir().
1508  *
1509  * @param dh        Valid directory as returned by smbc_opendir()
1510  *
1511  * @return          The current location in the directory stream or -1
1512  *                  if an error occur.  The current location is not
1513  *                  an offset. Becuase of the implementation, it is a 
1514  *                  handle that allows the library to find the entry
1515  *                  later.
1516  *                  - EBADF dh is not a valid directory handle
1517  *                  - EINVAL smbc_init() failed or has not been called
1518  *                  - ENOTDIR if dh is not a directory
1519  *
1520  * @see             smbc_readdir()
1521  *
1522  */
1523 off_t smbc_telldir(int dh);
1524
1525
1526 /**@ingroup directory
1527  * lseek on directories.
1528  *
1529  * smbc_lseekdir() may be used in conjunction with smbc_readdir() and
1530  * smbc_telldir(). (rewind by smbc_lseekdir(fd, NULL))
1531  *
1532  * @param fd        Valid directory as returned by smbc_opendir()
1533  * 
1534  * @param offset    The offset (as returned by smbc_telldir). Can be
1535  *                  NULL, in which case we will rewind
1536  *
1537  * @return          0 on success, -1 on failure
1538  *                  - EBADF dh is not a valid directory handle
1539  *                  - ENOTDIR if dh is not a directory
1540  *                  - EINVAL offset did not refer to a valid dirent or
1541  *                    smbc_init not called.
1542  *
1543  * @see             smbc_telldir()
1544  *
1545  *
1546  * @todo In what does the reture and errno values mean?
1547  */
1548 int smbc_lseekdir(int fd, off_t offset);
1549
1550 /**@ingroup directory
1551  * Create a directory.
1552  *
1553  * @param durl      The url of the directory to create
1554  *
1555  * @param mode      Specifies  the  permissions to use. It is modified
1556  *                  by the process's umask in the usual way: the 
1557  *                  permissions of the created file are (mode & ~umask).
1558  * 
1559  * @return          0 on success, < 0 on error with errno set:
1560  *                  - EEXIST directory url already exists
1561  *                  - EACCES The parent directory does not allow write
1562  *                  permission to the process, or one of the directories
1563  *                  - ENOENT A directory component in pathname does not
1564  *                  exist.
1565  *                  - EINVAL NULL durl passed or smbc_init not called.
1566  *                  - ENOMEM Insufficient memory was available.
1567  *
1568  * @see             smbc_rmdir()
1569  *
1570  */
1571 int smbc_mkdir(const char *durl, mode_t mode);
1572
1573
1574 /**@ingroup directory
1575  * Remove a directory.
1576  * 
1577  * @param durl      The smb url of the directory to remove
1578  *
1579  * @return          0 on success, < 0 on error with errno set:
1580  *                  - EACCES or EPERM Write access to the directory
1581  *                  containing pathname was not allowed.
1582  *                  - EINVAL durl is NULL or smbc_init not called.
1583  *                  - ENOENT A directory component in pathname does not
1584  *                  exist.
1585  *                  - ENOTEMPTY directory contains entries.
1586  *                  - ENOMEM Insufficient kernel memory was available.
1587  *
1588  * @see             smbc_mkdir(), smbc_unlink() 
1589  *
1590  * @todo Are errno values complete and correct?
1591  */
1592 int smbc_rmdir(const char *durl);
1593
1594
1595 /**@ingroup attribute
1596  * Get information about a file or directory.
1597  *
1598  * @param url       The smb url to get information for
1599  *
1600  * @param st        pointer to a buffer that will be filled with 
1601  *                  standard Unix struct stat information.
1602  *
1603  * @return          0 on success, < 0 on error with errno set:
1604  *                  - ENOENT A component of the path file_name does not
1605  *                  exist.
1606  *                  - EINVAL a NULL url was passed or smbc_init not called.
1607  *                  - EACCES Permission denied.
1608  *                  - ENOMEM Out of memory
1609  *                  - ENOTDIR The target dir, url, is not a directory.
1610  *
1611  * @see             Unix stat()
1612  *
1613  */
1614 int smbc_stat(const char *url, struct stat *st);
1615
1616
1617 /**@ingroup attribute
1618  * Get file information via an file descriptor.
1619  * 
1620  * @param fd        Open file handle from smbc_open() or smbc_creat()
1621  *
1622  * @param st        pointer to a buffer that will be filled with 
1623  *                  standard Unix struct stat information.
1624  * 
1625  * @return          EBADF  filedes is bad.
1626  *                  - EACCES Permission denied.
1627  *                  - EBADF fd is not a valid file descriptor
1628  *                  - EINVAL Problems occurred in the underlying routines
1629  *                    or smbc_init not called.
1630  *                  - ENOMEM Out of memory
1631  *
1632  * @see             smbc_stat(), Unix stat()
1633  *
1634  */
1635 int smbc_fstat(int fd, struct stat *st);
1636
1637
1638 /**@ingroup attribute
1639  * Get file system information for a specified path.
1640  * 
1641  * @param url       The smb url to get information for
1642  *
1643  * @param st        pointer to a buffer that will be filled with 
1644  *                  standard Unix struct statvfs information.
1645  * 
1646  * @return          EBADF  filedes is bad.
1647  *                  - EACCES Permission denied.
1648  *                  - EBADF fd is not a valid file descriptor
1649  *                  - EINVAL Problems occurred in the underlying routines
1650  *                    or smbc_init not called.
1651  *                  - ENOMEM Out of memory
1652  *
1653  * @see             Unix fstatvfs()
1654  *
1655  */
1656 int
1657 smbc_statvfs(char *url,
1658              struct smbc_statvfs *st);
1659
1660 /**@ingroup attribute
1661  * Get file system information via an file descriptor.
1662  * 
1663  * @param fd        Open file handle from smbc_open(), smbc_creat(),
1664  *                  or smbc_opendir()
1665  *
1666  * @param st        pointer to a buffer that will be filled with 
1667  *                  standard Unix struct statvfs information.
1668  * 
1669  * @return          EBADF  filedes is bad.
1670  *                  - EACCES Permission denied.
1671  *                  - EBADF fd is not a valid file descriptor
1672  *                  - EINVAL Problems occurred in the underlying routines
1673  *                    or smbc_init not called.
1674  *                  - ENOMEM Out of memory
1675  *
1676  * @see             Unix fstatvfs()
1677  *
1678  */
1679 int
1680 smbc_fstatvfs(int fd,
1681               struct smbc_statvfs *st);
1682
1683
1684 /**@ingroup attribute
1685  * Truncate a file given a file descriptor
1686  * 
1687  * @param fd        Open file handle from smbc_open() or smbc_creat()
1688  *
1689  * @param size      size to truncate the file to
1690  * 
1691  * @return          EBADF  filedes is bad.
1692  *                  - EACCES Permission denied.
1693  *                  - EBADF fd is not a valid file descriptor
1694  *                  - EINVAL Problems occurred in the underlying routines
1695  *                    or smbc_init not called.
1696  *                  - ENOMEM Out of memory
1697  *
1698  * @see             , Unix ftruncate()
1699  *
1700  */
1701 int smbc_ftruncate(int fd, off_t size);
1702
1703
1704 /**@ingroup attribute
1705  * Change the permissions of a file.
1706  *
1707  * @param url       The smb url of the file or directory to change
1708  *                  permissions of
1709  * 
1710  * @param mode      The permissions to set:
1711  *                  - Put good explaination of permissions here!
1712  *
1713  * @return          0 on success, < 0 on error with errno set:
1714  *                  - EPERM  The effective UID does not match the owner
1715  *                  of the file, and is not zero
1716  *                  - ENOENT The file does not exist.
1717  *                  - ENOMEM Insufficient was available.
1718  *                  - ENOENT file or directory does not exist
1719  *
1720  * @todo Actually implement this fuction?
1721  *
1722  * @todo Are errno values complete and correct?
1723  */
1724 int smbc_chmod(const char *url, mode_t mode);
1725
1726 /**
1727  * @ingroup attribute
1728  * Change the last modification time on a file
1729  *
1730  * @param url       The smb url of the file or directory to change
1731  *                  the modification time of
1732  *
1733  * @param tbuf      An array of two timeval structures which contains,
1734  *                  respectively, the desired access and modification times.
1735  *                  NOTE: Only the tv_sec field off each timeval structure is
1736  *                  used.  The tv_usec (microseconds) portion is ignored.
1737  *
1738  * @return          0 on success, < 0 on error with errno set:
1739  *                  - EINVAL The client library is not properly initialized
1740  *                  - EPERM  Permission was denied.
1741  *
1742  */
1743 int smbc_utimes(const char *url, struct timeval *tbuf);
1744
1745 #ifdef HAVE_UTIME_H
1746 /**
1747  * @ingroup attribute
1748  * Change the last modification time on a file
1749  *
1750  * @param url       The smb url of the file or directory to change
1751  *                  the modification time of
1752  *
1753  * @param utbuf     A pointer to a utimebuf structure which contains the
1754  *                  desired access and modification times.
1755  *
1756  * @return          0 on success, < 0 on error with errno set:
1757  *                  - EINVAL The client library is not properly initialized
1758  *                  - ENOMEM No memory was available for internal needs
1759  *                  - EPERM  Permission was denied.
1760  *
1761  */
1762 int smbc_utime(const char *fname, struct utimbuf *utbuf);
1763 #endif
1764
1765 /**@ingroup attribute
1766  * Set extended attributes for a file.  This is used for modifying a file's
1767  * security descriptor (i.e. owner, group, and access control list)
1768  *
1769  * @param url       The smb url of the file or directory to set extended
1770  *                  attributes for.
1771  * 
1772  * @param name      The name of an attribute to be changed.  Names are of
1773  *                  one of the following forms:
1774  *
1775  *                     system.nt_sec_desc.<attribute name>
1776  *                     system.nt_sec_desc.*
1777  *                     system.nt_sec_desc.*+
1778  *
1779  *                  where <attribute name> is one of:
1780  *
1781  *                     revision
1782  *                     owner
1783  *                     owner+
1784  *                     group
1785  *                     group+
1786  *                     acl:<name or sid>
1787  *                     acl+:<name or sid>
1788  *
1789  *                  In the forms "system.nt_sec_desc.*" and
1790  *                  "system.nt_sec_desc.*+", the asterisk and plus signs are
1791  *                  literal, i.e. the string is provided exactly as shown, and
1792  *                  the value parameter should contain a complete security
1793  *                  descriptor with name:value pairs separated by tabs,
1794  *                  commas, or newlines (not spaces!).
1795  *
1796  *                  The plus sign ('+') indicates that SIDs should be mapped
1797  *                  to names.  Without the plus sign, SIDs are not mapped;
1798  *                  rather they are simply converted to a string format.
1799  *
1800  * @param value     The value to be assigned to the specified attribute name.
1801  *                  This buffer should contain only the attribute value if the
1802  *                  name was of the "system.nt_sec_desc.<attribute_name>"
1803  *                  form.  If the name was of the "system.nt_sec_desc.*" form
1804  *                  then a complete security descriptor, with name:value pairs
1805  *                  separated by tabs, commas, or newlines (not spaces!),
1806  *                  should be provided in this value buffer.  A complete
1807  *                  security descriptor will contain one or more entries
1808  *                  selected from the following:
1809  *
1810  *                    REVISION:<revision number>
1811  *                    OWNER:<sid or name>
1812  *                    GROUP:<sid or name>
1813  *                    ACL:<sid or name>:<type>/<flags>/<mask>
1814  *
1815  *                  The  revision of the ACL specifies the internal Windows NT
1816  *                  ACL revision for the security descriptor. If not specified
1817  *                  it defaults to  1.  Using values other than 1 may cause
1818  *                  strange behaviour.
1819  *
1820  *                  The owner and group specify the owner and group sids for
1821  *                  the object. If the attribute name (either '*+' with a
1822  *                  complete security descriptor, or individual 'owner+' or
1823  *                  'group+' attribute names) ended with a plus sign, the
1824  *                  specified name is resolved to a SID value, using the
1825  *                  server on which the file or directory resides.  Otherwise,
1826  *                  the value should be provided in SID-printable format as
1827  *                  S-1-x-y-z, and is used directly.  The <sid or name>
1828  *                  associated with the ACL: attribute should be provided
1829  *                  similarly.
1830  *
1831  * @param size      The number of the bytes of data in the value buffer
1832  *
1833  * @param flags     A bit-wise OR of zero or more of the following:
1834  *                    SMBC_XATTR_FLAG_CREATE -
1835  *                      fail if the named attribute already exists
1836  *                    SMBC_XATTR_FLAG_REPLACE -
1837  *                      fail if the attribute does not already exist
1838  *
1839  *                  If neither flag is specified, the specified attributes
1840  *                  will be added or replace existing attributes of the same
1841  *                  name, as necessary.
1842  *
1843  * @return          0 on success, < 0 on error with errno set:
1844  *                  - EINVAL  The client library is not properly initialized
1845  *                            or one of the parameters is not of a correct
1846  *                            form
1847  *                  - ENOMEM No memory was available for internal needs
1848  *                  - EEXIST  If the attribute already exists and the flag
1849  *                            SMBC_XATTR_FLAG_CREAT was specified
1850  *                  - ENOATTR If the attribute does not exist and the flag
1851  *                            SMBC_XATTR_FLAG_REPLACE was specified
1852  *                  - EPERM   Permission was denied.
1853  *                  - ENOTSUP The referenced file system does not support
1854  *                            extended attributes
1855  *
1856  * @note            Attribute names are compared in a case-insensitive
1857  *                  fashion.  All of the following are equivalent, although
1858  *                  the all-lower-case name is the preferred format:
1859  *                    system.nt_sec_desc.owner
1860  *                    SYSTEM.NT_SEC_DESC.OWNER
1861  *                    sYsTeM.nt_sEc_desc.owNER
1862  *
1863  */
1864 int smbc_setxattr(const char *url,
1865                   const char *name,
1866                   const void *value,
1867                   size_t size,
1868                   int flags);
1869
1870
1871 /**@ingroup attribute
1872  * Set extended attributes for a file.  This is used for modifying a file's
1873  * security descriptor (i.e. owner, group, and access control list).  The
1874  * POSIX function which this maps to would act on a symbolic link rather than
1875  * acting on what the symbolic link points to, but with no symbolic links in
1876  * SMB file systems, this function is functionally identical to
1877  * smbc_setxattr().
1878  *
1879  * @param url       The smb url of the file or directory to set extended
1880  *                  attributes for.
1881  * 
1882  * @param name      The name of an attribute to be changed.  Names are of
1883  *                  one of the following forms:
1884  *
1885  *                     system.nt_sec_desc.<attribute name>
1886  *                     system.nt_sec_desc.*
1887  *                     system.nt_sec_desc.*+
1888  *
1889  *                  where <attribute name> is one of:
1890  *
1891  *                     revision
1892  *                     owner
1893  *                     owner+
1894  *                     group
1895  *                     group+
1896  *                     acl:<name or sid>
1897  *                     acl+:<name or sid>
1898  *
1899  *                  In the forms "system.nt_sec_desc.*" and
1900  *                  "system.nt_sec_desc.*+", the asterisk and plus signs are
1901  *                  literal, i.e. the string is provided exactly as shown, and
1902  *                  the value parameter should contain a complete security
1903  *                  descriptor with name:value pairs separated by tabs,
1904  *                  commas, or newlines (not spaces!).
1905  *
1906  *                  The plus sign ('+') indicates that SIDs should be mapped
1907  *                  to names.  Without the plus sign, SIDs are not mapped;
1908  *                  rather they are simply converted to a string format.
1909  *
1910  * @param value     The value to be assigned to the specified attribute name.
1911  *                  This buffer should contain only the attribute value if the
1912  *                  name was of the "system.nt_sec_desc.<attribute_name>"
1913  *                  form.  If the name was of the "system.nt_sec_desc.*" form
1914  *                  then a complete security descriptor, with name:value pairs
1915  *                  separated by tabs, commas, or newlines (not spaces!),
1916  *                  should be provided in this value buffer.  A complete
1917  *                  security descriptor will contain one or more entries
1918  *                  selected from the following:
1919  *
1920  *                    REVISION:<revision number>
1921  *                    OWNER:<sid or name>
1922  *                    GROUP:<sid or name>
1923  *                    ACL:<sid or name>:<type>/<flags>/<mask>
1924  *
1925  *                  The  revision of the ACL specifies the internal Windows NT
1926  *                  ACL revision for the security descriptor. If not specified
1927  *                  it defaults to  1.  Using values other than 1 may cause
1928  *                  strange behaviour.
1929  *
1930  *                  The owner and group specify the owner and group sids for
1931  *                  the object. If the attribute name (either '*+' with a
1932  *                  complete security descriptor, or individual 'owner+' or
1933  *                  'group+' attribute names) ended with a plus sign, the
1934  *                  specified name is resolved to a SID value, using the
1935  *                  server on which the file or directory resides.  Otherwise,
1936  *                  the value should be provided in SID-printable format as
1937  *                  S-1-x-y-z, and is used directly.  The <sid or name>
1938  *                  associated with the ACL: attribute should be provided
1939  *                  similarly.
1940  *
1941  * @param size      The number of the bytes of data in the value buffer
1942  *
1943  * @param flags     A bit-wise OR of zero or more of the following:
1944  *                    SMBC_XATTR_FLAG_CREATE -
1945  *                      fail if the named attribute already exists
1946  *                    SMBC_XATTR_FLAG_REPLACE -
1947  *                      fail if the attribute does not already exist
1948  *
1949  *                  If neither flag is specified, the specified attributes
1950  *                  will be added or replace existing attributes of the same
1951  *                  name, as necessary.
1952  *
1953  * @return          0 on success, < 0 on error with errno set:
1954  *                  - EINVAL  The client library is not properly initialized
1955  *                            or one of the parameters is not of a correct
1956  *                            form
1957  *                  - ENOMEM No memory was available for internal needs
1958  *                  - EEXIST  If the attribute already exists and the flag
1959  *                            SMBC_XATTR_FLAG_CREAT was specified
1960  *                  - ENOATTR If the attribute does not exist and the flag
1961  *                            SMBC_XATTR_FLAG_REPLACE was specified
1962  *                  - EPERM   Permission was denied.
1963  *                  - ENOTSUP The referenced file system does not support
1964  *                            extended attributes
1965  *
1966  * @note            Attribute names are compared in a case-insensitive
1967  *                  fashion.  All of the following are equivalent, although
1968  *                  the all-lower-case name is the preferred format:
1969  *                    system.nt_sec_desc.owner
1970  *                    SYSTEM.NT_SEC_DESC.OWNER
1971  *                    sYsTeM.nt_sEc_desc.owNER
1972  *
1973  */
1974 int smbc_lsetxattr(const char *url,
1975                    const char *name,
1976                    const void *value,
1977                    size_t size,
1978                    int flags);
1979
1980
1981 /**@ingroup attribute
1982  * Set extended attributes for a file.  This is used for modifying a file's
1983  * security descriptor (i.e. owner, group, and access control list)
1984  *
1985  * @param fd        A file descriptor associated with an open file (as
1986  *                  previously returned by smbc_open(), to get extended
1987  *                  attributes for.
1988  * 
1989  * @param name      The name of an attribute to be changed.  Names are of
1990  *                  one of the following forms:
1991  *
1992  *                     system.nt_sec_desc.<attribute name>
1993  *                     system.nt_sec_desc.*
1994  *                     system.nt_sec_desc.*+
1995  *
1996  *                  where <attribute name> is one of:
1997  *
1998  *                     revision
1999  *                     owner
2000  *                     owner+
2001  *                     group
2002  *                     group+
2003  *                     acl:<name or sid>
2004  *                     acl+:<name or sid>
2005  *
2006  *                  In the forms "system.nt_sec_desc.*" and
2007  *                  "system.nt_sec_desc.*+", the asterisk and plus signs are
2008  *                  literal, i.e. the string is provided exactly as shown, and
2009  *                  the value parameter should contain a complete security
2010  *                  descriptor with name:value pairs separated by tabs,
2011  *                  commas, or newlines (not spaces!).
2012  *
2013  *                  The plus sign ('+') indicates that SIDs should be mapped
2014  *                  to names.  Without the plus sign, SIDs are not mapped;
2015  *                  rather they are simply converted to a string format.
2016  *
2017  * @param value     The value to be assigned to the specified attribute name.
2018  *                  This buffer should contain only the attribute value if the
2019  *                  name was of the "system.nt_sec_desc.<attribute_name>"
2020  *                  form.  If the name was of the "system.nt_sec_desc.*" form
2021  *                  then a complete security descriptor, with name:value pairs
2022  *                  separated by tabs, commas, or newlines (not spaces!),
2023  *                  should be provided in this value buffer.  A complete
2024  *                  security descriptor will contain one or more entries
2025  *                  selected from the following:
2026  *
2027  *                    REVISION:<revision number>
2028  *                    OWNER:<sid or name>
2029  *                    GROUP:<sid or name>
2030  *                    ACL:<sid or name>:<type>/<flags>/<mask>
2031  *
2032  *                  The  revision of the ACL specifies the internal Windows NT
2033  *                  ACL revision for the security descriptor. If not specified
2034  *                  it defaults to  1.  Using values other than 1 may cause
2035  *                  strange behaviour.
2036  *
2037  *                  The owner and group specify the owner and group sids for
2038  *                  the object. If the attribute name (either '*+' with a
2039  *                  complete security descriptor, or individual 'owner+' or
2040  *                  'group+' attribute names) ended with a plus sign, the
2041  *                  specified name is resolved to a SID value, using the
2042  *                  server on which the file or directory resides.  Otherwise,
2043  *                  the value should be provided in SID-printable format as
2044  *                  S-1-x-y-z, and is used directly.  The <sid or name>
2045  *                  associated with the ACL: attribute should be provided
2046  *                  similarly.
2047  *
2048  * @param size      The number of the bytes of data in the value buffer
2049  *
2050  * @param flags     A bit-wise OR of zero or more of the following:
2051  *                    SMBC_XATTR_FLAG_CREATE -
2052  *                      fail if the named attribute already exists
2053  *                    SMBC_XATTR_FLAG_REPLACE -
2054  *                      fail if the attribute does not already exist
2055  *
2056  *                  If neither flag is specified, the specified attributes
2057  *                  will be added or replace existing attributes of the same
2058  *                  name, as necessary.
2059  *
2060  * @return          0 on success, < 0 on error with errno set:
2061  *                  - EINVAL  The client library is not properly initialized
2062  *                            or one of the parameters is not of a correct
2063  *                            form
2064  *                  - ENOMEM No memory was available for internal needs
2065  *                  - EEXIST  If the attribute already exists and the flag
2066  *                            SMBC_XATTR_FLAG_CREAT was specified
2067  *                  - ENOATTR If the attribute does not exist and the flag
2068  *                            SMBC_XATTR_FLAG_REPLACE was specified
2069  *                  - EPERM   Permission was denied.
2070  *                  - ENOTSUP The referenced file system does not support
2071  *                            extended attributes
2072  *
2073  * @note            Attribute names are compared in a case-insensitive
2074  *                  fashion.  All of the following are equivalent, although
2075  *                  the all-lower-case name is the preferred format:
2076  *                    system.nt_sec_desc.owner
2077  *                    SYSTEM.NT_SEC_DESC.OWNER
2078  *                    sYsTeM.nt_sEc_desc.owNER
2079  *
2080  */
2081 int smbc_fsetxattr(int fd,
2082                    const char *name,
2083                    const void *value,
2084                    size_t size,
2085                    int flags);
2086
2087
2088 /**@ingroup attribute
2089  * Get extended attributes for a file.
2090  *
2091  * @param url       The smb url of the file or directory to get extended
2092  *                  attributes for.
2093  * 
2094  * @param name      The name of an attribute to be retrieved.  Names are of
2095  *                  one of the following forms:
2096  *
2097  *                     system.nt_sec_desc.<attribute name>
2098  *                     system.nt_sec_desc.*
2099  *                     system.nt_sec_desc.*+
2100  *
2101  *                  where <attribute name> is one of:
2102  *
2103  *                     revision
2104  *                     owner
2105  *                     owner+
2106  *                     group
2107  *                     group+
2108  *                     acl:<name or sid>
2109  *                     acl+:<name or sid>
2110  *
2111  *                  In the forms "system.nt_sec_desc.*" and
2112  *                  "system.nt_sec_desc.*+", the asterisk and plus signs are
2113  *                  literal, i.e. the string is provided exactly as shown, and
2114  *                  the value parameter will return a complete security
2115  *                  descriptor with name:value pairs separated by tabs,
2116  *                  commas, or newlines (not spaces!).
2117  *
2118  *                  The plus sign ('+') indicates that SIDs should be mapped
2119  *                  to names.  Without the plus sign, SIDs are not mapped;
2120  *                  rather they are simply converted to a string format.
2121  *
2122  * @param value     A pointer to a buffer in which the value of the specified
2123  *                  attribute will be placed (unless size is zero).
2124  *
2125  * @param size      The size of the buffer pointed to by value.  This parameter
2126  *                  may also be zero, in which case the size of the buffer
2127  *                  required to hold the attribute value will be returned,
2128  *                  but nothing will be placed into the value buffer.
2129  * 
2130  * @return          0 on success, < 0 on error with errno set:
2131  *                  - EINVAL  The client library is not properly initialized
2132  *                            or one of the parameters is not of a correct
2133  *                            form
2134  *                  - ENOMEM No memory was available for internal needs
2135  *                  - EEXIST  If the attribute already exists and the flag
2136  *                            SMBC_XATTR_FLAG_CREAT was specified
2137  *                  - ENOATTR If the attribute does not exist and the flag
2138  *                            SMBC_XATTR_FLAG_REPLACE was specified
2139  *                  - EPERM   Permission was denied.
2140  *                  - ENOTSUP The referenced file system does not support
2141  *                            extended attributes
2142  *
2143  */
2144 int smbc_getxattr(const char *url,
2145                   const char *name,
2146                   const void *value,
2147                   size_t size);
2148
2149
2150 /**@ingroup attribute
2151  * Get extended attributes for a file.  The POSIX function which this maps to
2152  * would act on a symbolic link rather than acting on what the symbolic link
2153  * points to, but with no symbolic links in SMB file systems, this function
2154  * is functionally identical to smbc_getxattr().
2155  *
2156  * @param url       The smb url of the file or directory to get extended
2157  *                  attributes for.
2158  * 
2159  * @param name      The name of an attribute to be retrieved.  Names are of
2160  *                  one of the following forms:
2161  *
2162  *                     system.nt_sec_desc.<attribute name>
2163  *                     system.nt_sec_desc.*
2164  *                     system.nt_sec_desc.*+
2165  *
2166  *                  where <attribute name> is one of:
2167  *
2168  *                     revision
2169  *                     owner
2170  *                     owner+
2171  *                     group
2172  *                     group+
2173  *                     acl:<name or sid>
2174  *                     acl+:<name or sid>
2175  *
2176  *                  In the forms "system.nt_sec_desc.*" and
2177  *                  "system.nt_sec_desc.*+", the asterisk and plus signs are
2178  *                  literal, i.e. the string is provided exactly as shown, and
2179  *                  the value parameter will return a complete security
2180  *                  descriptor with name:value pairs separated by tabs,
2181  *                  commas, or newlines (not spaces!).
2182  *
2183  *                  The plus sign ('+') indicates that SIDs should be mapped
2184  *                  to names.  Without the plus sign, SIDs are not mapped;
2185  *                  rather they are simply converted to a string format.
2186  *
2187  * @param value     A pointer to a buffer in which the value of the specified
2188  *                  attribute will be placed (unless size is zero).
2189  *
2190  * @param size      The size of the buffer pointed to by value.  This parameter
2191  *                  may also be zero, in which case the size of the buffer
2192  *                  required to hold the attribute value will be returned,
2193  *                  but nothing will be placed into the value buffer.
2194  * 
2195  * @return          0 on success, < 0 on error with errno set:
2196  *                  - EINVAL  The client library is not properly initialized
2197  *                            or one of the parameters is not of a correct
2198  *                            form
2199  *                  - ENOMEM No memory was available for internal needs
2200  *                  - EEXIST  If the attribute already exists and the flag
2201  *                            SMBC_XATTR_FLAG_CREAT was specified
2202  *                  - ENOATTR If the attribute does not exist and the flag
2203  *                            SMBC_XATTR_FLAG_REPLACE was specified
2204  *                  - EPERM   Permission was denied.
2205  *                  - ENOTSUP The referenced file system does not support
2206  *                            extended attributes
2207  *
2208  */
2209 int smbc_lgetxattr(const char *url,
2210                    const char *name,
2211                    const void *value,
2212                    size_t size);
2213
2214
2215 /**@ingroup attribute
2216  * Get extended attributes for a file.
2217  *
2218  * @param fd        A file descriptor associated with an open file (as
2219  *                  previously returned by smbc_open(), to get extended
2220  *                  attributes for.
2221  * 
2222  * @param name      The name of an attribute to be retrieved.  Names are of
2223  *                  one of the following forms:
2224  *
2225  *                     system.nt_sec_desc.<attribute name>
2226  *                     system.nt_sec_desc.*
2227  *                     system.nt_sec_desc.*+
2228  *
2229  *                  where <attribute name> is one of:
2230  *
2231  *                     revision
2232  *                     owner
2233  *                     owner+
2234  *                     group
2235  *                     group+
2236  *                     acl:<name or sid>
2237  *                     acl+:<name or sid>
2238  *
2239  *                  In the forms "system.nt_sec_desc.*" and
2240  *                  "system.nt_sec_desc.*+", the asterisk and plus signs are
2241  *                  literal, i.e. the string is provided exactly as shown, and
2242  *                  the value parameter will return a complete security
2243  *                  descriptor with name:value pairs separated by tabs,
2244  *                  commas, or newlines (not spaces!).
2245  *
2246  *                  The plus sign ('+') indicates that SIDs should be mapped
2247  *                  to names.  Without the plus sign, SIDs are not mapped;
2248  *                  rather they are simply converted to a string format.
2249  *
2250  * @param value     A pointer to a buffer in which the value of the specified
2251  *                  attribute will be placed (unless size is zero).
2252  *
2253  * @param size      The size of the buffer pointed to by value.  This parameter
2254  *                  may also be zero, in which case the size of the buffer
2255  *                  required to hold the attribute value will be returned,
2256  *                  but nothing will be placed into the value buffer.
2257  * 
2258  * @return          0 on success, < 0 on error with errno set:
2259  *                  - EINVAL  The client library is not properly initialized
2260  *                            or one of the parameters is not of a correct
2261  *                            form
2262  *                  - ENOMEM No memory was available for internal needs
2263  *                  - EEXIST  If the attribute already exists and the flag
2264  *                            SMBC_XATTR_FLAG_CREAT was specified
2265  *                  - ENOATTR If the attribute does not exist and the flag
2266  *                            SMBC_XATTR_FLAG_REPLACE was specified
2267  *                  - EPERM   Permission was denied.
2268  *                  - ENOTSUP The referenced file system does not support
2269  *                            extended attributes
2270  *
2271  */
2272 int smbc_fgetxattr(int fd,
2273                    const char *name,
2274                    const void *value,
2275                    size_t size);
2276
2277
2278 /**@ingroup attribute
2279  * Remove extended attributes for a file.  This is used for modifying a file's
2280  * security descriptor (i.e. owner, group, and access control list)
2281  *
2282  * @param url       The smb url of the file or directory to remove the extended
2283  *                  attributes for.
2284  * 
2285  * @param name      The name of an attribute to be removed.  Names are of
2286  *                  one of the following forms:
2287  *
2288  *                     system.nt_sec_desc.<attribute name>
2289  *                     system.nt_sec_desc.*
2290  *                     system.nt_sec_desc.*+
2291  *
2292  *                  where <attribute name> is one of:
2293  *
2294  *                     revision
2295  *                     owner
2296  *                     owner+
2297  *                     group
2298  *                     group+
2299  *                     acl:<name or sid>
2300  *                     acl+:<name or sid>
2301  *
2302  *                  In the forms "system.nt_sec_desc.*" and
2303  *                  "system.nt_sec_desc.*+", the asterisk and plus signs are
2304  *                  literal, i.e. the string is provided exactly as shown, and
2305  *                  the value parameter will return a complete security
2306  *                  descriptor with name:value pairs separated by tabs,
2307  *                  commas, or newlines (not spaces!).
2308  *
2309  *                  The plus sign ('+') indicates that SIDs should be mapped
2310  *                  to names.  Without the plus sign, SIDs are not mapped;
2311  *                  rather they are simply converted to a string format.
2312  *
2313  * @return          0 on success, < 0 on error with errno set:
2314  *                  - EINVAL The client library is not properly initialized
2315  *                  - ENOMEM No memory was available for internal needs
2316  *                  - EPERM  Permission was denied.
2317  *                  - ENOTSUP The referenced file system does not support
2318  *                            extended attributes
2319  *
2320  */
2321 int smbc_removexattr(const char *url,
2322                      const char *name);
2323
2324
2325 /**@ingroup attribute
2326  * Remove extended attributes for a file.  This is used for modifying a file's
2327  * security descriptor (i.e. owner, group, and access control list) The POSIX
2328  * function which this maps to would act on a symbolic link rather than acting
2329  * on what the symbolic link points to, but with no symbolic links in SMB file
2330  * systems, this function is functionally identical to smbc_removexattr().
2331  *
2332  * @param url       The smb url of the file or directory to remove the extended
2333  *                  attributes for.
2334  * 
2335  * @param name      The name of an attribute to be removed.  Names are of
2336  *                  one of the following forms:
2337  *
2338  *                     system.nt_sec_desc.<attribute name>
2339  *                     system.nt_sec_desc.*
2340  *                     system.nt_sec_desc.*+
2341  *
2342  *                  where <attribute name> is one of:
2343  *
2344  *                     revision
2345  *                     owner
2346  *                     owner+
2347  *                     group
2348  *                     group+
2349  *                     acl:<name or sid>
2350  *                     acl+:<name or sid>
2351  *
2352  *                  In the forms "system.nt_sec_desc.*" and
2353  *                  "system.nt_sec_desc.*+", the asterisk and plus signs are
2354  *                  literal, i.e. the string is provided exactly as shown, and
2355  *                  the value parameter will return a complete security
2356  *                  descriptor with name:value pairs separated by tabs,
2357  *                  commas, or newlines (not spaces!).
2358  *
2359  *                  The plus sign ('+') indicates that SIDs should be mapped
2360  *                  to names.  Without the plus sign, SIDs are not mapped;
2361  *                  rather they are simply converted to a string format.
2362  *
2363  * @return          0 on success, < 0 on error with errno set:
2364  *                  - EINVAL The client library is not properly initialized
2365  *                  - ENOMEM No memory was available for internal needs
2366  *                  - EPERM  Permission was denied.
2367  *                  - ENOTSUP The referenced file system does not support
2368  *                            extended attributes
2369  *
2370  */
2371 int smbc_lremovexattr(const char *url,
2372                       const char *name);
2373
2374
2375 /**@ingroup attribute
2376  * Remove extended attributes for a file.  This is used for modifying a file's
2377  * security descriptor (i.e. owner, group, and access control list)
2378  *
2379  * @param fd        A file descriptor associated with an open file (as
2380  *                  previously returned by smbc_open(), to get extended
2381  *                  attributes for.
2382  * 
2383  * @param name      The name of an attribute to be removed.  Names are of
2384  *                  one of the following forms:
2385  *
2386  *                     system.nt_sec_desc.<attribute name>
2387  *                     system.nt_sec_desc.*
2388  *                     system.nt_sec_desc.*+
2389  *
2390  *                  where <attribute name> is one of:
2391  *
2392  *                     revision
2393  *                     owner
2394  *                     owner+
2395  *                     group
2396  *                     group+
2397  *                     acl:<name or sid>
2398  *                     acl+:<name or sid>
2399  *
2400  *                  In the forms "system.nt_sec_desc.*" and
2401  *                  "system.nt_sec_desc.*+", the asterisk and plus signs are
2402  *                  literal, i.e. the string is provided exactly as shown, and
2403  *                  the value parameter will return a complete security
2404  *                  descriptor with name:value pairs separated by tabs,
2405  *                  commas, or newlines (not spaces!).
2406  *
2407  *                  The plus sign ('+') indicates that SIDs should be mapped
2408  *                  to names.  Without the plus sign, SIDs are not mapped;
2409  *                  rather they are simply converted to a string format.
2410  *
2411  * @return          0 on success, < 0 on error with errno set:
2412  *                  - EINVAL The client library is not properly initialized
2413  *                  - ENOMEM No memory was available for internal needs
2414  *                  - EPERM  Permission was denied.
2415  *                  - ENOTSUP The referenced file system does not support
2416  *                            extended attributes
2417  *
2418  */
2419 int smbc_fremovexattr(int fd,
2420                       const char *name);
2421
2422
2423 /**@ingroup attribute
2424  * List the supported extended attribute names associated with a file
2425  *
2426  * @param url       The smb url of the file or directory to list the extended
2427  *                  attributes for.
2428  *
2429  * @param list      A pointer to a buffer in which the list of attributes for
2430  *                  the specified file or directory will be placed (unless
2431  *                  size is zero).
2432  *
2433  * @param size      The size of the buffer pointed to by list.  This parameter
2434  *                  may also be zero, in which case the size of the buffer
2435  *                  required to hold all of the attribute names will be
2436  *                  returned, but nothing will be placed into the list buffer.
2437  * 
2438  * @return          0 on success, < 0 on error with errno set:
2439  *                  - EINVAL The client library is not properly initialized
2440  *                  - ENOMEM No memory was available for internal needs
2441  *                  - EPERM  Permission was denied.
2442  *                  - ENOTSUP The referenced file system does not support
2443  *                            extended attributes
2444  *
2445  * @note            This function always returns all attribute names supported
2446  *                  by NT file systems, regardless of whether the referenced
2447  *                  file system supports extended attributes (e.g. a Windows
2448  *                  2000 machine supports extended attributes if NTFS is used,
2449  *                  but not if FAT is used, and Windows 98 doesn't support
2450  *                  extended attributes at all.  Whether this is a feature or
2451  *                  a bug is yet to be decided.
2452  */
2453 int smbc_listxattr(const char *url,
2454                    char *list,
2455                    size_t size);
2456
2457 /**@ingroup attribute
2458  * List the supported extended attribute names associated with a file The
2459  * POSIX function which this maps to would act on a symbolic link rather than
2460  * acting on what the symbolic link points to, but with no symbolic links in
2461  * SMB file systems, this function is functionally identical to
2462  * smbc_listxattr().
2463  *
2464  * @param url       The smb url of the file or directory to list the extended
2465  *                  attributes for.
2466  *
2467  * @param list      A pointer to a buffer in which the list of attributes for
2468  *                  the specified file or directory will be placed (unless
2469  *                  size is zero).
2470  *
2471  * @param size      The size of the buffer pointed to by list.  This parameter
2472  *                  may also be zero, in which case the size of the buffer
2473  *                  required to hold all of the attribute names will be
2474  *                  returned, but nothing will be placed into the list buffer.
2475  * 
2476  * @return          0 on success, < 0 on error with errno set:
2477  *                  - EINVAL The client library is not properly initialized
2478  *                  - ENOMEM No memory was available for internal needs
2479  *                  - EPERM  Permission was denied.
2480  *                  - ENOTSUP The referenced file system does not support
2481  *                            extended attributes
2482  *
2483  * @note            This function always returns all attribute names supported
2484  *                  by NT file systems, regardless of wether the referenced
2485  *                  file system supports extended attributes (e.g. a Windows
2486  *                  2000 machine supports extended attributes if NTFS is used,
2487  *                  but not if FAT is used, and Windows 98 doesn't support
2488  *                  extended attributes at all.  Whether this is a feature or
2489  *                  a bug is yet to be decided.
2490  */
2491 int smbc_llistxattr(const char *url,
2492                     char *list,
2493                     size_t size);
2494
2495 /**@ingroup attribute
2496  * List the supported extended attribute names associated with a file
2497  *
2498  * @param fd        A file descriptor associated with an open file (as
2499  *                  previously returned by smbc_open(), to get extended
2500  *                  attributes for.
2501  * 
2502  * @param list      A pointer to a buffer in which the list of attributes for
2503  *                  the specified file or directory will be placed (unless
2504  *                  size is zero).
2505  *
2506  * @param size      The size of the buffer pointed to by list.  This parameter
2507  *                  may also be zero, in which case the size of the buffer
2508  *                  required to hold all of the attribute names will be
2509  *                  returned, but nothing will be placed into the list buffer.
2510  * 
2511  * @return          0 on success, < 0 on error with errno set:
2512  *                  - EINVAL The client library is not properly initialized
2513  *                  - ENOMEM No memory was available for internal needs
2514  *                  - EPERM  Permission was denied.
2515  *                  - ENOTSUP The referenced file system does not support
2516  *                            extended attributes
2517  *
2518  * @note            This function always returns all attribute names supported
2519  *                  by NT file systems, regardless of wether the referenced
2520  *                  file system supports extended attributes (e.g. a Windows
2521  *                  2000 machine supports extended attributes if NTFS is used,
2522  *                  but not if FAT is used, and Windows 98 doesn't support
2523  *                  extended attributes at all.  Whether this is a feature or
2524  *                  a bug is yet to be decided.
2525  */
2526 int smbc_flistxattr(int fd,
2527                     char *list,
2528                     size_t size);
2529
2530 /**@ingroup print
2531  * Print a file given the name in fname. It would be a URL ...
2532  * 
2533  * @param fname     The URL of a file on a remote SMB server that the
2534  *                  caller wants printed
2535  *
2536  * @param printq    The URL of the print share to print the file to.
2537  *
2538  * @return          0 on success, < 0 on error with errno set:         
2539  *
2540  *                  - EINVAL fname or printq was NULL or smbc_init not
2541  *                    not called.
2542  *                  and errors returned by smbc_open
2543  *
2544  */                                     
2545 int smbc_print_file(const char *fname, const char *printq);
2546
2547 /**@ingroup print
2548  * Open a print file that can be written to by other calls. This simply
2549  * does an smbc_open call after checking if there is a file name on the
2550  * URI. If not, a temporary name is added ...
2551  *
2552  * @param fname     The URL of the print share to print to?
2553  *
2554  * @returns         A file handle for the print file if successful.
2555  *                  Returns -1 if an error ocurred and errno has the values
2556  *                  - EINVAL fname was NULL or smbc_init not called.
2557  *                  - all errors returned by smbc_open
2558  *
2559  */
2560 int smbc_open_print_job(const char *fname);
2561
2562 /**@ingroup print
2563  * List the print jobs on a print share, for the moment, pass a callback 
2564  *
2565  * @param purl      The url of the print share to list the jobs of
2566  * 
2567  * @param fn        Callback function the receives printjob info
2568  * 
2569  * @return          0 on success, < 0 on error with errno set: 
2570  *                  - EINVAL fname was NULL or smbc_init not called
2571  *                  - EACCES ???
2572  */
2573 int smbc_list_print_jobs(const char *purl, smbc_list_print_job_fn fn);
2574
2575 /**@ingroup print
2576  * Delete a print job 
2577  *
2578  * @param purl      Url of the print share
2579  *
2580  * @param id        The id of the job to delete
2581  *
2582  * @return          0 on success, < 0 on error with errno set: 
2583  *                  - EINVAL fname was NULL or smbc_init not called
2584  *
2585  * @todo    what errno values are possible here?
2586  */
2587 int smbc_unlink_print_job(const char *purl, int id);
2588
2589 /**@ingroup callback
2590  * Remove a server from the cached server list it's unused.
2591  *
2592  * @param context    pointer to smb context
2593  *
2594  * @param srv        pointer to server to remove
2595  *
2596  * @return On success, 0 is returned. 1 is returned if the server could not
2597  *         be removed. Also useable outside libsmbclient.
2598  */
2599 int smbc_remove_unused_server(SMBCCTX * context, SMBCSRV * srv);
2600
2601 #ifdef __cplusplus
2602 }
2603 #endif
2604
2605 /**@ingroup directory
2606  * Convert strings of %xx to their single character equivalent.
2607  *
2608  * @param dest      A pointer to a buffer in which the resulting decoded
2609  *                  string should be placed.  This may be a pointer to the
2610  *                  same buffer as src_segment.
2611  * 
2612  * @param src       A pointer to the buffer containing the URL to be decoded.
2613  *                  Any %xx sequences herein are converted to their single
2614  *                  character equivalent.  Each 'x' must be a valid hexadecimal
2615  *                  digit, or that % sequence is left undecoded.
2616  *
2617  * @param max_dest_len
2618  *                  The size of the buffer pointed to by dest_segment.
2619  * 
2620  * @return          The number of % sequences which could not be converted
2621  *                  due to lack of two following hexadecimal digits.
2622  */
2623 #ifdef __cplusplus
2624 extern "C" {
2625 #endif
2626 int
2627 smbc_urldecode(char *dest, char * src, size_t max_dest_len);
2628 #ifdef __cplusplus
2629 }
2630 #endif
2631
2632
2633 /*
2634  * Convert any characters not specifically allowed in a URL into their %xx
2635  * equivalent.
2636  *
2637  * @param dest      A pointer to a buffer in which the resulting encoded
2638  *                  string should be placed.  Unlike smbc_urldecode(), this
2639  *                  must be a buffer unique from src.
2640  * 
2641  * @param src       A pointer to the buffer containing the string to be encoded.
2642  *                  Any character not specifically allowed in a URL is converted
2643  *                  into its hexadecimal value and encoded as %xx.
2644  *
2645  * @param max_dest_len
2646  *                  The size of the buffer pointed to by dest_segment.
2647  * 
2648  * @returns         The remaining buffer length.
2649  */
2650 #ifdef __cplusplus
2651 extern "C" {
2652 #endif
2653 int
2654 smbc_urlencode(char * dest, char * src, int max_dest_len);
2655 #ifdef __cplusplus
2656 }
2657 #endif
2658
2659
2660 /**@ingroup directory
2661  * Return the version of the linked Samba code, and thus the version of the
2662  * libsmbclient code.
2663  *
2664  * @return          The version string.
2665  */
2666 #ifdef __cplusplus
2667 extern "C" {
2668 #endif
2669 const char *
2670 smbc_version(void);
2671 #ifdef __cplusplus
2672 }
2673 #endif
2674
2675 /**@ingroup misc
2676  * Set the users credentials globally so they can be used for DFS
2677  * referrals. Probably best to use this function in the smbc_get_auth_data_fn
2678  * callback.
2679  *
2680  * @param workgroup      Workgroup of the user.
2681  *
2682  * @param user           Username of user.
2683  *
2684  * @param password       Password of user.
2685  *
2686  * @param use_kerberos   Whether to use Kerberos
2687  *
2688  * @param signing_state  One of these strings (all equivalents on same line):
2689  *                         "off", "no", "false"
2690  *                         "on", "yes", "true", "auto"
2691  *                         "force", "required", "forced"
2692  */
2693
2694 void
2695 smbc_set_credentials(char *workgroup,
2696                      char *user,
2697                      char *password,
2698                      smbc_bool use_kerberos,
2699                      char *signing_state);
2700
2701
2702 /**
2703  * @ingroup structure
2704  * Structure that contains a client context information 
2705  * This structure is known as SMBCCTX
2706  *
2707  * DO NOT DIRECTLY MANIPULATE THE CONTEXT STRUCTURE!  The data in the context
2708  * structure should all be considered private to the library.  It remains here
2709  * only for backward compatibility.
2710  *
2711  * See the comments herein for use of the setter and getter functions which
2712  * should now be used for manipulating these values.  New features, functions,
2713  * etc., are not added here but rather in _internal where they are not
2714  * directly visible to applications.  This makes it much easier to maintain
2715  * ABI compatibility.
2716  */
2717 struct _SMBCCTX
2718 {
2719         /**
2720          * debug level
2721          *
2722          * DEPRECATED:
2723          * Use smbc_getDebug() and smbc_setDebug()
2724          */
2725         int     debug DEPRECATED_SMBC_INTERFACE;
2726         
2727         /**
2728          * netbios name used for making connections
2729          *
2730          * DEPRECATED:
2731          * Use smbc_getNetbiosName() and smbc_setNetbiosName()
2732          */
2733         char * netbios_name DEPRECATED_SMBC_INTERFACE;
2734
2735         /**
2736          * workgroup name used for making connections
2737          *
2738          * DEPRECATED:
2739          * Use smbc_getWorkgroup() and smbc_setWorkgroup()
2740          */
2741         char * workgroup DEPRECATED_SMBC_INTERFACE;
2742
2743         /**
2744          * username used for making connections
2745          *
2746          * DEPRECATED:
2747          * Use smbc_getUser() and smbc_setUser()
2748          */
2749         char * user DEPRECATED_SMBC_INTERFACE;
2750
2751         /**
2752          * timeout used for waiting on connections / response data (in
2753          * milliseconds)
2754          *
2755          * DEPRECATED:
2756          * Use smbc_getTimeout() and smbc_setTimeout()
2757          */
2758         int timeout DEPRECATED_SMBC_INTERFACE;
2759
2760         /**
2761          * callable functions for files:
2762          * For usage and return values see the SMBC_* functions
2763          *
2764          * DEPRECATED:
2765          *
2766          * Use smbc_getFunction*() and smbc_setFunction*(), e.g.
2767          * smbc_getFunctionOpen(), smbc_setFunctionUnlink(), etc.
2768          */ 
2769         smbc_open_fn                    open DEPRECATED_SMBC_INTERFACE;
2770         smbc_creat_fn                   creat DEPRECATED_SMBC_INTERFACE;
2771         smbc_read_fn                    read DEPRECATED_SMBC_INTERFACE;
2772         smbc_write_fn                   write DEPRECATED_SMBC_INTERFACE;
2773         smbc_unlink_fn                  unlink DEPRECATED_SMBC_INTERFACE;
2774         smbc_rename_fn                  rename DEPRECATED_SMBC_INTERFACE;
2775         smbc_lseek_fn                   lseek DEPRECATED_SMBC_INTERFACE;
2776         smbc_stat_fn                    stat DEPRECATED_SMBC_INTERFACE;
2777         smbc_fstat_fn                   fstat DEPRECATED_SMBC_INTERFACE;
2778 #if 0 /* internal */
2779         smbc_ftruncate_fn               ftruncate_fn;
2780 #endif
2781         smbc_close_fn                   close_fn DEPRECATED_SMBC_INTERFACE;
2782         smbc_opendir_fn                 opendir DEPRECATED_SMBC_INTERFACE;
2783         smbc_closedir_fn                closedir DEPRECATED_SMBC_INTERFACE;
2784         smbc_readdir_fn                 readdir DEPRECATED_SMBC_INTERFACE;
2785         smbc_getdents_fn                getdents DEPRECATED_SMBC_INTERFACE;
2786         smbc_mkdir_fn                   mkdir DEPRECATED_SMBC_INTERFACE;
2787         smbc_rmdir_fn                   rmdir DEPRECATED_SMBC_INTERFACE;
2788         smbc_telldir_fn                 telldir DEPRECATED_SMBC_INTERFACE;
2789         smbc_lseekdir_fn                lseekdir DEPRECATED_SMBC_INTERFACE;
2790         smbc_fstatdir_fn                fstatdir DEPRECATED_SMBC_INTERFACE;
2791         smbc_chmod_fn                   chmod DEPRECATED_SMBC_INTERFACE;
2792         smbc_utimes_fn                  utimes DEPRECATED_SMBC_INTERFACE;
2793         smbc_setxattr_fn                setxattr DEPRECATED_SMBC_INTERFACE;
2794         smbc_getxattr_fn                getxattr DEPRECATED_SMBC_INTERFACE;
2795         smbc_removexattr_fn             removexattr DEPRECATED_SMBC_INTERFACE;
2796         smbc_listxattr_fn               listxattr DEPRECATED_SMBC_INTERFACE;
2797
2798         /* Printing-related functions */
2799         smbc_print_file_fn              print_file DEPRECATED_SMBC_INTERFACE;
2800         smbc_open_print_job_fn          open_print_job DEPRECATED_SMBC_INTERFACE;
2801         smbc_list_print_jobs_fn         list_print_jobs DEPRECATED_SMBC_INTERFACE;
2802         smbc_unlink_print_job_fn        unlink_print_job DEPRECATED_SMBC_INTERFACE;
2803
2804         /*
2805         ** Callbacks
2806         *
2807         * DEPRECATED:
2808         *
2809         * See the comment above each field, for the getter and setter
2810         * functions that should now be used.
2811         */
2812         struct _smbc_callbacks
2813         {
2814                 /**
2815                  * authentication function callback: called upon auth requests
2816                  *
2817                  * DEPRECATED:
2818                  * Use smbc_getFunctionAuthData(), smbc_setFunctionAuthData()
2819                  */
2820                 smbc_get_auth_data_fn auth_fn DEPRECATED_SMBC_INTERFACE;
2821                 
2822                 /**
2823                  * check if a server is still good
2824                  *
2825                  * DEPRECATED:
2826                  * Use smbc_getFunctionCheckServer(),
2827                  * smbc_setFunctionCheckServer()
2828                  */
2829                 smbc_check_server_fn check_server_fn DEPRECATED_SMBC_INTERFACE;
2830
2831                 /**
2832                  * remove a server if unused
2833                  *
2834                  * DEPRECATED:
2835                  * Use smbc_getFunctionRemoveUnusedServer(),
2836                  * smbc_setFunctionCheckServer()
2837                  */
2838                 smbc_remove_unused_server_fn remove_unused_server_fn DEPRECATED_SMBC_INTERFACE;
2839
2840                 /** Cache subsystem
2841                  *
2842                  * For an example cache system see
2843                  * samba/source/libsmb/libsmb_cache.c
2844                  *
2845                  * Cache subsystem * functions follow.
2846                  */
2847
2848                 /**
2849                  * server cache addition 
2850                  *
2851                  * DEPRECATED:
2852                  * Use smbc_getFunctionAddCachedServer(),
2853                  * smbc_setFunctionAddCachedServer()
2854                  */
2855                 smbc_add_cached_srv_fn add_cached_srv_fn DEPRECATED_SMBC_INTERFACE;
2856
2857                 /**
2858                  * server cache lookup 
2859                  *
2860                  * DEPRECATED:
2861                  * Use smbc_getFunctionGetCachedServer(),
2862                  * smbc_setFunctionGetCachedServer()
2863                  */
2864                 smbc_get_cached_srv_fn get_cached_srv_fn DEPRECATED_SMBC_INTERFACE;
2865
2866                 /**
2867                  * server cache removal
2868                  *
2869                  * DEPRECATED:
2870                  * Use smbc_getFunctionRemoveCachedServer(),
2871                  * smbc_setFunctionRemoveCachedServer()
2872                  */
2873                 smbc_remove_cached_srv_fn remove_cached_srv_fn DEPRECATED_SMBC_INTERFACE;
2874                 
2875                 /**
2876                  * server cache purging, try to remove all cached servers
2877                  * (disconnect)
2878                  *
2879                  * DEPRECATED:
2880                  * Use smbc_getFunctionPurgeCachedServers(),
2881                  * smbc_setFunctionPurgeCachedServers()
2882                  */
2883                 smbc_purge_cached_fn purge_cached_fn DEPRECATED_SMBC_INTERFACE;
2884         } callbacks;
2885
2886         /**
2887          * Space where the private data of the server cache used to be
2888          *
2889          * DEPRECATED:
2890          * Use smbc_getServerCacheData(), smbc_setServerCacheData()
2891          */
2892         void * reserved DEPRECATED_SMBC_INTERFACE;
2893
2894         /*
2895          * Very old configuration options.
2896          * 
2897          * DEPRECATED:
2898          * Use one of the following functions instead:
2899          *   smbc_setOptionUseKerberos()
2900          *   smbc_getOptionUseKerberos()
2901          *   smbc_setOptionFallbackAfterKerberos()
2902          *   smbc_getOptionFallbackAfterKerberos()
2903          *   smbc_setOptionNoAutoAnonymousLogin()
2904          *   smbc_getOptionNoAutoAnonymousLogin()
2905          */
2906         int flags DEPRECATED_SMBC_INTERFACE;
2907         
2908         /**
2909          * user options selections that apply to this session
2910          *
2911          * NEW OPTIONS ARE NOT ADDED HERE!
2912          *
2913          * DEPRECATED:
2914          * To set and retrieve options, use the smbc_setOption*() and
2915          * smbc_getOption*() functions.
2916          */
2917         struct _smbc_options {
2918                 int browse_max_lmb_count DEPRECATED_SMBC_INTERFACE;
2919                 int urlencode_readdir_entries DEPRECATED_SMBC_INTERFACE;
2920                 int one_share_per_server DEPRECATED_SMBC_INTERFACE;
2921         } options DEPRECATED_SMBC_INTERFACE;
2922         
2923         /** INTERNAL DATA
2924          * do _NOT_ touch this from your program !
2925          */
2926         struct SMBC_internal_data * internal;
2927 };
2928
2929
2930 #endif /* SMBCLIENT_H_INCLUDED */