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
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.
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.
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 =====================================================================*/
23 #ifndef SMBCLIENT_H_INCLUDED
24 #define SMBCLIENT_H_INCLUDED
26 /*-------------------------------------------------------------------*/
27 /* The following are special comments to instruct DOXYGEN (automated
30 /** \defgroup libsmbclient
32 /** \defgroup structure Data Structures Type and Constants
33 * \ingroup libsmbclient
34 * Data structures, types, and constants
36 /** \defgroup file File Functions
37 * \ingroup libsmbclient
38 * Functions used to access individual file contents
40 /** \defgroup directory Directory Functions
41 * \ingroup libsmbclient
42 * Functions used to access directory entries
44 /** \defgroup attribute Attributes Functions
45 * \ingroup libsmbclient
46 * Functions used to view or change file and directory attributes
48 /** \defgroup print Print Functions
49 * \ingroup libsmbclient
50 * Functions used to access printing functionality
52 /** \defgroup attribute Miscellaneous Functions
53 * \ingroup libsmbclient
54 * Functions that don't fit in to other categories
56 /*-------------------------------------------------------------------*/
58 /* Make sure we have the following includes for now ... */
59 #include <sys/types.h>
63 #define SMBC_MAX_NAME 1023
64 #define SMBC_WORKGROUP 1
66 #define SMBC_FILE_SHARE 3
67 #define SMBC_PRINTER_SHARE 4
68 #define SMBC_COMMS_SHARE 5
69 #define SMBC_IPC_SHARE 6
74 #define SMBC_FILE_MODE (S_IFREG | 0444)
75 #define SMBC_DIR_MODE (S_IFDIR | 0555)
77 #define SMBC_MAX_FD 10000
81 * Structure that represents a directory entry.
98 /** Length of this smbc_dirent in bytes
101 /** The length of the comment string in bytes (includes null
105 /** Points to the null terminated comment string
108 /** The length of the name string in bytes (includes null
112 /** Points to the null terminated name string
119 typedef unsigned short uint16;
121 /**@ingroup structure
122 * Structure that represents a print job.
125 struct print_job_info
127 /** numeric ID of the print job
131 /** represents print job priority (lower numbers mean higher priority)
135 /** Size of the print job
139 /** Name of the user that owns the print job
143 /** Name of the print job. This will have no name if an anonymous print
144 * file was opened. Ie smb://server/printer
148 /** Time the print job was spooled
155 /**@ingroup structure
156 * Authentication callback function type.
158 * Type for the the authentication function called by the library to
159 * obtain authentication credentals
161 * @param srv Server being authenticated to
163 * @param shr Share being authenticated to
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.
169 * @param wglen The size of the workgroup buffer in bytes
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
176 * @param unlen The size of the username buffer in bytes
178 * @param pw Pointer to buffer containing to which password
181 * @param pwlen The size of the password buffer in bytes
184 typedef void (*smbc_get_auth_data_fn)(const char *srv,
188 char *pw, int pwlen);
191 /**@ingroup structure
192 * Print job info callback function type.
194 * @param i pointer to print job information structure
197 typedef void (*smbc_get_print_job_info)(struct print_job_info *i);
201 * Initialize the samba client library.
203 * Must be called before using any of the smbclient API function
205 * @param fn The function that will be called to obtaion
206 * authentication credentials.
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.
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
217 int smbc_init(smbc_get_auth_data_fn fn, int debug);
221 * Open a file on an SMB server.
223 * @param furl The smb url of the file to be opened.
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
231 * O_EXCL - When used with O_CREAT, if the file
232 * already exists it is an error and the open will
234 * O_TRUNC - If the file already exists it will be
236 * O_APPEND The file is opened in append mode
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)
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.
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
253 * - EISDIR pathname refers to a directory and
254 * the access requested involved writing.
255 * - EACCES The requested access to the file is not
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
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.
271 int smbc_open(const char *furl, int flags, mode_t mode);
275 * Create a file on an SMB server.
277 * Same as calling smbc_open() with flags = O_CREAT|O_WRONLY|O_TRUNC
279 * @param furl The smb url of the file to be created
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)
286 * NOTE, the above is not true. We are dealing with
287 * an SMB server, which has no concept of a umask!
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
295 * - EISDIR pathname refers to a directory and
296 * the access requested involved writing.
297 * - EACCES The requested access to the file is not
299 * - ENOENT A directory component in pathname does
301 * - ENODEV The requested share does not exist.
305 int smbc_creat(const char *furl, mode_t mode);
309 * Read from a file using an opened file handle.
311 * @param fd Open file handle from smbc_open() or smbc_creat()
313 * @param buf Pointer to buffer to recieve read data
315 * @param bufsize Size of buf in bytes
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.
325 * @see smbc_open(), smbc_write()
328 ssize_t smbc_read(int fd, void *buf, size_t bufsize);
332 * Write to a file using an opened file handle.
334 * @param fd Open file handle from smbc_open() or smbc_creat()
336 * @param buf Pointer to buffer to recieve read data
338 * @param bufsize Size of buf in bytes
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.
348 * @see smbc_open(), smbc_read()
351 ssize_t smbc_write(int fd, void *buf, size_t bufsize);
355 * Seek to a specific location in a file.
357 * @param fd Open file handle from smbc_open() or smbc_creat()
359 * @param offset Offset in bytes from whence
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
366 * - SEEK_END The offset is set to the size of the
367 * file plus offset bytes.
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
378 * @todo Are all the whence values really supported?
380 * @todo Are errno values complete and correct?
382 off_t smbc_lseek(int fd, off_t offset, int whence);
386 * Close an open file handle.
388 * @param fd The file handle to close
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
394 * @see smbc_open(), smbc_creat()
396 int smbc_close(int fd);
399 /**@ingroup directory
400 * Unlink (delete) a file or directory.
402 * @param furl The smb url of the file to delete
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
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
418 * @todo Are errno values complete and correct?
420 int smbc_unlink(const char *furl);
423 /**@ingroup directory
424 * Rename or move a file or directory.
426 * @param ourl The original smb url (source url) of file or
427 * directory to be moved
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.
433 * @return 0 on success, < 0 on error with errno set:
434 * - EISDIR nurl is an existing directory, but ourl is
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
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
454 * - EXDEV Rename across shares not supported.
455 * - ENOMEM Insufficient kernel memory was available.
456 * - EEXIST The target file, nurl, already exists.
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.
463 int smbc_rename(const char *ourl, const char *nurl);
466 /**@ingroup directory
467 * Open a directory used to obtain directory entries.
469 * @param durl The smb url of the directory to open
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
476 * - ENOENT durl does not exist, or name is an
477 * - ENOMEM Insufficient memory to complete the
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.
483 * @see smbc_getdents(), smbc_readdir(), smbc_closedir()
486 int smbc_opendir(const char *durl);
489 /**@ingroup directory
490 * Close a directory handle opened by smbc_opendir().
492 * @param dh Directory handle to close
494 * @return 0 on success, < 0 on error with errno set:
495 * - EBADF dh is an invalid directory handle
497 * @see smbc_opendir()
499 int smbc_closedir(int dh);
502 /**@ingroup directory
503 * Get multiple directory entries.
505 * smbc_getdents() reads as many dirent structures from the an open
506 * directory handle into a specified memory area as will fit.
508 * @param dh Valid directory as returned by smbc_opendir()
510 * @param dirp pointer to buffer that will receive the directory
513 * @param count The size of the dirp buffer in bytes
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
521 * - ENOENT No such directory.
522 * @see , smbc_dirent, smbc_readdir(), smbc_open()
524 * @todo Are errno values complete and correct?
526 * @todo Add example code so people know how to parse buffers.
528 int smbc_getdents(unsigned int dh, struct smbc_dirent *dirp, int count);
531 /**@ingroup directory
532 * Get a single directory entry.
534 * @param dh Valid directory as returned by smbc_opendir()
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
541 * @see smbc_dirent, smbc_getdents(), smbc_open()
543 struct smbc_dirent* smbc_readdir(unsigned int dh);
546 /**@ingroup directory
547 * Get the current directory offset.
549 * smbc_telldir() may be used in conjunction with smbc_readdir() and
552 * @param dh Valid directory as returned by smbc_opendir()
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
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
563 * @see smbc_readdir()
566 off_t smbc_telldir(int dh);
569 /**@ingroup directory
570 * lseek on directories.
572 * smbc_lseekdir() may be used in conjunction with smbc_readdir() and
573 * smbc_telldir(). (rewind by smbc_lseekdir(fd, NULL))
575 * @param fd Valid directory as returned by smbc_opendir()
577 * @param offset The offset (as returned by smbc_telldir). Can be
578 * NULL, in which case we will rewind
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.
586 * @see smbc_telldir()
589 * @todo In what does the reture and errno values mean?
591 int smbc_lseekdir(int fd, off_t offset);
593 /**@ingroup directory
594 * Create a directory.
596 * @param durl The url of the directory to create
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).
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
608 * - EINVAL NULL durl passed or smbc_init not called.
609 * - ENOMEM Insufficient memory was available.
614 int smbc_mkdir(const char *durl, mode_t mode);
617 /**@ingroup directory
618 * Remove a directory.
620 * @param durl The smb url of the directory to remove
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
628 * - ENOTEMPTY directory contains entries.
629 * - ENOMEM Insufficient kernel memory was available.
631 * @see smbc_mkdir(), smbc_unlink()
633 * @todo Are errno values complete and correct?
635 int smbc_rmdir(const char *durl);
638 /**@ingroup attribute
639 * Get information about a file or directory.
641 * @param url The smb url to get information for
643 * @param st pointer to a buffer that will be filled with
644 * standard Unix struct stat information.
646 * @return 0 on success, < 0 on error with errno set:
647 * - ENOENT A component of the path file_name does not
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.
657 int smbc_stat(const char *url, struct stat *st);
660 /**@ingroup attribute
661 * Get file information via an file descriptor.
663 * @param fd Open file handle from smbc_open() or smbc_creat()
665 * @param st pointer to a buffer that will be filled with
666 * standard Unix struct stat information.
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
675 * @see smbc_stat(), Unix stat()
678 int smbc_fstat(int fd, struct stat *st);
682 * Change the ownership of a file or directory.
684 * @param url The smb url of the file or directory to change
687 * @param owner I have no idea?
689 * @param group I have not idea?
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
699 * @todo Are we actually going to be able to implement this function
701 * @todo How do we abstract owner and group uid and gid?
704 int smbc_chown(const char *url, uid_t owner, gid_t group);
707 /**@ingroup attribute
708 * Change the permissions of a file.
710 * @param url The smb url of the file or directory to change
713 * @param mode The permissions to set:
714 * - Put good explaination of permissions here!
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
723 * @todo Actually implement this fuction?
725 * @todo Are errno values complete and correct?
727 int smbc_chmod(const char *url, mode_t mode);
731 * Print a file given the name in fname. It would be a URL ...
733 * @param fname The URL of a file on a remote SMB server that the
734 * caller wants printed
736 * @param printq The URL of the print share to print the file to.
738 * @return 0 on success, < 0 on error with errno set:
740 * - EINVAL fname or printq was NULL or smbc_init not
742 * and errors returned by smbc_open
745 int smbc_print_file(const char *fname, const char *printq);
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 ...
752 * @param fname The URL of the print share to print to?
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
760 int smbc_open_print_job(const char *fname);
763 * List the print jobs on a print share, for the moment, pass a callback
765 * @param purl The url of the print share to list the jobs of
767 * @param fn Callback function the receives printjob info
769 * @return 0 on success, < 0 on error with errno set:
770 * - EINVAL fname was NULL or smbc_init not called
773 int smbc_list_print_jobs(const char *purl, smbc_get_print_job_info fn);
778 * @param purl Url of the print share
780 * @param id The id of the job to delete
782 * @return 0 on success, < 0 on error with errno set:
783 * - EINVAL fname was NULL or smbc_init not called
785 * @todo what errno values are possible here?
787 int smbc_unlink_print_job(const char *purl, int id);
790 #endif /* SMBCLIENT_H_INCLUDED */