Removed version number from file header.
[kai/samba.git] / source3 / include / libsmbclient.h
1 /*=====================================================================
2   Unix SMB/CIFS 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    
8   This program is free software; you can redistribute it and/or modify
9   it under the terms of the GNU General Public License as published by
10   the Free Software Foundation; either version 2 of the License, or
11   (at your option) any later version.
12    
13   This program is distributed in the hope that it will be useful,
14   but WITHOUT ANY WARRANTY; without even the implied warranty of
15   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
16   GNU General Public License for more details.
17    
18   You should have received a copy of the GNU General Public License
19   along with this program; if not, write to the Free Software
20   Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
21   =====================================================================*/
22
23 #ifndef SMBCLIENT_H_INCLUDED
24 #define SMBCLIENT_H_INCLUDED
25
26 /*-------------------------------------------------------------------*/
27 /* The following are special comments to instruct DOXYGEN (automated 
28  * documentation tool:
29 */
30 /** \defgroup libsmbclient
31 */
32 /** \defgroup structure Data Structures Type and Constants
33 *   \ingroup libsmbclient
34 *   Data structures, types, and constants
35 */
36 /** \defgroup file File Functions
37 *   \ingroup libsmbclient
38 *   Functions used to access individual file contents
39 */
40 /** \defgroup directory Directory Functions
41 *   \ingroup libsmbclient
42 *   Functions used to access directory entries
43 */
44 /** \defgroup attribute Attributes Functions
45 *   \ingroup libsmbclient
46 *   Functions used to view or change file and directory attributes
47 */
48 /** \defgroup print Print Functions
49 *   \ingroup libsmbclient
50 *   Functions used to access printing functionality
51 */
52 /** \defgroup attribute Miscellaneous Functions
53 *   \ingroup libsmbclient
54 *   Functions that don't fit in to other categories
55 */
56 /*-------------------------------------------------------------------*/   
57
58 /* Make sure we have the following includes for now ... */
59 #include <sys/types.h>
60 #include <sys/stat.h>
61 #include <fcntl.h>
62
63 #define SMBC_MAX_NAME       1023
64 #define SMBC_WORKGROUP      1
65 #define SMBC_SERVER         2
66 #define SMBC_FILE_SHARE     3
67 #define SMBC_PRINTER_SHARE  4
68 #define SMBC_COMMS_SHARE    5
69 #define SMBC_IPC_SHARE      6
70 #define SMBC_DIR            7
71 #define SMBC_FILE           8
72 #define SMBC_LINK           9
73
74 #define SMBC_FILE_MODE (S_IFREG | 0444)
75 #define SMBC_DIR_MODE  (S_IFDIR | 0555)
76
77 #define SMBC_MAX_FD         10000
78
79
80 /**@ingroup structure
81  * Structure that represents a directory entry.
82  *
83  */
84 struct smbc_dirent 
85 {
86         /** Type of entity.
87             SMBC_WORKGROUP=1,
88             SMBC_SERVER=2, 
89             SMBC_FILE_SHARE=3,
90             SMBC_PRINTER_SHARE=4,
91             SMBC_COMMS_SHARE=5,
92             SMBC_IPC_SHARE=6,
93             SMBC_DIR=7,
94             SMBC_FILE=8,
95             SMBC_LINK=9,*/ 
96         uint smbc_type; 
97
98         /** Length of this smbc_dirent in bytes
99          */
100         uint dirlen;
101         /** The length of the comment string in bytes (includes null 
102          *  terminator)
103          */
104         uint commentlen;
105         /** Points to the null terminated comment string 
106          */
107         char *comment;
108         /** The length of the name string in bytes (includes null 
109          *  terminator)
110          */
111         uint namelen;
112         /** Points to the null terminated name string 
113          */
114         char name[1];
115 };
116
117
118 #ifndef _CLIENT_H
119 typedef unsigned short uint16;
120
121 /**@ingroup structure
122  * Structure that represents a print job.
123  *
124  */
125 struct print_job_info 
126 {
127         /** numeric ID of the print job
128          */
129         uint16 id;
130     
131         /** represents print job priority (lower numbers mean higher priority)
132          */
133         uint16 priority;
134     
135         /** Size of the print job
136          */
137         size_t size;
138     
139         /** Name of the user that owns the print job
140          */
141         char user[128];
142   
143         /** Name of the print job. This will have no name if an anonymous print
144          *  file was opened. Ie smb://server/printer
145          */
146         char name[128];
147
148         /** Time the print job was spooled
149          */
150         time_t t;
151 };
152 #endif
153
154
155 /**@ingroup structure
156  * Authentication callback function type.
157  * 
158  * Type for the the authentication function called by the library to
159  * obtain authentication credentals
160  *
161  * @param srv       Server being authenticated to
162  *
163  * @param shr       Share being authenticated to
164  *
165  * @param wg        Pointer to buffer containing a "hint" for the
166  *                  workgroup to be authenticated.  Should be filled in
167  *                  with the correct workgroup if the hint is wrong.
168  * 
169  * @param wglen     The size of the workgroup buffer in bytes
170  *
171  * @param un        Pointer to buffer containing a "hint" for the
172  *                  user name to be use for authentication. Should be
173  *                  filled in with the correct workgroup if the hint is
174  *                  wrong.
175  * 
176  * @param unlen     The size of the username buffer in bytes
177  *
178  * @param pw        Pointer to buffer containing to which password 
179  *                  copied
180  * 
181  * @param pwlen     The size of the password buffer in bytes
182  *           
183  */
184 typedef void (*smbc_get_auth_data_fn)(const char *srv, 
185                                       const char *shr,
186                                       char *wg, int wglen, 
187                                       char *un, int unlen,
188                                       char *pw, int pwlen);
189
190
191 /**@ingroup structure
192  * Print job info callback function type.
193  *
194  * @param i         pointer to print job information structure
195  *
196  */ 
197 typedef void (*smbc_get_print_job_info)(struct print_job_info *i);
198
199
200 /**@ingroup misc
201  * Initialize the samba client library.
202  *
203  * Must be called before using any of the smbclient API function
204  *  
205  * @param fn        The function that will be called to obtaion 
206  *                  authentication credentials.
207  *
208  * @param debug     Allows caller to set the debug level. Can be
209  *                  changed in smb.conf file. Allows caller to set
210  *                  debugging if no smb.conf.
211  *   
212  * @return          0 on success, < 0 on error with errno set:
213  *                  - ENOMEM Out of memory
214  *                  - ENOENT The smb.conf file would not load
215  *
216  */
217 int smbc_init(smbc_get_auth_data_fn fn, int debug);
218
219
220 /**@ingroup file
221  * Open a file on an SMB server.
222  *
223  * @param furl      The smb url of the file to be opened. 
224  *
225  * @param flags     Is one of O_RDONLY, O_WRONLY or O_RDWR which 
226  *                  request opening  the  file  read-only,write-only
227  *                  or read/write. flags may also be bitwise-or'd with
228  *                  one or  more of  the following: 
229  *                  O_CREAT - If the file does not exist it will be 
230  *                  created.
231  *                  O_EXCL - When  used with O_CREAT, if the file 
232  *                  already exists it is an error and the open will 
233  *                  fail. 
234  *                  O_TRUNC - If the file already exists it will be
235  *                  truncated.
236  *                  O_APPEND The  file  is  opened  in  append mode 
237  *
238  * @param mode      mode specifies the permissions to use if a new 
239  *                  file is created.  It  is  modified  by  the 
240  *                  process's umask in the usual way: the permissions
241  *                  of the created file are (mode & ~umask) 
242  *
243  *                  Not currently use, but there for future use.
244  *                  We will map this to SYSTEM, HIDDEN, etc bits
245  *                  that reverses the mapping that smbc_fstat does.
246  *
247  * @return          Valid file handle, < 0 on error with errno set:
248  *                  - ENOMEM  Out of memory
249  *                  - EINVAL if an invalid parameter passed, like no 
250  *                  file, or smbc_init not called.
251  *                  - EEXIST  pathname already exists and O_CREAT and 
252  *                  O_EXCL were used.
253  *                  - EISDIR  pathname  refers  to  a  directory  and  
254  *                  the access requested involved writing.
255  *                  - EACCES  The requested access to the file is not 
256  *                  allowed 
257  *                  - ENODEV The requested share does not exist
258  *                  - ENOTDIR A file on the path is not a directory
259  *                  - ENOENT  A directory component in pathname does 
260  *                  not exist.
261  *
262  * @see             smbc_creat()
263  *
264  * @note            This call uses an underlying routine that may create
265  *                  a new connection to the server specified in the URL.
266  *                  If the credentials supplied in the URL, or via the
267  *                  auth_fn in the smbc_init call, fail, this call will
268  *                  try again with an empty username and password. This 
269  *                  often gets mapped to the guest account on some machines.
270  */
271 int smbc_open(const char *furl, int flags, mode_t mode);
272
273
274 /**@ingroup file
275  * Create a file on an SMB server.
276  *
277  * Same as calling smbc_open() with flags = O_CREAT|O_WRONLY|O_TRUNC 
278  *   
279  * @param furl      The smb url of the file to be created
280  *  
281  * @param mode      mode specifies the permissions to use if  a  new  
282  *                  file is created.  It  is  modified  by  the 
283  *                  process's umask in the usual way: the permissions
284  *                  of the created file are (mode & ~umask)
285  *
286  *                  NOTE, the above is not true. We are dealing with 
287  *                  an SMB server, which has no concept of a umask!
288  *      
289  * @return          Valid file handle, < 0 on error with errno set:
290  *                  - ENOMEM  Out of memory
291  *                  - EINVAL if an invalid parameter passed, like no 
292  *                  file, or smbc_init not called.
293  *                  - EEXIST  pathname already exists and O_CREAT and
294  *                  O_EXCL were used.
295  *                  - EISDIR  pathname  refers  to  a  directory  and
296  *                  the access requested involved writing.
297  *                  - EACCES  The requested access to the file is not
298  *                  allowed 
299  *                  - ENOENT  A directory component in pathname does 
300  *                  not exist.
301  *                  - ENODEV The requested share does not exist.
302  * @see             smbc_open()
303  *
304  */
305 int smbc_creat(const char *furl, mode_t mode);
306
307
308 /**@ingroup file
309  * Read from a file using an opened file handle.
310  *
311  * @param fd        Open file handle from smbc_open() or smbc_creat()
312  *
313  * @param buf       Pointer to buffer to recieve read data
314  *
315  * @param bufsize   Size of buf in bytes
316  *
317  * @return          Number of bytes read, < 0 on error with errno set:
318  *                  - EISDIR fd refers to a directory
319  *                  - EBADF  fd  is  not  a valid file descriptor or 
320  *                  is not open for reading.
321  *                  - EINVAL fd is attached to an object which is 
322  *                  unsuitable for reading, or no buffer passed or
323  *                  smbc_init not called.
324  *
325  * @see             smbc_open(), smbc_write()
326  *
327  */
328 ssize_t smbc_read(int fd, void *buf, size_t bufsize);
329
330
331 /**@ingroup file
332  * Write to a file using an opened file handle.
333  *
334  * @param fd        Open file handle from smbc_open() or smbc_creat()
335  *
336  * @param buf       Pointer to buffer to recieve read data
337  *
338  * @param bufsize   Size of buf in bytes
339  *
340  * @return          Number of bytes written, < 0 on error with errno set:
341  *                  - EISDIR fd refers to a directory.
342  *                  - EBADF  fd  is  not  a valid file descriptor or 
343  *                  is not open for reading.
344  *                  - EINVAL fd is attached to an object which is 
345  *                  unsuitable for reading, or no buffer passed or
346  *                  smbc_init not called.
347  *
348  * @see             smbc_open(), smbc_read()
349  *
350  */
351 ssize_t smbc_write(int fd, void *buf, size_t bufsize);
352
353
354 /**@ingroup file
355  * Seek to a specific location in a file.
356  *
357  * @param fd        Open file handle from smbc_open() or smbc_creat()
358  * 
359  * @param offset    Offset in bytes from whence
360  * 
361  * @param whence    A location in the file:
362  *                  - SEEK_SET The offset is set to offset bytes from
363  *                  the beginning of the file
364  *                  - SEEK_CUR The offset is set to current location 
365  *                  plus offset bytes.
366  *                  - SEEK_END The offset is set to the size of the 
367  *                  file plus offset bytes.
368  *
369  * @return          Upon successful completion, lseek returns the 
370  *                  resulting offset location as measured in bytes 
371  *                  from the beginning  of the file. Otherwise, a value
372  *                  of (off_t)-1 is returned and errno is set to 
373  *                  indicate the error:
374  *                  - EBADF  Fildes is not an open file descriptor.
375  *                  - EINVAL Whence is not a proper value or smbc_init
376  *                    not called.
377  *
378  * @todo Are all the whence values really supported?
379  * 
380  * @todo Are errno values complete and correct?
381  */
382 off_t smbc_lseek(int fd, off_t offset, int whence);
383
384
385 /**@ingroup file
386  * Close an open file handle.
387  *
388  * @param fd        The file handle to close
389  *
390  * @return          0 on success, < 0 on error with errno set:
391  *                  - EBADF  fd isn't a valid open file descriptor
392  *                  - EINVAL smbc_init() failed or has not been called
393  *
394  * @see             smbc_open(), smbc_creat()
395  */
396 int smbc_close(int fd);
397
398
399 /**@ingroup directory
400  * Unlink (delete) a file or directory.
401  *
402  * @param furl      The smb url of the file to delete
403  *
404  * @return          0 on success, < 0 on error with errno set:
405  *                  - EACCES or EPERM Write  access  to the directory 
406  *                  containing pathname is not allowed or one  
407  *                  of  the  directories in pathname did not allow
408  *                  search (execute) permission
409  *                  - ENOENT A directory component in pathname does
410  *                  not exist
411  *                  - EINVAL NULL was passed in the file param or
412  *                    smbc_init not called.
413  *                  - EACCES You do not have access to the file
414  *                  - ENOMEM Insufficient kernel memory was available
415  *
416  * @see             smbc_rmdir()s
417  *
418  * @todo Are errno values complete and correct?
419  */
420 int smbc_unlink(const char *furl);
421
422
423 /**@ingroup directory
424  * Rename or move a file or directory.
425  * 
426  * @param ourl      The original smb url (source url) of file or 
427  *                  directory to be moved
428  * 
429  * @param nurl      The new smb url (destination url) of the file
430  *                  or directory after the move.  Currently nurl must
431  *                  be on the same share as ourl.
432  *
433  * @return          0 on success, < 0 on error with errno set:
434  *                  - EISDIR nurl is an existing directory, but ourl is
435  *                  not a directory.
436  *                  - EEXIST nurl is  a  non-empty directory, 
437  *                  i.e., contains entries other than "." and ".."
438  *                  - EINVAL The  new  url  contained  a path prefix 
439  *                  of the old, or, more generally, an  attempt was
440  *                  made  to make a directory a subdirectory of itself
441  *                  or smbc_init not called.
442  *                  - ENOTDIR A component used as a directory in ourl 
443  *                  or nurl path is not, in fact, a directory.  Or, 
444  *                  ourl  is a directory, and newpath exists but is not
445  *                  a directory.
446  *                  - EACCES or EPERM Write access to the directory 
447  *                  containing ourl or nurl is not allowed for the 
448  *                  process's effective uid,  or  one of the 
449  *                  directories in ourl or nurl did not allow search
450  *                  (execute) permission,  or ourl  was  a  directory
451  *                  and did not allow write permission.
452  *                  - ENOENT A  directory component in ourl or nurl 
453  *                  does not exist.
454  *                  - EXDEV Rename across shares not supported.
455  *                  - ENOMEM Insufficient kernel memory was available.
456  *                  - EEXIST The target file, nurl, already exists.
457  *
458  *
459  * @todo Are we going to support copying when urls are not on the same
460  *       share?  I say no... NOTE. I agree for the moment.
461  *
462  */
463 int smbc_rename(const char *ourl, const char *nurl);
464
465
466 /**@ingroup directory
467  * Open a directory used to obtain directory entries.
468  *
469  * @param durl      The smb url of the directory to open
470  *
471  * @return          Valid directory handle. < 0 on error with errno set:
472  *                  - EACCES Permission denied.
473  *                  - EINVAL A NULL file/URL was passed, or the URL would
474  *                  not parse, or was of incorrect form or smbc_init not
475  *                  called.
476  *                  - ENOENT durl does not exist, or name is an 
477  *                  - ENOMEM Insufficient memory to complete the 
478  *                  operation.                              
479  *                  - ENOTDIR name is not a directory.
480  *                  - EPERM the workgroup could not be found.
481  *                  - ENODEV the workgroup or server could not be found.
482  *
483  * @see             smbc_getdents(), smbc_readdir(), smbc_closedir()
484  *
485  */
486 int smbc_opendir(const char *durl);
487
488
489 /**@ingroup directory
490  * Close a directory handle opened by smbc_opendir().
491  *
492  * @param dh        Directory handle to close
493  *
494  * @return          0 on success, < 0 on error with errno set:
495  *                  - EBADF dh is an invalid directory handle
496  *
497  * @see             smbc_opendir()
498  */
499 int smbc_closedir(int dh);
500
501
502 /**@ingroup directory
503  * Get multiple directory entries.
504  *
505  * smbc_getdents() reads as many dirent structures from the an open 
506  * directory handle into a specified memory area as will fit.
507  *
508  * @param dh        Valid directory as returned by smbc_opendir()
509  *
510  * @param dirp      pointer to buffer that will receive the directory
511  *                  entries.
512  * 
513  * @param count     The size of the dirp buffer in bytes
514  *
515  * @returns         If any dirents returned, return will indicate the
516  *                  total size. If there were no more dirents available,
517  *                  0 is returned. < 0 indicates an error.
518  *                  - EBADF  Invalid directory handle
519  *                  - EINVAL Result buffer is too small or smbc_init
520  *                  not called.
521  *                  - ENOENT No such directory.
522  * @see             , smbc_dirent, smbc_readdir(), smbc_open()
523  *
524  * @todo Are errno values complete and correct?
525  *
526  * @todo Add example code so people know how to parse buffers.
527  */
528 int smbc_getdents(unsigned int dh, struct smbc_dirent *dirp, int count);
529
530
531 /**@ingroup directory
532  * Get a single directory entry.
533  *
534  * @param dh        Valid directory as returned by smbc_opendir()
535  *
536  * @return          A pointer to a smbc_dirent structure, or NULL if an
537  *                  error occurs or end-of-directory is reached:
538  *                  - EBADF Invalid directory handle
539  *                  - EINVAL smbc_init() failed or has not been called
540  *
541  * @see             smbc_dirent, smbc_getdents(), smbc_open()
542  */
543 struct smbc_dirent* smbc_readdir(unsigned int dh);
544
545
546 /**@ingroup directory
547  * Get the current directory offset.
548  *
549  * smbc_telldir() may be used in conjunction with smbc_readdir() and
550  * smbc_lseekdir().
551  *
552  * @param dh        Valid directory as returned by smbc_opendir()
553  *
554  * @return          The current location in the directory stream or -1
555  *                  if an error occur.  The current location is not
556  *                  an offset. Becuase of the implementation, it is a 
557  *                  handle that allows the library to find the entry
558  *                  later.
559  *                  - EBADF dh is not a valid directory handle
560  *                  - EINVAL smbc_init() failed or has not been called
561  *                  - ENOTDIR if dh is not a directory
562  *
563  * @see             smbc_readdir()
564  *
565  */
566 off_t smbc_telldir(int dh);
567
568
569 /**@ingroup directory
570  * lseek on directories.
571  *
572  * smbc_lseekdir() may be used in conjunction with smbc_readdir() and
573  * smbc_telldir(). (rewind by smbc_lseekdir(fd, NULL))
574  *
575  * @param fd        Valid directory as returned by smbc_opendir()
576  * 
577  * @param offset    The offset (as returned by smbc_telldir). Can be
578  *                  NULL, in which case we will rewind
579  *
580  * @return          0 on success, -1 on failure
581  *                  - EBADF dh is not a valid directory handle
582  *                  - ENOTDIR if dh is not a directory
583  *                  - EINVAL offset did not refer to a valid dirent or
584  *                    smbc_init not called.
585  *
586  * @see             smbc_telldir()
587  *
588  *
589  * @todo In what does the reture and errno values mean?
590  */
591 int smbc_lseekdir(int fd, off_t offset);
592
593 /**@ingroup directory
594  * Create a directory.
595  *
596  * @param durl      The url of the directory to create
597  *
598  * @param mode      Specifies  the  permissions to use. It is modified
599  *                  by the process's umask in the usual way: the 
600  *                  permissions of the created file are (mode & ~umask).
601  * 
602  * @return          0 on success, < 0 on error with errno set:
603  *                  - EEXIST directory url already exists
604  *                  - EACCES The parent directory does not allow write
605  *                  permission to the process, or one of the directories
606  *                  - ENOENT A directory component in pathname does not
607  *                  exist.
608  *                  - EINVAL NULL durl passed or smbc_init not called.
609  *                  - ENOMEM Insufficient memory was available.
610  *
611  * @see             smbc_rmdir()
612  *
613  */
614 int smbc_mkdir(const char *durl, mode_t mode);
615
616
617 /**@ingroup directory
618  * Remove a directory.
619  * 
620  * @param durl      The smb url of the directory to remove
621  *
622  * @return          0 on success, < 0 on error with errno set:
623  *                  - EACCES or EPERM Write access to the directory
624  *                  containing pathname was not allowed.
625  *                  - EINVAL durl is NULL or smbc_init not called.
626  *                  - ENOENT A directory component in pathname does not
627  *                  exist.
628  *                  - ENOTEMPTY directory contains entries.
629  *                  - ENOMEM Insufficient kernel memory was available.
630  *
631  * @see             smbc_mkdir(), smbc_unlink() 
632  *
633  * @todo Are errno values complete and correct?
634  */
635 int smbc_rmdir(const char *durl);
636
637
638 /**@ingroup attribute
639  * Get information about a file or directory.
640  *
641  * @param url       The smb url to get information for
642  *
643  * @param st        pointer to a buffer that will be filled with 
644  *                  standard Unix struct stat information.
645  *
646  * @return          0 on success, < 0 on error with errno set:
647  *                  - ENOENT A component of the path file_name does not
648  *                  exist.
649  *                  - EINVAL a NULL url was passed or smbc_init not called.
650  *                  - EACCES Permission denied.
651  *                  - ENOMEM Out of memory
652  *                  - ENOTDIR The target dir, url, is not a directory.
653  *
654  * @see             Unix stat()
655  *
656  */
657 int smbc_stat(const char *url, struct stat *st);
658
659
660 /**@ingroup attribute
661  * Get file information via an file descriptor.
662  * 
663  * @param fd        Open file handle from smbc_open() or smbc_creat()
664  *
665  * @param st        pointer to a buffer that will be filled with 
666  *                  standard Unix struct stat information.
667  * 
668  * @return          EBADF  filedes is bad.
669  *                  - EACCES Permission denied.
670  *                  - EBADF fd is not a valid file descriptor
671  *                  - EINVAL Problems occurred in the underlying routines
672  *                    or smbc_init not called.
673  *                  - ENOMEM Out of memory
674  *
675  * @see             smbc_stat(), Unix stat()
676  *
677  */
678 int smbc_fstat(int fd, struct stat *st);
679
680
681 /**@ingroup attribue
682  * Change the ownership of a file or directory.
683  *
684  * @param url       The smb url of the file or directory to change 
685  *                  ownership of.
686  *
687  * @param owner     I have no idea?
688  *
689  * @param group     I have not idea?
690  *
691  * @return          0 on success, < 0 on error with errno set:
692  *                  - EPERM  The effective UID does not match the owner
693  *                  of the file, and is not zero; or the owner or group
694  *                  were specified incorrectly.
695  *                  - ENOENT The file does not exist.
696  *                  - ENOMEM Insufficient was available.
697  *                  - ENOENT file or directory does not exist
698  *
699  * @todo Are we actually going to be able to implement this function
700  *
701  * @todo How do we abstract owner and group uid and gid?
702  *
703  */
704 int smbc_chown(const char *url, uid_t owner, gid_t group);
705
706
707 /**@ingroup attribute
708  * Change the permissions of a file.
709  *
710  * @param url       The smb url of the file or directory to change
711  *                  permissions of
712  * 
713  * @param mode      The permissions to set:
714  *                  - Put good explaination of permissions here!
715  *
716  * @return          0 on success, < 0 on error with errno set:
717  *                  - EPERM  The effective UID does not match the owner
718  *                  of the file, and is not zero
719  *                  - ENOENT The file does not exist.
720  *                  - ENOMEM Insufficient was available.
721  *                  - ENOENT file or directory does not exist
722  *
723  * @todo Actually implement this fuction?
724  *
725  * @todo Are errno values complete and correct?
726  */
727 int smbc_chmod(const char *url, mode_t mode);
728
729
730 /**@ingroup print
731  * Print a file given the name in fname. It would be a URL ...
732  * 
733  * @param fname     The URL of a file on a remote SMB server that the
734  *                  caller wants printed
735  *
736  * @param printq    The URL of the print share to print the file to.
737  *
738  * @return          0 on success, < 0 on error with errno set:         
739  *
740  *                  - EINVAL fname or printq was NULL or smbc_init not
741  *                    not called.
742  *                  and errors returned by smbc_open
743  *
744  */                                     
745 int smbc_print_file(const char *fname, const char *printq);
746
747 /**@ingroup print
748  * Open a print file that can be written to by other calls. This simply
749  * does an smbc_open call after checking if there is a file name on the
750  * URI. If not, a temporary name is added ...
751  *
752  * @param fname     The URL of the print share to print to?
753  *
754  * @returns         A file handle for the print file if successful.
755  *                  Returns -1 if an error ocurred and errno has the values
756  *                  - EINVAL fname was NULL or smbc_init not called.
757  *                  - all errors returned by smbc_open
758  *
759  */
760 int smbc_open_print_job(const char *fname);
761
762 /**@ingroup print
763  * List the print jobs on a print share, for the moment, pass a callback 
764  *
765  * @param purl      The url of the print share to list the jobs of
766  * 
767  * @param fn        Callback function the receives printjob info
768  * 
769  * @return          0 on success, < 0 on error with errno set: 
770  *                  - EINVAL fname was NULL or smbc_init not called
771  *                  - EACCES ???
772  */
773 int smbc_list_print_jobs(const char *purl, smbc_get_print_job_info fn);
774
775 /**@ingroup print
776  * Delete a print job 
777  *
778  * @param purl      Url of the print share
779  *
780  * @param id        The id of the job to delete
781  *
782  * @return          0 on success, < 0 on error with errno set: 
783  *                  - EINVAL fname was NULL or smbc_init not called
784  *
785  * @todo    what errno values are possible here?
786  */
787 int smbc_unlink_print_job(const char *purl, int id);
788
789
790 #endif /* SMBCLIENT_H_INCLUDED */