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