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