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