source3/include/libsmbclient.h

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