libwbclient: don't link talloc.o into libwbclient.a
[ira/wip.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
9
10    
11   This program is free software; you can redistribute it and/or modify
12   it under the terms of the GNU General Public License as published by
13   the Free Software Foundation; either version 3 of the License, or
14   (at your option) any later version.
15    
16   This program is distributed in the hope that it will be useful,
17   but WITHOUT ANY WARRANTY; without even the implied warranty of
18   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
19   GNU General Public License for more details.
20    
21   You should have received a copy of the GNU General Public License
22   along with this program; if not, see <http://www.gnu.org/licenses/>.
23   =====================================================================*/
24
25 #ifndef SMBCLIENT_H_INCLUDED
26 #define SMBCLIENT_H_INCLUDED
27
28 #ifdef __cplusplus
29 extern "C" {
30 #endif
31
32 /*-------------------------------------------------------------------*/
33 /* The following are special comments to instruct DOXYGEN (automated 
34  * documentation tool:
35 */
36 /** \defgroup libsmbclient
37 */
38 /** \defgroup structure Data Structures Type and Constants
39 *   \ingroup libsmbclient
40 *   Data structures, types, and constants
41 */
42 /** \defgroup callback Callback function types
43 *   \ingroup libsmbclient
44 *   Callback functions
45 */
46 /** \defgroup file File Functions
47 *   \ingroup libsmbclient
48 *   Functions used to access individual file contents
49 */
50 /** \defgroup directory Directory Functions
51 *   \ingroup libsmbclient
52 *   Functions used to access directory entries
53 */
54 /** \defgroup attribute Attributes Functions
55 *   \ingroup libsmbclient
56 *   Functions used to view or change file and directory attributes
57 */
58 /** \defgroup print Print Functions
59 *   \ingroup libsmbclient
60 *   Functions used to access printing functionality
61 */
62 /** \defgroup misc Miscellaneous Functions
63 *   \ingroup libsmbclient
64 *   Functions that don't fit in to other categories
65 */
66 /*-------------------------------------------------------------------*/   
67
68 /* Make sure we have the following includes for now ... */
69 #include <sys/types.h>
70 #include <sys/stat.h>
71 #include <fcntl.h>
72 #include <utime.h>
73
74 #define SMBC_BASE_FD        10000 /* smallest file descriptor returned */
75
76 #define SMBC_WORKGROUP      1
77 #define SMBC_SERVER         2
78 #define SMBC_FILE_SHARE     3
79 #define SMBC_PRINTER_SHARE  4
80 #define SMBC_COMMS_SHARE    5
81 #define SMBC_IPC_SHARE      6
82 #define SMBC_DIR            7
83 #define SMBC_FILE           8
84 #define SMBC_LINK           9
85
86 /**@ingroup structure
87  * Structure that represents a directory entry.
88  *
89  */
90 struct smbc_dirent 
91 {
92         /** Type of entity.
93             SMBC_WORKGROUP=1,
94             SMBC_SERVER=2, 
95             SMBC_FILE_SHARE=3,
96             SMBC_PRINTER_SHARE=4,
97             SMBC_COMMS_SHARE=5,
98             SMBC_IPC_SHARE=6,
99             SMBC_DIR=7,
100             SMBC_FILE=8,
101             SMBC_LINK=9,*/ 
102         unsigned int smbc_type; 
103
104         /** Length of this smbc_dirent in bytes
105          */
106         unsigned int dirlen;
107         /** The length of the comment string in bytes (does not include
108          *  null terminator)
109          */
110         unsigned int commentlen;
111         /** Points to the null terminated comment string 
112          */
113         char *comment;
114         /** The length of the name string in bytes (does not include
115          *  null terminator)
116          */
117         unsigned int namelen;
118         /** Points to the null terminated name string 
119          */
120         char name[1];
121 };
122
123 /*
124  * Flags for smbc_setxattr()
125  *   Specify a bitwise OR of these, or 0 to add or replace as necessary
126  */
127 #define SMBC_XATTR_FLAG_CREATE       0x1 /* fail if attr already exists */
128 #define SMBC_XATTR_FLAG_REPLACE      0x2 /* fail if attr does not exist */
129
130
131 /*
132  * Mappings of the DOS mode bits, as returned by smbc_getxattr() when the
133  * attribute name "system.dos_attr.mode" (or "system.dos_attr.*" or
134  * "system.*") is specified.
135  */
136 #define SMBC_DOS_MODE_READONLY       0x01
137 #define SMBC_DOS_MODE_HIDDEN         0x02
138 #define SMBC_DOS_MODE_SYSTEM         0x04
139 #define SMBC_DOS_MODE_VOLUME_ID      0x08
140 #define SMBC_DOS_MODE_DIRECTORY      0x10
141 #define SMBC_DOS_MODE_ARCHIVE        0x20
142
143 /*
144  * Valid values for the option "open_share_mode", when calling
145  * smbc_option_set()
146  */
147 typedef enum smbc_share_mode
148 {
149     SMBC_SHAREMODE_DENY_DOS     = 0,
150     SMBC_SHAREMODE_DENY_ALL     = 1,
151     SMBC_SHAREMODE_DENY_WRITE   = 2,
152     SMBC_SHAREMODE_DENY_READ    = 3,
153     SMBC_SHAREMODE_DENY_NONE    = 4,
154     SMBC_SHAREMODE_DENY_FCB     = 7
155 } smbc_share_mode;
156
157
158 #ifndef ENOATTR
159 # define ENOATTR ENOENT        /* No such attribute */
160 #endif
161
162
163
164
165 /**@ingroup structure
166  * Structure that represents a print job.
167  *
168  */
169 #ifndef _CLIENT_H
170 struct print_job_info 
171 {
172         /** numeric ID of the print job
173          */
174         unsigned short id;
175     
176         /** represents print job priority (lower numbers mean higher priority)
177          */
178         unsigned short priority;
179     
180         /** Size of the print job
181          */
182         size_t size;
183     
184         /** Name of the user that owns the print job
185          */
186         char user[128];
187   
188         /** Name of the print job. This will have no name if an anonymous print
189          *  file was opened. Ie smb://server/printer
190          */
191         char name[128];
192
193         /** Time the print job was spooled
194          */
195         time_t t;
196 };
197 #endif /* _CLIENT_H */
198
199
200 /**@ingroup structure
201  * Server handle 
202  */
203 typedef struct _SMBCSRV  SMBCSRV;
204
205 /**@ingroup structure
206  * File or directory handle 
207  */
208 typedef struct _SMBCFILE SMBCFILE;
209
210 /**@ingroup structure
211  * File or directory handle 
212  */
213 typedef struct _SMBCCTX SMBCCTX;
214
215
216
217
218
219 /**@ingroup callback
220  * Authentication callback function type (traditional method)
221  * 
222  * Type for the the authentication function called by the library to
223  * obtain authentication credentals
224  *
225  * @param srv       Server being authenticated to
226  *
227  * @param shr       Share being authenticated to
228  *
229  * @param wg        Pointer to buffer containing a "hint" for the
230  *                  workgroup to be authenticated.  Should be filled in
231  *                  with the correct workgroup if the hint is wrong.
232  * 
233  * @param wglen     The size of the workgroup buffer in bytes
234  *
235  * @param un        Pointer to buffer containing a "hint" for the
236  *                  user name to be use for authentication. Should be
237  *                  filled in with the correct workgroup if the hint is
238  *                  wrong.
239  * 
240  * @param unlen     The size of the username buffer in bytes
241  *
242  * @param pw        Pointer to buffer containing to which password 
243  *                  copied
244  * 
245  * @param pwlen     The size of the password buffer in bytes
246  *           
247  */
248 typedef void (*smbc_get_auth_data_fn)(const char *srv, 
249                                       const char *shr,
250                                       char *wg, int wglen, 
251                                       char *un, int unlen,
252                                       char *pw, int pwlen);
253 /**@ingroup callback
254  * Authentication callback function type (method that includes context)
255  * 
256  * Type for the the authentication function called by the library to
257  * obtain authentication credentals
258  *
259  * @param c         Pointer to the smb context
260  *
261  * @param srv       Server being authenticated to
262  *
263  * @param shr       Share being authenticated to
264  *
265  * @param wg        Pointer to buffer containing a "hint" for the
266  *                  workgroup to be authenticated.  Should be filled in
267  *                  with the correct workgroup if the hint is wrong.
268  * 
269  * @param wglen     The size of the workgroup buffer in bytes
270  *
271  * @param un        Pointer to buffer containing a "hint" for the
272  *                  user name to be use for authentication. Should be
273  *                  filled in with the correct workgroup if the hint is
274  *                  wrong.
275  * 
276  * @param unlen     The size of the username buffer in bytes
277  *
278  * @param pw        Pointer to buffer containing to which password 
279  *                  copied
280  * 
281  * @param pwlen     The size of the password buffer in bytes
282  *           
283  */
284 typedef void (*smbc_get_auth_data_with_context_fn)(SMBCCTX *c,
285                                                    const char *srv, 
286                                                    const char *shr,
287                                                    char *wg, int wglen, 
288                                                    char *un, int unlen,
289                                                    char *pw, int pwlen);
290
291
292 /**@ingroup callback
293  * Print job info callback function type.
294  *
295  * @param i         pointer to print job information structure
296  *
297  */ 
298 typedef void (*smbc_list_print_job_fn)(struct print_job_info *i);
299                 
300
301 /**@ingroup callback
302  * Check if a server is still good
303  *
304  * @param c         pointer to smb context
305  *
306  * @param srv       pointer to server to check
307  *
308  * @return          0 when connection is good. 1 on error.
309  *
310  */ 
311 typedef int (*smbc_check_server_fn)(SMBCCTX * c, SMBCSRV *srv);
312
313 /**@ingroup callback
314  * Remove a server if unused
315  *
316  * @param c         pointer to smb context
317  *
318  * @param srv       pointer to server to remove
319  *
320  * @return          0 on success. 1 on failure.
321  *
322  */ 
323 typedef int (*smbc_remove_unused_server_fn)(SMBCCTX * c, SMBCSRV *srv);
324
325
326 /**@ingroup callback
327  * Add a server to the cache system
328  *
329  * @param c         pointer to smb context
330  *
331  * @param srv       pointer to server to add
332  *
333  * @param server    server name 
334  *
335  * @param share     share name
336  *
337  * @param workgroup workgroup used to connect
338  *
339  * @param username  username used to connect
340  *
341  * @return          0 on success. 1 on failure.
342  *
343  */ 
344 typedef int (*smbc_add_cached_srv_fn)   (SMBCCTX * c, SMBCSRV *srv, 
345                                     const char * server, const char * share,
346                                     const char * workgroup, const char * username);
347
348 /**@ingroup callback
349  * Look up a server in the cache system
350  *
351  * @param c         pointer to smb context
352  *
353  * @param server    server name to match
354  *
355  * @param share     share name to match
356  *
357  * @param workgroup workgroup to match
358  *
359  * @param username  username to match
360  *
361  * @return          pointer to SMBCSRV on success. NULL on failure.
362  *
363  */ 
364 typedef SMBCSRV * (*smbc_get_cached_srv_fn)   (SMBCCTX * c, const char * server,
365                                                const char * share, const char * workgroup,
366                                                const char * username);
367
368 /**@ingroup callback
369  * Check if a server is still good
370  *
371  * @param c         pointer to smb context
372  *
373  * @param srv       pointer to server to remove
374  *
375  * @return          0 when found and removed. 1 on failure.
376  *
377  */ 
378 typedef int (*smbc_remove_cached_srv_fn)(SMBCCTX * c, SMBCSRV *srv);
379
380
381 /**@ingroup callback
382  * Try to remove all servers from the cache system and disconnect
383  *
384  * @param c         pointer to smb context
385  *
386  * @return          0 when found and removed. 1 on failure.
387  *
388  */ 
389 typedef int (*smbc_purge_cached_fn)     (SMBCCTX * c);
390
391
392 /**@ingroup structure
393  * Structure that contains a client context information 
394  * This structure is know as SMBCCTX
395  */
396 struct _SMBCCTX {
397         /** debug level 
398          */
399         int     debug;
400         
401         /** netbios name used for making connections
402          */
403         char * netbios_name;
404
405         /** workgroup name used for making connections 
406          */
407         char * workgroup;
408
409         /** username used for making connections 
410          */
411         char * user;
412
413         /** timeout used for waiting on connections / response data (in milliseconds)
414          */
415         int timeout;
416
417         /** callable functions for files:
418          * For usage and return values see the smbc_* functions
419          */ 
420         SMBCFILE * (*open)    (SMBCCTX *c, const char *fname, int flags, mode_t mode);
421         SMBCFILE * (*creat)   (SMBCCTX *c, const char *path, mode_t mode);
422         ssize_t    (*read)    (SMBCCTX *c, SMBCFILE *file, void *buf, size_t count);
423         ssize_t    (*write)   (SMBCCTX *c, SMBCFILE *file, void *buf, size_t count);
424         int        (*unlink)  (SMBCCTX *c, const char *fname);
425         int        (*rename)  (SMBCCTX *ocontext, const char *oname, 
426                                SMBCCTX *ncontext, const char *nname);
427         off_t      (*lseek)   (SMBCCTX *c, SMBCFILE * file, off_t offset, int whence);
428         int        (*stat)    (SMBCCTX *c, const char *fname, struct stat *st);
429         int        (*fstat)   (SMBCCTX *c, SMBCFILE *file, struct stat *st);
430         int        (*close_fn) (SMBCCTX *c, SMBCFILE *file);
431
432         /** callable functions for dirs
433          */ 
434         SMBCFILE * (*opendir) (SMBCCTX *c, const char *fname);
435         int        (*closedir)(SMBCCTX *c, SMBCFILE *dir);
436         struct smbc_dirent * (*readdir)(SMBCCTX *c, SMBCFILE *dir);
437         int        (*getdents)(SMBCCTX *c, SMBCFILE *dir, 
438                                struct smbc_dirent *dirp, int count);
439         int        (*mkdir)   (SMBCCTX *c, const char *fname, mode_t mode);
440         int        (*rmdir)   (SMBCCTX *c, const char *fname);
441         off_t      (*telldir) (SMBCCTX *c, SMBCFILE *dir);
442         int        (*lseekdir)(SMBCCTX *c, SMBCFILE *dir, off_t offset);
443         int        (*fstatdir)(SMBCCTX *c, SMBCFILE *dir, struct stat *st);
444         int        (*chmod)(SMBCCTX *c, const char *fname, mode_t mode);
445         int        (*utimes)(SMBCCTX *c,
446                              const char *fname, struct timeval *tbuf);
447         int        (*setxattr)(SMBCCTX *context,
448                                const char *fname,
449                                const char *name,
450                                const void *value,
451                                size_t size,
452                                int flags);
453         int        (*getxattr)(SMBCCTX *context,
454                                const char *fname,
455                                const char *name,
456                                const void *value,
457                                size_t size);
458         int        (*removexattr)(SMBCCTX *context,
459                                   const char *fname,
460                                   const char *name);
461         int        (*listxattr)(SMBCCTX *context,
462                                 const char *fname,
463                                 char *list,
464                                 size_t size);
465
466         /** callable functions for printing
467          */ 
468         int        (*print_file)(SMBCCTX *c_file, const char *fname, 
469                                  SMBCCTX *c_print, const char *printq);
470         SMBCFILE * (*open_print_job)(SMBCCTX *c, const char *fname);
471         int        (*list_print_jobs)(SMBCCTX *c, const char *fname, smbc_list_print_job_fn fn);
472         int        (*unlink_print_job)(SMBCCTX *c, const char *fname, int id);
473
474
475         /*
476         ** Callbacks
477         * These callbacks _always_ have to be initialized because they will
478         * not be checked at dereference for increased speed.
479         */
480         struct _smbc_callbacks {
481                 /** authentication function callback: called upon auth requests
482                  */
483                 smbc_get_auth_data_fn auth_fn;
484                 
485                 /** check if a server is still good
486                  */
487                 smbc_check_server_fn check_server_fn;
488
489                 /** remove a server if unused
490                  */
491                 smbc_remove_unused_server_fn remove_unused_server_fn;
492
493                 /** Cache subsystem
494                  * For an example cache system see samba/source/libsmb/libsmb_cache.c
495                  * Cache subsystem functions follow.
496                  */
497
498                 /** server cache addition 
499                  */
500                 smbc_add_cached_srv_fn add_cached_srv_fn;
501
502                 /** server cache lookup 
503                  */
504                 smbc_get_cached_srv_fn get_cached_srv_fn;
505
506                 /** server cache removal
507                  */
508                 smbc_remove_cached_srv_fn remove_cached_srv_fn;
509                 
510                 /** server cache purging, try to remove all cached servers (disconnect)
511                  */
512                 smbc_purge_cached_fn purge_cached_fn;
513         } callbacks;
514
515
516         /** Space to store private data of the server cache.
517          */
518         struct smbc_server_cache * server_cache;
519
520         int flags;
521         
522         /** user options selections that apply to this session
523          */
524         struct _smbc_options {
525
526                 /*
527                  * From how many local master browsers should the list of
528                  * workgroups be retrieved?  It can take up to 12 minutes or
529                  * longer after a server becomes a local master browser, for
530                  * it to have the entire browse list (the list of
531                  * workgroups/domains) from an entire network.  Since a client
532                  * never knows which local master browser will be found first,
533                  * the one which is found first and used to retrieve a browse
534                  * list may have an incomplete or empty browse list.  By
535                  * requesting the browse list from multiple local master
536                  * browsers, a more complete list can be generated.  For small
537                  * networks (few workgroups), it is recommended that this
538                  * value be set to 0, causing the browse lists from all found
539                  * local master browsers to be retrieved and merged.  For
540                  * networks with many workgroups, a suitable value for this
541                  * variable is probably somewhere around 3. (Default: 3).
542                  */
543                 int browse_max_lmb_count;
544
545                 /*
546                  * There is a difference in the desired return strings from
547                  * smbc_readdir() depending upon whether the filenames are to
548                  * be displayed to the user, or whether they are to be
549                  * appended to the path name passed to smbc_opendir() to call
550                  * a further smbc_ function (e.g. open the file with
551                  * smbc_open()).  In the former case, the filename should be
552                  * in "human readable" form.  In the latter case, the smbc_
553                  * functions expect a URL which must be url-encoded.  Those
554                  * functions decode the URL.  If, for example, smbc_readdir()
555                  * returned a file name of "abc%20def.txt", passing a path
556                  * with this file name attached to smbc_open() would cause
557                  * smbc_open to attempt to open the file "abc def.txt" since
558                  * the %20 is decoded into a space.
559                  *
560                  * Set this option to True if the names returned by
561                  * smbc_readdir() should be url-encoded such that they can be
562                  * passed back to another smbc_ call.  Set it to False if the
563                  * names returned by smbc_readdir() are to be presented to the
564                  * user.
565                  *
566                  * For backwards compatibility, this option defaults to False.
567                  */
568                 int urlencode_readdir_entries;
569
570                 /*
571                  * Some Windows versions appear to have a limit to the number
572                  * of concurrent SESSIONs and/or TREE CONNECTions.  In
573                  * one-shot programs (i.e. the program runs and then quickly
574                  * ends, thereby shutting down all connections), it is
575                  * probably reasonable to establish a new connection for each
576                  * share.  In long-running applications, the limitation can be
577                  * avoided by using only a single connection to each server,
578                  * and issuing a new TREE CONNECT when the share is accessed.
579                  */
580                 int one_share_per_server;
581         } options;
582         
583         /** INTERNAL DATA
584          * do _NOT_ touch this from your program !
585          */
586         struct smbc_internal_data * internal;
587 };
588
589 /* Flags for SMBCCTX->flags */
590 #define SMB_CTX_FLAG_USE_KERBEROS (1 << 0)
591 #define SMB_CTX_FLAG_FALLBACK_AFTER_KERBEROS (1 << 1)
592 #define SMBCCTX_FLAG_NO_AUTO_ANONYMOUS_LOGON (1 << 2) /* don't try to do automatic anon login */
593
594 /**@ingroup misc
595  * Create a new SBMCCTX (a context).
596  *
597  * Must be called before the context is passed to smbc_context_init()
598  *
599  * @return          The given SMBCCTX pointer on success, NULL on error with errno set:
600  *                  - ENOMEM Out of memory
601  *
602  * @see             smbc_free_context(), smbc_init_context()
603  *
604  * @note            Do not forget to smbc_init_context() the returned SMBCCTX pointer !
605  */
606 SMBCCTX * smbc_new_context(void);
607
608 /**@ingroup misc
609  * Delete a SBMCCTX (a context) acquired from smbc_new_context().
610  *
611  * The context will be deleted if possible.
612  *
613  * @param context   A pointer to a SMBCCTX obtained from smbc_new_context()
614  *
615  * @param shutdown_ctx   If 1, all connections and files will be closed even if they are busy.
616  *
617  *
618  * @return          Returns 0 on succes. Returns 1 on failure with errno set:
619  *                  - EBUSY Server connections are still used, Files are open or cache 
620  *                          could not be purged
621  *                  - EBADF context == NULL
622  *
623  * @see             smbc_new_context()
624  *
625  * @note            It is advised to clean up all the contexts with shutdown_ctx set to 1
626  *                  just before exit()'ing. When shutdown_ctx is 0, this function can be
627  *                  use in periodical cleanup functions for example.
628  */
629 int smbc_free_context(SMBCCTX * context, int shutdown_ctx);
630
631
632 /**@ingroup misc
633  * Each time the context structure is changed, we have binary backward
634  * compatibility issues.  Instead of modifying the public portions of the
635  * context structure to add new options, instead, we put them in the internal
636  * portion of the context structure and provide a set function for these new
637  * options.
638  *
639  * @param context   A pointer to a SMBCCTX obtained from smbc_new_context()
640  *
641  * @param option_name
642  *                  The name of the option for which the value is to be set
643  *
644  * @param option_value
645  *                  The new value of the option being set
646  *
647  */
648 void
649 smbc_option_set(SMBCCTX *context,
650                 char *option_name,
651                 ... /* option_value */);
652 /*
653  * Retrieve the current value of an option
654  *
655  * @param context   A pointer to a SMBCCTX obtained from smbc_new_context()
656  *
657  * @param option_name
658  *                  The name of the option for which the value is to be
659  *                  retrieved
660  *
661  * @return          The value of the specified option.
662  */
663 void *
664 smbc_option_get(SMBCCTX *context,
665                 char *option_name);
666
667 /**@ingroup misc
668  * Initialize a SBMCCTX (a context).
669  *
670  * Must be called before using any SMBCCTX API function
671  *
672  * @param context   A pointer to a SMBCCTX obtained from smbc_new_context()
673  *
674  * @return          A pointer to the given SMBCCTX on success,
675  *                  NULL on error with errno set:
676  *                  - EBADF  NULL context given
677  *                  - ENOMEM Out of memory
678  *                  - ENOENT The smb.conf file would not load
679  *
680  * @see             smbc_new_context()
681  *
682  * @note            my_context = smbc_init_context(smbc_new_context())
683  *                  is perfectly safe, but it might leak memory on
684  *                  smbc_context_init() failure. Avoid this.
685  *                  You'll have to call smbc_free_context() yourself
686  *                  on failure.  
687  */
688
689 SMBCCTX * smbc_init_context(SMBCCTX * context);
690
691 /**@ingroup misc
692  * Initialize the samba client library.
693  *
694  * Must be called before using any of the smbclient API function
695  *  
696  * @param fn        The function that will be called to obtaion 
697  *                  authentication credentials.
698  *
699  * @param debug     Allows caller to set the debug level. Can be
700  *                  changed in smb.conf file. Allows caller to set
701  *                  debugging if no smb.conf.
702  *   
703  * @return          0 on success, < 0 on error with errno set:
704  *                  - ENOMEM Out of memory
705  *                  - ENOENT The smb.conf file would not load
706  *
707  */
708
709 int smbc_init(smbc_get_auth_data_fn fn, int debug);
710
711 /**@ingroup misc
712  * Set or retrieve the compatibility library's context pointer
713  *
714  * @param context   New context to use, or NULL.  If a new context is provided,
715  *                  it must have allocated with smbc_new_context() and
716  *                  initialized with smbc_init_context(), followed, optionally,
717  *                  by some manual changes to some of the non-internal fields.
718  *
719  * @return          The old context.
720  *
721  * @see             smbc_new_context(), smbc_init_context(), smbc_init()
722  *
723  * @note            This function may be called prior to smbc_init() to force
724  *                  use of the next context without any internal calls to
725  *                  smbc_new_context() or smbc_init_context().  It may also
726  *                  be called after smbc_init() has already called those two
727  *                  functions, to replace the existing context with a new one.
728  *                  Care should be taken, in this latter case, to ensure that
729  *                  the server cache and any data allocated by the
730  *                  authentication functions have been freed, if necessary.
731  */
732
733 SMBCCTX * smbc_set_context(SMBCCTX * new_context);
734
735 /**@ingroup file
736  * Open a file on an SMB server.
737  *
738  * @param furl      The smb url of the file to be opened. 
739  *
740  * @param flags     Is one of O_RDONLY, O_WRONLY or O_RDWR which 
741  *                  request opening  the  file  read-only,write-only
742  *                  or read/write. flags may also be bitwise-or'd with
743  *                  one or  more of  the following: 
744  *                  O_CREAT - If the file does not exist it will be 
745  *                  created.
746  *                  O_EXCL - When  used with O_CREAT, if the file 
747  *                  already exists it is an error and the open will 
748  *                  fail. 
749  *                  O_TRUNC - If the file already exists it will be
750  *                  truncated.
751  *                  O_APPEND The  file  is  opened  in  append mode 
752  *
753  * @param mode      mode specifies the permissions to use if a new 
754  *                  file is created.  It  is  modified  by  the 
755  *                  process's umask in the usual way: the permissions
756  *                  of the created file are (mode & ~umask) 
757  *
758  *                  Not currently use, but there for future use.
759  *                  We will map this to SYSTEM, HIDDEN, etc bits
760  *                  that reverses the mapping that smbc_fstat does.
761  *
762  * @return          Valid file handle, < 0 on error with errno set:
763  *                  - ENOMEM  Out of memory
764  *                  - EINVAL if an invalid parameter passed, like no 
765  *                  file, or smbc_init not called.
766  *                  - EEXIST  pathname already exists and O_CREAT and 
767  *                  O_EXCL were used.
768  *                  - EISDIR  pathname  refers  to  a  directory  and  
769  *                  the access requested involved writing.
770  *                  - EACCES  The requested access to the file is not 
771  *                  allowed 
772  *                  - ENODEV The requested share does not exist
773  *                  - ENOTDIR A file on the path is not a directory
774  *                  - ENOENT  A directory component in pathname does 
775  *                  not exist.
776  *
777  * @see             smbc_creat()
778  *
779  * @note            This call uses an underlying routine that may create
780  *                  a new connection to the server specified in the URL.
781  *                  If the credentials supplied in the URL, or via the
782  *                  auth_fn in the smbc_init call, fail, this call will
783  *                  try again with an empty username and password. This 
784  *                  often gets mapped to the guest account on some machines.
785  */
786
787 int smbc_open(const char *furl, int flags, mode_t mode);
788
789 /**@ingroup file
790  * Create a file on an SMB server.
791  *
792  * Same as calling smbc_open() with flags = O_CREAT|O_WRONLY|O_TRUNC 
793  *   
794  * @param furl      The smb url of the file to be created
795  *  
796  * @param mode      mode specifies the permissions to use if  a  new  
797  *                  file is created.  It  is  modified  by  the 
798  *                  process's umask in the usual way: the permissions
799  *                  of the created file are (mode & ~umask)
800  *
801  *                  NOTE, the above is not true. We are dealing with 
802  *                  an SMB server, which has no concept of a umask!
803  *      
804  * @return          Valid file handle, < 0 on error with errno set:
805  *                  - ENOMEM  Out of memory
806  *                  - EINVAL if an invalid parameter passed, like no 
807  *                  file, or smbc_init not called.
808  *                  - EEXIST  pathname already exists and O_CREAT and
809  *                  O_EXCL were used.
810  *                  - EISDIR  pathname  refers  to  a  directory  and
811  *                  the access requested involved writing.
812  *                  - EACCES  The requested access to the file is not
813  *                  allowed 
814  *                  - ENOENT  A directory component in pathname does 
815  *                  not exist.
816  *                  - ENODEV The requested share does not exist.
817  * @see             smbc_open()
818  *
819  */
820
821 int smbc_creat(const char *furl, mode_t mode);
822
823 /**@ingroup file
824  * Read from a file using an opened file handle.
825  *
826  * @param fd        Open file handle from smbc_open() or smbc_creat()
827  *
828  * @param buf       Pointer to buffer to recieve read data
829  *
830  * @param bufsize   Size of buf in bytes
831  *
832  * @return          Number of bytes read, < 0 on error with errno set:
833  *                  - EISDIR fd refers to a directory
834  *                  - EBADF  fd  is  not  a valid file descriptor or 
835  *                  is not open for reading.
836  *                  - EINVAL fd is attached to an object which is 
837  *                  unsuitable for reading, or no buffer passed or
838  *                  smbc_init not called.
839  *
840  * @see             smbc_open(), smbc_write()
841  *
842  */
843 ssize_t smbc_read(int fd, void *buf, size_t bufsize);
844
845
846 /**@ingroup file
847  * Write to a file using an opened file handle.
848  *
849  * @param fd        Open file handle from smbc_open() or smbc_creat()
850  *
851  * @param buf       Pointer to buffer to recieve read data
852  *
853  * @param bufsize   Size of buf in bytes
854  *
855  * @return          Number of bytes written, < 0 on error with errno set:
856  *                  - EISDIR fd refers to a directory.
857  *                  - EBADF  fd  is  not  a valid file descriptor or 
858  *                  is not open for reading.
859  *                  - EINVAL fd is attached to an object which is 
860  *                  unsuitable for reading, or no buffer passed or
861  *                  smbc_init not called.
862  *
863  * @see             smbc_open(), smbc_read()
864  *
865  */
866 ssize_t smbc_write(int fd, void *buf, size_t bufsize);
867
868
869 /**@ingroup file
870  * Seek to a specific location in a file.
871  *
872  * @param fd        Open file handle from smbc_open() or smbc_creat()
873  * 
874  * @param offset    Offset in bytes from whence
875  * 
876  * @param whence    A location in the file:
877  *                  - SEEK_SET The offset is set to offset bytes from
878  *                  the beginning of the file
879  *                  - SEEK_CUR The offset is set to current location 
880  *                  plus offset bytes.
881  *                  - SEEK_END The offset is set to the size of the 
882  *                  file plus offset bytes.
883  *
884  * @return          Upon successful completion, lseek returns the 
885  *                  resulting offset location as measured in bytes 
886  *                  from the beginning  of the file. Otherwise, a value
887  *                  of (off_t)-1 is returned and errno is set to 
888  *                  indicate the error:
889  *                  - EBADF  Fildes is not an open file descriptor.
890  *                  - EINVAL Whence is not a proper value or smbc_init
891  *                    not called.
892  *
893  * @todo Are all the whence values really supported?
894  * 
895  * @todo Are errno values complete and correct?
896  */
897 off_t smbc_lseek(int fd, off_t offset, int whence);
898
899
900 /**@ingroup file
901  * Close an open file handle.
902  *
903  * @param fd        The file handle to close
904  *
905  * @return          0 on success, < 0 on error with errno set:
906  *                  - EBADF  fd isn't a valid open file descriptor
907  *                  - EINVAL smbc_init() failed or has not been called
908  *
909  * @see             smbc_open(), smbc_creat()
910  */
911 int smbc_close(int fd);
912
913
914 /**@ingroup directory
915  * Unlink (delete) a file or directory.
916  *
917  * @param furl      The smb url of the file to delete
918  *
919  * @return          0 on success, < 0 on error with errno set:
920  *                  - EACCES or EPERM Write  access  to the directory 
921  *                  containing pathname is not allowed or one  
922  *                  of  the  directories in pathname did not allow
923  *                  search (execute) permission
924  *                  - ENOENT A directory component in pathname does
925  *                  not exist
926  *                  - EINVAL NULL was passed in the file param or
927  *                    smbc_init not called.
928  *                  - EACCES You do not have access to the file
929  *                  - ENOMEM Insufficient kernel memory was available
930  *
931  * @see             smbc_rmdir()s
932  *
933  * @todo Are errno values complete and correct?
934  */
935 int smbc_unlink(const char *furl);
936
937
938 /**@ingroup directory
939  * Rename or move a file or directory.
940  * 
941  * @param ourl      The original smb url (source url) of file or 
942  *                  directory to be moved
943  * 
944  * @param nurl      The new smb url (destination url) of the file
945  *                  or directory after the move.  Currently nurl must
946  *                  be on the same share as ourl.
947  *
948  * @return          0 on success, < 0 on error with errno set:
949  *                  - EISDIR nurl is an existing directory, but ourl is
950  *                  not a directory.
951  *                  - EEXIST nurl is  a  non-empty directory, 
952  *                  i.e., contains entries other than "." and ".."
953  *                  - EINVAL The  new  url  contained  a path prefix 
954  *                  of the old, or, more generally, an  attempt was
955  *                  made  to make a directory a subdirectory of itself
956  *                  or smbc_init not called.
957  *                  - ENOTDIR A component used as a directory in ourl 
958  *                  or nurl path is not, in fact, a directory.  Or, 
959  *                  ourl  is a directory, and newpath exists but is not
960  *                  a directory.
961  *                  - EACCES or EPERM Write access to the directory 
962  *                  containing ourl or nurl is not allowed for the 
963  *                  process's effective uid,  or  one of the 
964  *                  directories in ourl or nurl did not allow search
965  *                  (execute) permission,  or ourl  was  a  directory
966  *                  and did not allow write permission.
967  *                  - ENOENT A  directory component in ourl or nurl 
968  *                  does not exist.
969  *                  - EXDEV Rename across shares not supported.
970  *                  - ENOMEM Insufficient kernel memory was available.
971  *                  - EEXIST The target file, nurl, already exists.
972  *
973  *
974  * @todo Are we going to support copying when urls are not on the same
975  *       share?  I say no... NOTE. I agree for the moment.
976  *
977  */
978 int smbc_rename(const char *ourl, const char *nurl);
979
980
981 /**@ingroup directory
982  * Open a directory used to obtain directory entries.
983  *
984  * @param durl      The smb url of the directory to open
985  *
986  * @return          Valid directory handle. < 0 on error with errno set:
987  *                  - EACCES Permission denied.
988  *                  - EINVAL A NULL file/URL was passed, or the URL would
989  *                  not parse, or was of incorrect form or smbc_init not
990  *                  called.
991  *                  - ENOENT durl does not exist, or name is an 
992  *                  - ENOMEM Insufficient memory to complete the 
993  *                  operation.                              
994  *                  - ENOTDIR name is not a directory.
995  *                  - EPERM the workgroup could not be found.
996  *                  - ENODEV the workgroup or server could not be found.
997  *
998  * @see             smbc_getdents(), smbc_readdir(), smbc_closedir()
999  *
1000  */
1001 int smbc_opendir(const char *durl);
1002
1003
1004 /**@ingroup directory
1005  * Close a directory handle opened by smbc_opendir().
1006  *
1007  * @param dh        Directory handle to close
1008  *
1009  * @return          0 on success, < 0 on error with errno set:
1010  *                  - EBADF dh is an invalid directory handle
1011  *
1012  * @see             smbc_opendir()
1013  */
1014 int smbc_closedir(int dh);
1015
1016
1017 /**@ingroup directory
1018  * Get multiple directory entries.
1019  *
1020  * smbc_getdents() reads as many dirent structures from the an open 
1021  * directory handle into a specified memory area as will fit.
1022  *
1023  * @param dh        Valid directory as returned by smbc_opendir()
1024  *
1025  * @param dirp      pointer to buffer that will receive the directory
1026  *                  entries.
1027  * 
1028  * @param count     The size of the dirp buffer in bytes
1029  *
1030  * @returns         If any dirents returned, return will indicate the
1031  *                  total size. If there were no more dirents available,
1032  *                  0 is returned. < 0 indicates an error.
1033  *                  - EBADF  Invalid directory handle
1034  *                  - EINVAL Result buffer is too small or smbc_init
1035  *                  not called.
1036  *                  - ENOENT No such directory.
1037  * @see             , smbc_dirent, smbc_readdir(), smbc_open()
1038  *
1039  * @todo Are errno values complete and correct?
1040  *
1041  * @todo Add example code so people know how to parse buffers.
1042  */
1043 int smbc_getdents(unsigned int dh, struct smbc_dirent *dirp, int count);
1044
1045
1046 /**@ingroup directory
1047  * Get a single directory entry.
1048  *
1049  * @param dh        Valid directory as returned by smbc_opendir()
1050  *
1051  * @return          A pointer to a smbc_dirent structure, or NULL if an
1052  *                  error occurs or end-of-directory is reached:
1053  *                  - EBADF Invalid directory handle
1054  *                  - EINVAL smbc_init() failed or has not been called
1055  *
1056  * @see             smbc_dirent, smbc_getdents(), smbc_open()
1057  */
1058 struct smbc_dirent* smbc_readdir(unsigned int dh);
1059
1060
1061 /**@ingroup directory
1062  * Get the current directory offset.
1063  *
1064  * smbc_telldir() may be used in conjunction with smbc_readdir() and
1065  * smbc_lseekdir().
1066  *
1067  * @param dh        Valid directory as returned by smbc_opendir()
1068  *
1069  * @return          The current location in the directory stream or -1
1070  *                  if an error occur.  The current location is not
1071  *                  an offset. Becuase of the implementation, it is a 
1072  *                  handle that allows the library to find the entry
1073  *                  later.
1074  *                  - EBADF dh is not a valid directory handle
1075  *                  - EINVAL smbc_init() failed or has not been called
1076  *                  - ENOTDIR if dh is not a directory
1077  *
1078  * @see             smbc_readdir()
1079  *
1080  */
1081 off_t smbc_telldir(int dh);
1082
1083
1084 /**@ingroup directory
1085  * lseek on directories.
1086  *
1087  * smbc_lseekdir() may be used in conjunction with smbc_readdir() and
1088  * smbc_telldir(). (rewind by smbc_lseekdir(fd, NULL))
1089  *
1090  * @param fd        Valid directory as returned by smbc_opendir()
1091  * 
1092  * @param offset    The offset (as returned by smbc_telldir). Can be
1093  *                  NULL, in which case we will rewind
1094  *
1095  * @return          0 on success, -1 on failure
1096  *                  - EBADF dh is not a valid directory handle
1097  *                  - ENOTDIR if dh is not a directory
1098  *                  - EINVAL offset did not refer to a valid dirent or
1099  *                    smbc_init not called.
1100  *
1101  * @see             smbc_telldir()
1102  *
1103  *
1104  * @todo In what does the reture and errno values mean?
1105  */
1106 int smbc_lseekdir(int fd, off_t offset);
1107
1108 /**@ingroup directory
1109  * Create a directory.
1110  *
1111  * @param durl      The url of the directory to create
1112  *
1113  * @param mode      Specifies  the  permissions to use. It is modified
1114  *                  by the process's umask in the usual way: the 
1115  *                  permissions of the created file are (mode & ~umask).
1116  * 
1117  * @return          0 on success, < 0 on error with errno set:
1118  *                  - EEXIST directory url already exists
1119  *                  - EACCES The parent directory does not allow write
1120  *                  permission to the process, or one of the directories
1121  *                  - ENOENT A directory component in pathname does not
1122  *                  exist.
1123  *                  - EINVAL NULL durl passed or smbc_init not called.
1124  *                  - ENOMEM Insufficient memory was available.
1125  *
1126  * @see             smbc_rmdir()
1127  *
1128  */
1129 int smbc_mkdir(const char *durl, mode_t mode);
1130
1131
1132 /**@ingroup directory
1133  * Remove a directory.
1134  * 
1135  * @param durl      The smb url of the directory to remove
1136  *
1137  * @return          0 on success, < 0 on error with errno set:
1138  *                  - EACCES or EPERM Write access to the directory
1139  *                  containing pathname was not allowed.
1140  *                  - EINVAL durl is NULL or smbc_init not called.
1141  *                  - ENOENT A directory component in pathname does not
1142  *                  exist.
1143  *                  - ENOTEMPTY directory contains entries.
1144  *                  - ENOMEM Insufficient kernel memory was available.
1145  *
1146  * @see             smbc_mkdir(), smbc_unlink() 
1147  *
1148  * @todo Are errno values complete and correct?
1149  */
1150 int smbc_rmdir(const char *durl);
1151
1152
1153 /**@ingroup attribute
1154  * Get information about a file or directory.
1155  *
1156  * @param url       The smb url to get information for
1157  *
1158  * @param st        pointer to a buffer that will be filled with 
1159  *                  standard Unix struct stat information.
1160  *
1161  * @return          0 on success, < 0 on error with errno set:
1162  *                  - ENOENT A component of the path file_name does not
1163  *                  exist.
1164  *                  - EINVAL a NULL url was passed or smbc_init not called.
1165  *                  - EACCES Permission denied.
1166  *                  - ENOMEM Out of memory
1167  *                  - ENOTDIR The target dir, url, is not a directory.
1168  *
1169  * @see             Unix stat()
1170  *
1171  */
1172 int smbc_stat(const char *url, struct stat *st);
1173
1174
1175 /**@ingroup attribute
1176  * Get file information via an file descriptor.
1177  * 
1178  * @param fd        Open file handle from smbc_open() or smbc_creat()
1179  *
1180  * @param st        pointer to a buffer that will be filled with 
1181  *                  standard Unix struct stat information.
1182  * 
1183  * @return          EBADF  filedes is bad.
1184  *                  - EACCES Permission denied.
1185  *                  - EBADF fd is not a valid file descriptor
1186  *                  - EINVAL Problems occurred in the underlying routines
1187  *                    or smbc_init not called.
1188  *                  - ENOMEM Out of memory
1189  *
1190  * @see             smbc_stat(), Unix stat()
1191  *
1192  */
1193 int smbc_fstat(int fd, struct stat *st);
1194
1195
1196 /**@ingroup attribue
1197  * Change the ownership of a file or directory.
1198  *
1199  * @param url       The smb url of the file or directory to change 
1200  *                  ownership of.
1201  *
1202  * @param owner     I have no idea?
1203  *
1204  * @param group     I have not idea?
1205  *
1206  * @return          0 on success, < 0 on error with errno set:
1207  *                  - EPERM  The effective UID does not match the owner
1208  *                  of the file, and is not zero; or the owner or group
1209  *                  were specified incorrectly.
1210  *                  - ENOENT The file does not exist.
1211  *                  - ENOMEM Insufficient was available.
1212  *                  - ENOENT file or directory does not exist
1213  *
1214  * @todo Are we actually going to be able to implement this function
1215  *
1216  * @todo How do we abstract owner and group uid and gid?
1217  *
1218  */
1219 int smbc_chown(const char *url, uid_t owner, gid_t group);
1220
1221
1222 /**@ingroup attribute
1223  * Change the permissions of a file.
1224  *
1225  * @param url       The smb url of the file or directory to change
1226  *                  permissions of
1227  * 
1228  * @param mode      The permissions to set:
1229  *                  - Put good explaination of permissions here!
1230  *
1231  * @return          0 on success, < 0 on error with errno set:
1232  *                  - EPERM  The effective UID does not match the owner
1233  *                  of the file, and is not zero
1234  *                  - ENOENT The file does not exist.
1235  *                  - ENOMEM Insufficient was available.
1236  *                  - ENOENT file or directory does not exist
1237  *
1238  * @todo Actually implement this fuction?
1239  *
1240  * @todo Are errno values complete and correct?
1241  */
1242 int smbc_chmod(const char *url, mode_t mode);
1243
1244 /**
1245  * @ingroup attribute
1246  * Change the last modification time on a file
1247  *
1248  * @param url       The smb url of the file or directory to change
1249  *                  the modification time of
1250  *
1251  * @param tbuf      An array of two timeval structures which contains,
1252  *                  respectively, the desired access and modification times.
1253  *                  NOTE: Only the tv_sec field off each timeval structure is
1254  *                  used.  The tv_usec (microseconds) portion is ignored.
1255  *
1256  * @return          0 on success, < 0 on error with errno set:
1257  *                  - EINVAL The client library is not properly initialized
1258  *                  - EPERM  Permission was denied.
1259  *
1260  */
1261 int smbc_utimes(const char *url, struct timeval *tbuf);
1262
1263 #ifdef HAVE_UTIME_H
1264 /**
1265  * @ingroup attribute
1266  * Change the last modification time on a file
1267  *
1268  * @param url       The smb url of the file or directory to change
1269  *                  the modification time of
1270  *
1271  * @param utbuf     A pointer to a utimebuf structure which contains the
1272  *                  desired access and modification times.
1273  *
1274  * @return          0 on success, < 0 on error with errno set:
1275  *                  - EINVAL The client library is not properly initialized
1276  *                  - ENOMEM No memory was available for internal needs
1277  *                  - EPERM  Permission was denied.
1278  *
1279  */
1280 int smbc_utime(const char *fname, struct utimbuf *utbuf);
1281 #endif
1282
1283 /**@ingroup attribute
1284  * Set extended attributes for a file.  This is used for modifying a file's
1285  * security descriptor (i.e. owner, group, and access control list)
1286  *
1287  * @param url       The smb url of the file or directory to set extended
1288  *                  attributes for.
1289  * 
1290  * @param name      The name of an attribute to be changed.  Names are of
1291  *                  one of the following forms:
1292  *
1293  *                     system.nt_sec_desc.<attribute name>
1294  *                     system.nt_sec_desc.*
1295  *                     system.nt_sec_desc.*+
1296  *
1297  *                  where <attribute name> is one of:
1298  *
1299  *                     revision
1300  *                     owner
1301  *                     owner+
1302  *                     group
1303  *                     group+
1304  *                     acl:<name or sid>
1305  *                     acl+:<name or sid>
1306  *
1307  *                  In the forms "system.nt_sec_desc.*" and
1308  *                  "system.nt_sec_desc.*+", the asterisk and plus signs are
1309  *                  literal, i.e. the string is provided exactly as shown, and
1310  *                  the value parameter should contain a complete security
1311  *                  descriptor with name:value pairs separated by tabs,
1312  *                  commas, or newlines (not spaces!).
1313  *
1314  *                  The plus sign ('+') indicates that SIDs should be mapped
1315  *                  to names.  Without the plus sign, SIDs are not mapped;
1316  *                  rather they are simply converted to a string format.
1317  *
1318  * @param value     The value to be assigned to the specified attribute name.
1319  *                  This buffer should contain only the attribute value if the
1320  *                  name was of the "system.nt_sec_desc.<attribute_name>"
1321  *                  form.  If the name was of the "system.nt_sec_desc.*" form
1322  *                  then a complete security descriptor, with name:value pairs
1323  *                  separated by tabs, commas, or newlines (not spaces!),
1324  *                  should be provided in this value buffer.  A complete
1325  *                  security descriptor will contain one or more entries
1326  *                  selected from the following:
1327  *
1328  *                    REVISION:<revision number>
1329  *                    OWNER:<sid or name>
1330  *                    GROUP:<sid or name>
1331  *                    ACL:<sid or name>:<type>/<flags>/<mask>
1332  *
1333  *                  The  revision of the ACL specifies the internal Windows NT
1334  *                  ACL revision for the security descriptor. If not specified
1335  *                  it defaults to  1.  Using values other than 1 may cause
1336  *                  strange behaviour.
1337  *
1338  *                  The owner and group specify the owner and group sids for
1339  *                  the object. If the attribute name (either '*+' with a
1340  *                  complete security descriptor, or individual 'owner+' or
1341  *                  'group+' attribute names) ended with a plus sign, the
1342  *                  specified name is resolved to a SID value, using the
1343  *                  server on which the file or directory resides.  Otherwise,
1344  *                  the value should be provided in SID-printable format as
1345  *                  S-1-x-y-z, and is used directly.  The <sid or name>
1346  *                  associated with the ACL: attribute should be provided
1347  *                  similarly.
1348  *
1349  * @param size      The number of the bytes of data in the value buffer
1350  *
1351  * @param flags     A bit-wise OR of zero or more of the following:
1352  *                    SMBC_XATTR_FLAG_CREATE -
1353  *                      fail if the named attribute already exists
1354  *                    SMBC_XATTR_FLAG_REPLACE -
1355  *                      fail if the attribute does not already exist
1356  *
1357  *                  If neither flag is specified, the specified attributes
1358  *                  will be added or replace existing attributes of the same
1359  *                  name, as necessary.
1360  *
1361  * @return          0 on success, < 0 on error with errno set:
1362  *                  - EINVAL  The client library is not properly initialized
1363  *                            or one of the parameters is not of a correct
1364  *                            form
1365  *                  - ENOMEM No memory was available for internal needs
1366  *                  - EEXIST  If the attribute already exists and the flag
1367  *                            SMBC_XATTR_FLAG_CREAT was specified
1368  *                  - ENOATTR If the attribute does not exist and the flag
1369  *                            SMBC_XATTR_FLAG_REPLACE was specified
1370  *                  - EPERM   Permission was denied.
1371  *                  - ENOTSUP The referenced file system does not support
1372  *                            extended attributes
1373  *
1374  * @note            Attribute names are compared in a case-insensitive
1375  *                  fashion.  All of the following are equivalent, although
1376  *                  the all-lower-case name is the preferred format:
1377  *                    system.nt_sec_desc.owner
1378  *                    SYSTEM.NT_SEC_DESC.OWNER
1379  *                    sYsTeM.nt_sEc_desc.owNER
1380  *
1381  */
1382 int smbc_setxattr(const char *url,
1383                   const char *name,
1384                   const void *value,
1385                   size_t size,
1386                   int flags);
1387
1388
1389 /**@ingroup attribute
1390  * Set extended attributes for a file.  This is used for modifying a file's
1391  * security descriptor (i.e. owner, group, and access control list).  The
1392  * POSIX function which this maps to would act on a symbolic link rather than
1393  * acting on what the symbolic link points to, but with no symbolic links in
1394  * SMB file systems, this function is functionally identical to
1395  * smbc_setxattr().
1396  *
1397  * @param url       The smb url of the file or directory to set extended
1398  *                  attributes for.
1399  * 
1400  * @param name      The name of an attribute to be changed.  Names are of
1401  *                  one of the following forms:
1402  *
1403  *                     system.nt_sec_desc.<attribute name>
1404  *                     system.nt_sec_desc.*
1405  *                     system.nt_sec_desc.*+
1406  *
1407  *                  where <attribute name> is one of:
1408  *
1409  *                     revision
1410  *                     owner
1411  *                     owner+
1412  *                     group
1413  *                     group+
1414  *                     acl:<name or sid>
1415  *                     acl+:<name or sid>
1416  *
1417  *                  In the forms "system.nt_sec_desc.*" and
1418  *                  "system.nt_sec_desc.*+", the asterisk and plus signs are
1419  *                  literal, i.e. the string is provided exactly as shown, and
1420  *                  the value parameter should contain a complete security
1421  *                  descriptor with name:value pairs separated by tabs,
1422  *                  commas, or newlines (not spaces!).
1423  *
1424  *                  The plus sign ('+') indicates that SIDs should be mapped
1425  *                  to names.  Without the plus sign, SIDs are not mapped;
1426  *                  rather they are simply converted to a string format.
1427  *
1428  * @param value     The value to be assigned to the specified attribute name.
1429  *                  This buffer should contain only the attribute value if the
1430  *                  name was of the "system.nt_sec_desc.<attribute_name>"
1431  *                  form.  If the name was of the "system.nt_sec_desc.*" form
1432  *                  then a complete security descriptor, with name:value pairs
1433  *                  separated by tabs, commas, or newlines (not spaces!),
1434  *                  should be provided in this value buffer.  A complete
1435  *                  security descriptor will contain one or more entries
1436  *                  selected from the following:
1437  *
1438  *                    REVISION:<revision number>
1439  *                    OWNER:<sid or name>
1440  *                    GROUP:<sid or name>
1441  *                    ACL:<sid or name>:<type>/<flags>/<mask>
1442  *
1443  *                  The  revision of the ACL specifies the internal Windows NT
1444  *                  ACL revision for the security descriptor. If not specified
1445  *                  it defaults to  1.  Using values other than 1 may cause
1446  *                  strange behaviour.
1447  *
1448  *                  The owner and group specify the owner and group sids for
1449  *                  the object. If the attribute name (either '*+' with a
1450  *                  complete security descriptor, or individual 'owner+' or
1451  *                  'group+' attribute names) ended with a plus sign, the
1452  *                  specified name is resolved to a SID value, using the
1453  *                  server on which the file or directory resides.  Otherwise,
1454  *                  the value should be provided in SID-printable format as
1455  *                  S-1-x-y-z, and is used directly.  The <sid or name>
1456  *                  associated with the ACL: attribute should be provided
1457  *                  similarly.
1458  *
1459  * @param size      The number of the bytes of data in the value buffer
1460  *
1461  * @param flags     A bit-wise OR of zero or more of the following:
1462  *                    SMBC_XATTR_FLAG_CREATE -
1463  *                      fail if the named attribute already exists
1464  *                    SMBC_XATTR_FLAG_REPLACE -
1465  *                      fail if the attribute does not already exist
1466  *
1467  *                  If neither flag is specified, the specified attributes
1468  *                  will be added or replace existing attributes of the same
1469  *                  name, as necessary.
1470  *
1471  * @return          0 on success, < 0 on error with errno set:
1472  *                  - EINVAL  The client library is not properly initialized
1473  *                            or one of the parameters is not of a correct
1474  *                            form
1475  *                  - ENOMEM No memory was available for internal needs
1476  *                  - EEXIST  If the attribute already exists and the flag
1477  *                            SMBC_XATTR_FLAG_CREAT was specified
1478  *                  - ENOATTR If the attribute does not exist and the flag
1479  *                            SMBC_XATTR_FLAG_REPLACE was specified
1480  *                  - EPERM   Permission was denied.
1481  *                  - ENOTSUP The referenced file system does not support
1482  *                            extended attributes
1483  *
1484  * @note            Attribute names are compared in a case-insensitive
1485  *                  fashion.  All of the following are equivalent, although
1486  *                  the all-lower-case name is the preferred format:
1487  *                    system.nt_sec_desc.owner
1488  *                    SYSTEM.NT_SEC_DESC.OWNER
1489  *                    sYsTeM.nt_sEc_desc.owNER
1490  *
1491  */
1492 int smbc_lsetxattr(const char *url,
1493                    const char *name,
1494                    const void *value,
1495                    size_t size,
1496                    int flags);
1497
1498
1499 /**@ingroup attribute
1500  * Set extended attributes for a file.  This is used for modifying a file's
1501  * security descriptor (i.e. owner, group, and access control list)
1502  *
1503  * @param fd        A file descriptor associated with an open file (as
1504  *                  previously returned by smbc_open(), to get extended
1505  *                  attributes for.
1506  * 
1507  * @param name      The name of an attribute to be changed.  Names are of
1508  *                  one of the following forms:
1509  *
1510  *                     system.nt_sec_desc.<attribute name>
1511  *                     system.nt_sec_desc.*
1512  *                     system.nt_sec_desc.*+
1513  *
1514  *                  where <attribute name> is one of:
1515  *
1516  *                     revision
1517  *                     owner
1518  *                     owner+
1519  *                     group
1520  *                     group+
1521  *                     acl:<name or sid>
1522  *                     acl+:<name or sid>
1523  *
1524  *                  In the forms "system.nt_sec_desc.*" and
1525  *                  "system.nt_sec_desc.*+", the asterisk and plus signs are
1526  *                  literal, i.e. the string is provided exactly as shown, and
1527  *                  the value parameter should contain a complete security
1528  *                  descriptor with name:value pairs separated by tabs,
1529  *                  commas, or newlines (not spaces!).
1530  *
1531  *                  The plus sign ('+') indicates that SIDs should be mapped
1532  *                  to names.  Without the plus sign, SIDs are not mapped;
1533  *                  rather they are simply converted to a string format.
1534  *
1535  * @param value     The value to be assigned to the specified attribute name.
1536  *                  This buffer should contain only the attribute value if the
1537  *                  name was of the "system.nt_sec_desc.<attribute_name>"
1538  *                  form.  If the name was of the "system.nt_sec_desc.*" form
1539  *                  then a complete security descriptor, with name:value pairs
1540  *                  separated by tabs, commas, or newlines (not spaces!),
1541  *                  should be provided in this value buffer.  A complete
1542  *                  security descriptor will contain one or more entries
1543  *                  selected from the following:
1544  *
1545  *                    REVISION:<revision number>
1546  *                    OWNER:<sid or name>
1547  *                    GROUP:<sid or name>
1548  *                    ACL:<sid or name>:<type>/<flags>/<mask>
1549  *
1550  *                  The  revision of the ACL specifies the internal Windows NT
1551  *                  ACL revision for the security descriptor. If not specified
1552  *                  it defaults to  1.  Using values other than 1 may cause
1553  *                  strange behaviour.
1554  *
1555  *                  The owner and group specify the owner and group sids for
1556  *                  the object. If the attribute name (either '*+' with a
1557  *                  complete security descriptor, or individual 'owner+' or
1558  *                  'group+' attribute names) ended with a plus sign, the
1559  *                  specified name is resolved to a SID value, using the
1560  *                  server on which the file or directory resides.  Otherwise,
1561  *                  the value should be provided in SID-printable format as
1562  *                  S-1-x-y-z, and is used directly.  The <sid or name>
1563  *                  associated with the ACL: attribute should be provided
1564  *                  similarly.
1565  *
1566  * @param size      The number of the bytes of data in the value buffer
1567  *
1568  * @param flags     A bit-wise OR of zero or more of the following:
1569  *                    SMBC_XATTR_FLAG_CREATE -
1570  *                      fail if the named attribute already exists
1571  *                    SMBC_XATTR_FLAG_REPLACE -
1572  *                      fail if the attribute does not already exist
1573  *
1574  *                  If neither flag is specified, the specified attributes
1575  *                  will be added or replace existing attributes of the same
1576  *                  name, as necessary.
1577  *
1578  * @return          0 on success, < 0 on error with errno set:
1579  *                  - EINVAL  The client library is not properly initialized
1580  *                            or one of the parameters is not of a correct
1581  *                            form
1582  *                  - ENOMEM No memory was available for internal needs
1583  *                  - EEXIST  If the attribute already exists and the flag
1584  *                            SMBC_XATTR_FLAG_CREAT was specified
1585  *                  - ENOATTR If the attribute does not exist and the flag
1586  *                            SMBC_XATTR_FLAG_REPLACE was specified
1587  *                  - EPERM   Permission was denied.
1588  *                  - ENOTSUP The referenced file system does not support
1589  *                            extended attributes
1590  *
1591  * @note            Attribute names are compared in a case-insensitive
1592  *                  fashion.  All of the following are equivalent, although
1593  *                  the all-lower-case name is the preferred format:
1594  *                    system.nt_sec_desc.owner
1595  *                    SYSTEM.NT_SEC_DESC.OWNER
1596  *                    sYsTeM.nt_sEc_desc.owNER
1597  *
1598  */
1599 int smbc_fsetxattr(int fd,
1600                    const char *name,
1601                    const void *value,
1602                    size_t size,
1603                    int flags);
1604
1605
1606 /**@ingroup attribute
1607  * Get extended attributes for a file.
1608  *
1609  * @param url       The smb url of the file or directory to get extended
1610  *                  attributes for.
1611  * 
1612  * @param name      The name of an attribute to be retrieved.  Names are of
1613  *                  one of the following forms:
1614  *
1615  *                     system.nt_sec_desc.<attribute name>
1616  *                     system.nt_sec_desc.*
1617  *                     system.nt_sec_desc.*+
1618  *
1619  *                  where <attribute name> is one of:
1620  *
1621  *                     revision
1622  *                     owner
1623  *                     owner+
1624  *                     group
1625  *                     group+
1626  *                     acl:<name or sid>
1627  *                     acl+:<name or sid>
1628  *
1629  *                  In the forms "system.nt_sec_desc.*" and
1630  *                  "system.nt_sec_desc.*+", the asterisk and plus signs are
1631  *                  literal, i.e. the string is provided exactly as shown, and
1632  *                  the value parameter will return a complete security
1633  *                  descriptor with name:value pairs separated by tabs,
1634  *                  commas, or newlines (not spaces!).
1635  *
1636  *                  The plus sign ('+') indicates that SIDs should be mapped
1637  *                  to names.  Without the plus sign, SIDs are not mapped;
1638  *                  rather they are simply converted to a string format.
1639  *
1640  * @param value     A pointer to a buffer in which the value of the specified
1641  *                  attribute will be placed (unless size is zero).
1642  *
1643  * @param size      The size of the buffer pointed to by value.  This parameter
1644  *                  may also be zero, in which case the size of the buffer
1645  *                  required to hold the attribute value will be returned,
1646  *                  but nothing will be placed into the value buffer.
1647  * 
1648  * @return          0 on success, < 0 on error with errno set:
1649  *                  - EINVAL  The client library is not properly initialized
1650  *                            or one of the parameters is not of a correct
1651  *                            form
1652  *                  - ENOMEM No memory was available for internal needs
1653  *                  - EEXIST  If the attribute already exists and the flag
1654  *                            SMBC_XATTR_FLAG_CREAT was specified
1655  *                  - ENOATTR If the attribute does not exist and the flag
1656  *                            SMBC_XATTR_FLAG_REPLACE was specified
1657  *                  - EPERM   Permission was denied.
1658  *                  - ENOTSUP The referenced file system does not support
1659  *                            extended attributes
1660  *
1661  */
1662 int smbc_getxattr(const char *url,
1663                   const char *name,
1664                   const void *value,
1665                   size_t size);
1666
1667
1668 /**@ingroup attribute
1669  * Get extended attributes for a file.  The POSIX function which this maps to
1670  * would act on a symbolic link rather than acting on what the symbolic link
1671  * points to, but with no symbolic links in SMB file systems, this function
1672  * is functionally identical to smbc_getxattr().
1673  *
1674  * @param url       The smb url of the file or directory to get extended
1675  *                  attributes for.
1676  * 
1677  * @param name      The name of an attribute to be retrieved.  Names are of
1678  *                  one of the following forms:
1679  *
1680  *                     system.nt_sec_desc.<attribute name>
1681  *                     system.nt_sec_desc.*
1682  *                     system.nt_sec_desc.*+
1683  *
1684  *                  where <attribute name> is one of:
1685  *
1686  *                     revision
1687  *                     owner
1688  *                     owner+
1689  *                     group
1690  *                     group+
1691  *                     acl:<name or sid>
1692  *                     acl+:<name or sid>
1693  *
1694  *                  In the forms "system.nt_sec_desc.*" and
1695  *                  "system.nt_sec_desc.*+", the asterisk and plus signs are
1696  *                  literal, i.e. the string is provided exactly as shown, and
1697  *                  the value parameter will return a complete security
1698  *                  descriptor with name:value pairs separated by tabs,
1699  *                  commas, or newlines (not spaces!).
1700  *
1701  *                  The plus sign ('+') indicates that SIDs should be mapped
1702  *                  to names.  Without the plus sign, SIDs are not mapped;
1703  *                  rather they are simply converted to a string format.
1704  *
1705  * @param value     A pointer to a buffer in which the value of the specified
1706  *                  attribute will be placed (unless size is zero).
1707  *
1708  * @param size      The size of the buffer pointed to by value.  This parameter
1709  *                  may also be zero, in which case the size of the buffer
1710  *                  required to hold the attribute value will be returned,
1711  *                  but nothing will be placed into the value buffer.
1712  * 
1713  * @return          0 on success, < 0 on error with errno set:
1714  *                  - EINVAL  The client library is not properly initialized
1715  *                            or one of the parameters is not of a correct
1716  *                            form
1717  *                  - ENOMEM No memory was available for internal needs
1718  *                  - EEXIST  If the attribute already exists and the flag
1719  *                            SMBC_XATTR_FLAG_CREAT was specified
1720  *                  - ENOATTR If the attribute does not exist and the flag
1721  *                            SMBC_XATTR_FLAG_REPLACE was specified
1722  *                  - EPERM   Permission was denied.
1723  *                  - ENOTSUP The referenced file system does not support
1724  *                            extended attributes
1725  *
1726  */
1727 int smbc_lgetxattr(const char *url,
1728                    const char *name,
1729                    const void *value,
1730                    size_t size);
1731
1732
1733 /**@ingroup attribute
1734  * Get extended attributes for a file.
1735  *
1736  * @param fd        A file descriptor associated with an open file (as
1737  *                  previously returned by smbc_open(), to get extended
1738  *                  attributes for.
1739  * 
1740  * @param name      The name of an attribute to be retrieved.  Names are of
1741  *                  one of the following forms:
1742  *
1743  *                     system.nt_sec_desc.<attribute name>
1744  *                     system.nt_sec_desc.*
1745  *                     system.nt_sec_desc.*+
1746  *
1747  *                  where <attribute name> is one of:
1748  *
1749  *                     revision
1750  *                     owner
1751  *                     owner+
1752  *                     group
1753  *                     group+
1754  *                     acl:<name or sid>
1755  *                     acl+:<name or sid>
1756  *
1757  *                  In the forms "system.nt_sec_desc.*" and
1758  *                  "system.nt_sec_desc.*+", the asterisk and plus signs are
1759  *                  literal, i.e. the string is provided exactly as shown, and
1760  *                  the value parameter will return a complete security
1761  *                  descriptor with name:value pairs separated by tabs,
1762  *                  commas, or newlines (not spaces!).
1763  *
1764  *                  The plus sign ('+') indicates that SIDs should be mapped
1765  *                  to names.  Without the plus sign, SIDs are not mapped;
1766  *                  rather they are simply converted to a string format.
1767  *
1768  * @param value     A pointer to a buffer in which the value of the specified
1769  *                  attribute will be placed (unless size is zero).
1770  *
1771  * @param size      The size of the buffer pointed to by value.  This parameter
1772  *                  may also be zero, in which case the size of the buffer
1773  *                  required to hold the attribute value will be returned,
1774  *                  but nothing will be placed into the value buffer.
1775  * 
1776  * @return          0 on success, < 0 on error with errno set:
1777  *                  - EINVAL  The client library is not properly initialized
1778  *                            or one of the parameters is not of a correct
1779  *                            form
1780  *                  - ENOMEM No memory was available for internal needs
1781  *                  - EEXIST  If the attribute already exists and the flag
1782  *                            SMBC_XATTR_FLAG_CREAT was specified
1783  *                  - ENOATTR If the attribute does not exist and the flag
1784  *                            SMBC_XATTR_FLAG_REPLACE was specified
1785  *                  - EPERM   Permission was denied.
1786  *                  - ENOTSUP The referenced file system does not support
1787  *                            extended attributes
1788  *
1789  */
1790 int smbc_fgetxattr(int fd,
1791                    const char *name,
1792                    const void *value,
1793                    size_t size);
1794
1795
1796 /**@ingroup attribute
1797  * Remove extended attributes for a file.  This is used for modifying a file's
1798  * security descriptor (i.e. owner, group, and access control list)
1799  *
1800  * @param url       The smb url of the file or directory to remove the extended
1801  *                  attributes for.
1802  * 
1803  * @param name      The name of an attribute to be removed.  Names are of
1804  *                  one of the following forms:
1805  *
1806  *                     system.nt_sec_desc.<attribute name>
1807  *                     system.nt_sec_desc.*
1808  *                     system.nt_sec_desc.*+
1809  *
1810  *                  where <attribute name> is one of:
1811  *
1812  *                     revision
1813  *                     owner
1814  *                     owner+
1815  *                     group
1816  *                     group+
1817  *                     acl:<name or sid>
1818  *                     acl+:<name or sid>
1819  *
1820  *                  In the forms "system.nt_sec_desc.*" and
1821  *                  "system.nt_sec_desc.*+", the asterisk and plus signs are
1822  *                  literal, i.e. the string is provided exactly as shown, and
1823  *                  the value parameter will return a complete security
1824  *                  descriptor with name:value pairs separated by tabs,
1825  *                  commas, or newlines (not spaces!).
1826  *
1827  *                  The plus sign ('+') indicates that SIDs should be mapped
1828  *                  to names.  Without the plus sign, SIDs are not mapped;
1829  *                  rather they are simply converted to a string format.
1830  *
1831  * @return          0 on success, < 0 on error with errno set:
1832  *                  - EINVAL The client library is not properly initialized
1833  *                  - ENOMEM No memory was available for internal needs
1834  *                  - EPERM  Permission was denied.
1835  *                  - ENOTSUP The referenced file system does not support
1836  *                            extended attributes
1837  *
1838  */
1839 int smbc_removexattr(const char *url,
1840                      const char *name);
1841
1842
1843 /**@ingroup attribute
1844  * Remove extended attributes for a file.  This is used for modifying a file's
1845  * security descriptor (i.e. owner, group, and access control list) The POSIX
1846  * function which this maps to would act on a symbolic link rather than acting
1847  * on what the symbolic link points to, but with no symbolic links in SMB file
1848  * systems, this function is functionally identical to smbc_removexattr().
1849  *
1850  * @param url       The smb url of the file or directory to remove the extended
1851  *                  attributes for.
1852  * 
1853  * @param name      The name of an attribute to be removed.  Names are of
1854  *                  one of the following forms:
1855  *
1856  *                     system.nt_sec_desc.<attribute name>
1857  *                     system.nt_sec_desc.*
1858  *                     system.nt_sec_desc.*+
1859  *
1860  *                  where <attribute name> is one of:
1861  *
1862  *                     revision
1863  *                     owner
1864  *                     owner+
1865  *                     group
1866  *                     group+
1867  *                     acl:<name or sid>
1868  *                     acl+:<name or sid>
1869  *
1870  *                  In the forms "system.nt_sec_desc.*" and
1871  *                  "system.nt_sec_desc.*+", the asterisk and plus signs are
1872  *                  literal, i.e. the string is provided exactly as shown, and
1873  *                  the value parameter will return a complete security
1874  *                  descriptor with name:value pairs separated by tabs,
1875  *                  commas, or newlines (not spaces!).
1876  *
1877  *                  The plus sign ('+') indicates that SIDs should be mapped
1878  *                  to names.  Without the plus sign, SIDs are not mapped;
1879  *                  rather they are simply converted to a string format.
1880  *
1881  * @return          0 on success, < 0 on error with errno set:
1882  *                  - EINVAL The client library is not properly initialized
1883  *                  - ENOMEM No memory was available for internal needs
1884  *                  - EPERM  Permission was denied.
1885  *                  - ENOTSUP The referenced file system does not support
1886  *                            extended attributes
1887  *
1888  */
1889 int smbc_lremovexattr(const char *url,
1890                       const char *name);
1891
1892
1893 /**@ingroup attribute
1894  * Remove extended attributes for a file.  This is used for modifying a file's
1895  * security descriptor (i.e. owner, group, and access control list)
1896  *
1897  * @param fd        A file descriptor associated with an open file (as
1898  *                  previously returned by smbc_open(), to get extended
1899  *                  attributes for.
1900  * 
1901  * @param name      The name of an attribute to be removed.  Names are of
1902  *                  one of the following forms:
1903  *
1904  *                     system.nt_sec_desc.<attribute name>
1905  *                     system.nt_sec_desc.*
1906  *                     system.nt_sec_desc.*+
1907  *
1908  *                  where <attribute name> is one of:
1909  *
1910  *                     revision
1911  *                     owner
1912  *                     owner+
1913  *                     group
1914  *                     group+
1915  *                     acl:<name or sid>
1916  *                     acl+:<name or sid>
1917  *
1918  *                  In the forms "system.nt_sec_desc.*" and
1919  *                  "system.nt_sec_desc.*+", the asterisk and plus signs are
1920  *                  literal, i.e. the string is provided exactly as shown, and
1921  *                  the value parameter will return a complete security
1922  *                  descriptor with name:value pairs separated by tabs,
1923  *                  commas, or newlines (not spaces!).
1924  *
1925  *                  The plus sign ('+') indicates that SIDs should be mapped
1926  *                  to names.  Without the plus sign, SIDs are not mapped;
1927  *                  rather they are simply converted to a string format.
1928  *
1929  * @return          0 on success, < 0 on error with errno set:
1930  *                  - EINVAL The client library is not properly initialized
1931  *                  - ENOMEM No memory was available for internal needs
1932  *                  - EPERM  Permission was denied.
1933  *                  - ENOTSUP The referenced file system does not support
1934  *                            extended attributes
1935  *
1936  */
1937 int smbc_fremovexattr(int fd,
1938                       const char *name);
1939
1940
1941 /**@ingroup attribute
1942  * List the supported extended attribute names associated with a file
1943  *
1944  * @param url       The smb url of the file or directory to list the extended
1945  *                  attributes for.
1946  *
1947  * @param list      A pointer to a buffer in which the list of attributes for
1948  *                  the specified file or directory will be placed (unless
1949  *                  size is zero).
1950  *
1951  * @param size      The size of the buffer pointed to by list.  This parameter
1952  *                  may also be zero, in which case the size of the buffer
1953  *                  required to hold all of the attribute names will be
1954  *                  returned, but nothing will be placed into the list buffer.
1955  * 
1956  * @return          0 on success, < 0 on error with errno set:
1957  *                  - EINVAL The client library is not properly initialized
1958  *                  - ENOMEM No memory was available for internal needs
1959  *                  - EPERM  Permission was denied.
1960  *                  - ENOTSUP The referenced file system does not support
1961  *                            extended attributes
1962  *
1963  * @note            This function always returns all attribute names supported
1964  *                  by NT file systems, regardless of wether the referenced
1965  *                  file system supports extended attributes (e.g. a Windows
1966  *                  2000 machine supports extended attributes if NTFS is used,
1967  *                  but not if FAT is used, and Windows 98 doesn't support
1968  *                  extended attributes at all.  Whether this is a feature or
1969  *                  a bug is yet to be decided.
1970  */
1971 int smbc_listxattr(const char *url,
1972                    char *list,
1973                    size_t size);
1974
1975 /**@ingroup attribute
1976  * List the supported extended attribute names associated with a file The
1977  * POSIX function which this maps to would act on a symbolic link rather than
1978  * acting on what the symbolic link points to, but with no symbolic links in
1979  * SMB file systems, this function is functionally identical to
1980  * smbc_listxattr().
1981  *
1982  * @param url       The smb url of the file or directory to list the extended
1983  *                  attributes for.
1984  *
1985  * @param list      A pointer to a buffer in which the list of attributes for
1986  *                  the specified file or directory will be placed (unless
1987  *                  size is zero).
1988  *
1989  * @param size      The size of the buffer pointed to by list.  This parameter
1990  *                  may also be zero, in which case the size of the buffer
1991  *                  required to hold all of the attribute names will be
1992  *                  returned, but nothing will be placed into the list buffer.
1993  * 
1994  * @return          0 on success, < 0 on error with errno set:
1995  *                  - EINVAL The client library is not properly initialized
1996  *                  - ENOMEM No memory was available for internal needs
1997  *                  - EPERM  Permission was denied.
1998  *                  - ENOTSUP The referenced file system does not support
1999  *                            extended attributes
2000  *
2001  * @note            This function always returns all attribute names supported
2002  *                  by NT file systems, regardless of wether the referenced
2003  *                  file system supports extended attributes (e.g. a Windows
2004  *                  2000 machine supports extended attributes if NTFS is used,
2005  *                  but not if FAT is used, and Windows 98 doesn't support
2006  *                  extended attributes at all.  Whether this is a feature or
2007  *                  a bug is yet to be decided.
2008  */
2009 int smbc_llistxattr(const char *url,
2010                     char *list,
2011                     size_t size);
2012
2013 /**@ingroup attribute
2014  * List the supported extended attribute names associated with a file
2015  *
2016  * @param fd        A file descriptor associated with an open file (as
2017  *                  previously returned by smbc_open(), to get extended
2018  *                  attributes for.
2019  * 
2020  * @param list      A pointer to a buffer in which the list of attributes for
2021  *                  the specified file or directory will be placed (unless
2022  *                  size is zero).
2023  *
2024  * @param size      The size of the buffer pointed to by list.  This parameter
2025  *                  may also be zero, in which case the size of the buffer
2026  *                  required to hold all of the attribute names will be
2027  *                  returned, but nothing will be placed into the list buffer.
2028  * 
2029  * @return          0 on success, < 0 on error with errno set:
2030  *                  - EINVAL The client library is not properly initialized
2031  *                  - ENOMEM No memory was available for internal needs
2032  *                  - EPERM  Permission was denied.
2033  *                  - ENOTSUP The referenced file system does not support
2034  *                            extended attributes
2035  *
2036  * @note            This function always returns all attribute names supported
2037  *                  by NT file systems, regardless of wether the referenced
2038  *                  file system supports extended attributes (e.g. a Windows
2039  *                  2000 machine supports extended attributes if NTFS is used,
2040  *                  but not if FAT is used, and Windows 98 doesn't support
2041  *                  extended attributes at all.  Whether this is a feature or
2042  *                  a bug is yet to be decided.
2043  */
2044 int smbc_flistxattr(int fd,
2045                     char *list,
2046                     size_t size);
2047
2048 /**@ingroup print
2049  * Print a file given the name in fname. It would be a URL ...
2050  * 
2051  * @param fname     The URL of a file on a remote SMB server that the
2052  *                  caller wants printed
2053  *
2054  * @param printq    The URL of the print share to print the file to.
2055  *
2056  * @return          0 on success, < 0 on error with errno set:         
2057  *
2058  *                  - EINVAL fname or printq was NULL or smbc_init not
2059  *                    not called.
2060  *                  and errors returned by smbc_open
2061  *
2062  */                                     
2063 int smbc_print_file(const char *fname, const char *printq);
2064
2065 /**@ingroup print
2066  * Open a print file that can be written to by other calls. This simply
2067  * does an smbc_open call after checking if there is a file name on the
2068  * URI. If not, a temporary name is added ...
2069  *
2070  * @param fname     The URL of the print share to print to?
2071  *
2072  * @returns         A file handle for the print file if successful.
2073  *                  Returns -1 if an error ocurred and errno has the values
2074  *                  - EINVAL fname was NULL or smbc_init not called.
2075  *                  - all errors returned by smbc_open
2076  *
2077  */
2078 int smbc_open_print_job(const char *fname);
2079
2080 /**@ingroup print
2081  * List the print jobs on a print share, for the moment, pass a callback 
2082  *
2083  * @param purl      The url of the print share to list the jobs of
2084  * 
2085  * @param fn        Callback function the receives printjob info
2086  * 
2087  * @return          0 on success, < 0 on error with errno set: 
2088  *                  - EINVAL fname was NULL or smbc_init not called
2089  *                  - EACCES ???
2090  */
2091 int smbc_list_print_jobs(const char *purl, smbc_list_print_job_fn fn);
2092
2093 /**@ingroup print
2094  * Delete a print job 
2095  *
2096  * @param purl      Url of the print share
2097  *
2098  * @param id        The id of the job to delete
2099  *
2100  * @return          0 on success, < 0 on error with errno set: 
2101  *                  - EINVAL fname was NULL or smbc_init not called
2102  *
2103  * @todo    what errno values are possible here?
2104  */
2105 int smbc_unlink_print_job(const char *purl, int id);
2106
2107 /**@ingroup callback
2108  * Remove a server from the cached server list it's unused.
2109  *
2110  * @param context    pointer to smb context
2111  *
2112  * @param srv        pointer to server to remove
2113  *
2114  * @return On success, 0 is returned. 1 is returned if the server could not
2115  *         be removed. Also useable outside libsmbclient.
2116  */
2117 int smbc_remove_unused_server(SMBCCTX * context, SMBCSRV * srv);
2118
2119 #ifdef __cplusplus
2120 }
2121 #endif
2122
2123 /**@ingroup directory
2124  * Convert strings of %xx to their single character equivalent.
2125  *
2126  * @param dest      A pointer to a buffer in which the resulting decoded
2127  *                  string should be placed.  This may be a pointer to the
2128  *                  same buffer as src_segment.
2129  * 
2130  * @param src       A pointer to the buffer containing the URL to be decoded.
2131  *                  Any %xx sequences herein are converted to their single
2132  *                  character equivalent.  Each 'x' must be a valid hexadecimal
2133  *                  digit, or that % sequence is left undecoded.
2134  *
2135  * @param max_dest_len
2136  *                  The size of the buffer pointed to by dest_segment.
2137  * 
2138  * @return          The number of % sequences which could not be converted
2139  *                  due to lack of two following hexadecimal digits.
2140  */
2141 #ifdef __cplusplus
2142 extern "C" {
2143 #endif
2144 int
2145 smbc_urldecode(char *dest, char * src, size_t max_dest_len);
2146 #ifdef __cplusplus
2147 }
2148 #endif
2149
2150
2151 /*
2152  * Convert any characters not specifically allowed in a URL into their %xx
2153  * equivalent.
2154  *
2155  * @param dest      A pointer to a buffer in which the resulting encoded
2156  *                  string should be placed.  Unlike smbc_urldecode(), this
2157  *                  must be a buffer unique from src.
2158  * 
2159  * @param src       A pointer to the buffer containing the string to be encoded.
2160  *                  Any character not specifically allowed in a URL is converted
2161  *                  into its hexadecimal value and encoded as %xx.
2162  *
2163  * @param max_dest_len
2164  *                  The size of the buffer pointed to by dest_segment.
2165  * 
2166  * @returns         The remaining buffer length.
2167  */
2168 #ifdef __cplusplus
2169 extern "C" {
2170 #endif
2171 int
2172 smbc_urlencode(char * dest, char * src, int max_dest_len);
2173 #ifdef __cplusplus
2174 }
2175 #endif
2176
2177
2178 /**@ingroup directory
2179  * Return the version of the linked Samba code, and thus the version of the
2180  * libsmbclient code.
2181  *
2182  * @return          The version string.
2183  */
2184 #ifdef __cplusplus
2185 extern "C" {
2186 #endif
2187 const char *
2188 smbc_version(void);
2189 #ifdef __cplusplus
2190 }
2191 #endif
2192
2193
2194 #endif /* SMBCLIENT_H_INCLUDED */