1 /*=====================================================================
2 Unix SMB/Netbios implementation.
4 SMB client library API definitions
5 Copyright (C) Andrew Tridgell 1998
6 Copyright (C) Richard Sharpe 2000
7 Copyright (C) John Terpsra 2000
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.
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.
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 =====================================================================*/
24 #ifndef SMBCLIENT_H_INCLUDED
25 #define SMBCLIENT_H_INCLUDED
27 /*-------------------------------------------------------------------*/
28 /* The following are special comments to instruct DOXYGEN (automated
31 /** \defgroup libsmbclient
33 /** \defgroup structure Data Structures Type and Constants
34 * \ingroup libsmbclient
35 * Data structures, types, and constants
37 /** \defgroup file File Functions
38 * \ingroup libsmbclient
39 * Functions used to access individual file contents
41 /** \defgroup directory Directory Functions
42 * \ingroup libsmbclient
43 * Functions used to access directory entries
45 /** \defgroup attribute Attributes Functions
46 * \ingroup libsmbclient
47 * Functions used to view or change file and directory attributes
49 /** \defgroup print Print Functions
50 * \ingroup libsmbclient
51 * Functions used to access printing functionality
53 /** \defgroup attribute Miscellaneous Functions
54 * \ingroup libsmbclient
55 * Functions that don't fit in to other categories
57 /*-------------------------------------------------------------------*/
59 /* Make sure we have the following includes for now ... */
60 #include <sys/types.h>
64 #define SMBC_MAX_NAME 1023
65 #define SMBC_WORKGROUP 1
67 #define SMBC_FILE_SHARE 3
68 #define SMBC_PRINTER_SHARE 4
69 #define SMBC_COMMS_SHARE 5
70 #define SMBC_IPC_SHARE 6
75 #define SMBC_FILE_MODE (S_IFREG | 0444)
76 #define SMBC_DIR_MODE (S_IFDIR | 0555)
78 #define SMBC_MAX_FD 10000
82 * Structure that represents a directory entry.
99 /** Length of this smbc_dirent in bytes
102 /** The length of the comment string in bytes (includes null
106 /** Points to the null terminated comment string
109 /** The length of the name string in bytes (includes null
113 /** Points to the null terminated name string
120 typedef unsigned short uint16
;
122 /**@ingroup structure
123 * Structure that represents a print job.
126 struct print_job_info
128 /** numeric ID of the print job
132 /** represents print job priority (lower numbers mean higher priority)
136 /** Size of the print job
140 /** Name of the user that owns the print job
144 /** Name of the print job. This will have no name if an anonymous print
145 * file was opened. Ie smb://server/printer
149 /** Time the print job was spooled
156 /**@ingroup structure
157 * Authentication callback function type.
159 * Type for the the authentication function called by the library to
160 * obtain authentication credentals
162 * @param srv Server being authenticated to
164 * @param shr Share being authenticated to
166 * @param wg Pointer to buffer containing a "hint" for the
167 * workgroup to be authenticated. Should be filled in
168 * with the correct workgroup if the hint is wrong.
170 * @param wglen The size of the workgroup buffer in bytes
172 * @param un Pointer to buffer containing a "hint" for the
173 * user name to be use for authentication. Should be
174 * filled in with the correct workgroup if the hint is
177 * @param unlen The size of the username buffer in bytes
179 * @param pw Pointer to buffer containing to which password
182 * @param pwlen The size of the password buffer in bytes
185 typedef void (*smbc_get_auth_data_fn
)(const char *srv
,
189 char *pw
, int pwlen
);
192 /**@ingroup structure
193 * Print job info callback function type.
195 * @param i pointer to print job information structure
198 typedef void (*smbc_get_print_job_info
)(struct print_job_info
*i
);
202 * Initialize the samba client library.
204 * Must be called before using any of the smbclient API function
206 * @param fn The function that will be called to obtaion
207 * authentication credentials.
209 * @param debug Allows caller to set the debug level. Can be
210 * changed in smb.conf file. Allows caller to set
211 * debugging if no smb.conf.
213 * @return 0 on success, < 0 on error with errno set:
214 * - ENOMEM Out of memory
215 * - ENOENT The smb.conf file would not load
218 int smbc_init(smbc_get_auth_data_fn fn
, int debug
);
222 * Open a file on an SMB server.
224 * @param furl The smb url of the file to be opened.
226 * @param flags Is one of O_RDONLY, O_WRONLY or O_RDWR which
227 * request opening the file read-only,write-only
228 * or read/write. flags may also be bitwise-or'd with
229 * one or more of the following:
230 * O_CREAT - If the file does not exist it will be
232 * O_EXCL - When used with O_CREAT, if the file
233 * already exists it is an error and the open will
235 * O_TRUNC - If the file already exists it will be
237 * O_APPEND The file is opened in append mode
239 * @param mode mode specifies the permissions to use if a new
240 * file is created. It is modified by the
241 * process's umask in the usual way: the permissions
242 * of the created file are (mode & ~umask)
244 * Not currently use, but there for future use.
245 * We will map this to SYSTEM, HIDDEN, etc bits
246 * that reverses the mapping that smbc_fstat does.
248 * @return Valid file handle, < 0 on error with errno set:
249 * - ENOMEM Out of memory
250 * - EINVAL if an invalid parameter passed, like no
251 * file, or smbc_init not called.
252 * - EEXIST pathname already exists and O_CREAT and
254 * - EISDIR pathname refers to a directory and
255 * the access requested involved writing.
256 * - EACCES The requested access to the file is not
258 * - ENODEV The requested share does not exist
259 * - ENOTDIR A file on the path is not a directory
260 * - ENOENT A directory component in pathname does
265 * @note This call uses an underlying routine that may create
266 * a new connection to the server specified in the URL.
267 * If the credentials supplied in the URL, or via the
268 * auth_fn in the smbc_init call, fail, this call will
269 * try again with an empty username and password. This
270 * often gets mapped to the guest account on some machines.
272 int smbc_open(const char *furl
, int flags
, mode_t mode
);
276 * Create a file on an SMB server.
278 * Same as calling smbc_open() with flags = O_CREAT|O_WRONLY|O_TRUNC
280 * @param furl The smb url of the file to be created
282 * @param mode mode specifies the permissions to use if a new
283 * file is created. It is modified by the
284 * process's umask in the usual way: the permissions
285 * of the created file are (mode & ~umask)
287 * NOTE, the above is not true. We are dealing with
288 * an SMB server, which has no concept of a umask!
290 * @return Valid file handle, < 0 on error with errno set:
291 * - ENOMEM Out of memory
292 * - EINVAL if an invalid parameter passed, like no
293 * file, or smbc_init not called.
294 * - EEXIST pathname already exists and O_CREAT and
296 * - EISDIR pathname refers to a directory and
297 * the access requested involved writing.
298 * - EACCES The requested access to the file is not
300 * - ENOENT A directory component in pathname does
302 * - ENODEV The requested share does not exist.
306 int smbc_creat(const char *furl
, mode_t mode
);
310 * Read from a file using an opened file handle.
312 * @param fd Open file handle from smbc_open() or smbc_creat()
314 * @param buf Pointer to buffer to recieve read data
316 * @param bufsize Size of buf in bytes
318 * @return Number of bytes read, < 0 on error with errno set:
319 * - EISDIR fd refers to a directory
320 * - EBADF fd is not a valid file descriptor or
321 * is not open for reading.
322 * - EINVAL fd is attached to an object which is
323 * unsuitable for reading, or no buffer passed or
324 * smbc_init not called.
326 * @see smbc_open(), smbc_write()
329 ssize_t
smbc_read(int fd
, void *buf
, size_t bufsize
);
333 * Write to a file using an opened file handle.
335 * @param fd Open file handle from smbc_open() or smbc_creat()
337 * @param buf Pointer to buffer to recieve read data
339 * @param bufsize Size of buf in bytes
341 * @return Number of bytes written, < 0 on error with errno set:
342 * - EISDIR fd refers to a directory.
343 * - EBADF fd is not a valid file descriptor or
344 * is not open for reading.
345 * - EINVAL fd is attached to an object which is
346 * unsuitable for reading, or no buffer passed or
347 * smbc_init not called.
349 * @see smbc_open(), smbc_read()
352 ssize_t
smbc_write(int fd
, void *buf
, size_t bufsize
);
356 * Seek to a specific location in a file.
358 * @param fd Open file handle from smbc_open() or smbc_creat()
360 * @param offset Offset in bytes from whence
362 * @param whence A location in the file:
363 * - SEEK_SET The offset is set to offset bytes from
364 * the beginning of the file
365 * - SEEK_CUR The offset is set to current location
367 * - SEEK_END The offset is set to the size of the
368 * file plus offset bytes.
370 * @return Upon successful completion, lseek returns the
371 * resulting offset location as measured in bytes
372 * from the beginning of the file. Otherwise, a value
373 * of (off_t)-1 is returned and errno is set to
374 * indicate the error:
375 * - EBADF Fildes is not an open file descriptor.
376 * - EINVAL Whence is not a proper value or smbc_init
379 * @todo Are all the whence values really supported?
381 * @todo Are errno values complete and correct?
383 off_t
smbc_lseek(int fd
, off_t offset
, int whence
);
387 * Close an open file handle.
389 * @param fd The file handle to close
391 * @return 0 on success, < 0 on error with errno set:
392 * - EBADF fd isn't a valid open file descriptor
393 * - EINVAL smbc_init() failed or has not been called
395 * @see smbc_open(), smbc_creat()
397 int smbc_close(int fd
);
400 /**@ingroup directory
401 * Unlink (delete) a file or directory.
403 * @param furl The smb url of the file to delete
405 * @return 0 on success, < 0 on error with errno set:
406 * - EACCES or EPERM Write access to the directory
407 * containing pathname is not allowed or one
408 * of the directories in pathname did not allow
409 * search (execute) permission
410 * - ENOENT A directory component in pathname does
412 * - EINVAL NULL was passed in the file param or
413 * smbc_init not called.
414 * - EACCES You do not have access to the file
415 * - ENOMEM Insufficient kernel memory was available
419 * @todo Are errno values complete and correct?
421 int smbc_unlink(const char *furl
);
424 /**@ingroup directory
425 * Rename or move a file or directory.
427 * @param ourl The original smb url (source url) of file or
428 * directory to be moved
430 * @param nurl The new smb url (destination url) of the file
431 * or directory after the move. Currently nurl must
432 * be on the same share as ourl.
434 * @return 0 on success, < 0 on error with errno set:
435 * - EISDIR nurl is an existing directory, but ourl is
437 * - EEXIST nurl is a non-empty directory,
438 * i.e., contains entries other than "." and ".."
439 * - EINVAL The new url contained a path prefix
440 * of the old, or, more generally, an attempt was
441 * made to make a directory a subdirectory of itself
442 * or smbc_init not called.
443 * - ENOTDIR A component used as a directory in ourl
444 * or nurl path is not, in fact, a directory. Or,
445 * ourl is a directory, and newpath exists but is not
447 * - EACCES or EPERM Write access to the directory
448 * containing ourl or nurl is not allowed for the
449 * process's effective uid, or one of the
450 * directories in ourl or nurl did not allow search
451 * (execute) permission, or ourl was a directory
452 * and did not allow write permission.
453 * - ENOENT A directory component in ourl or nurl
455 * - EXDEV Rename across shares not supported.
456 * - ENOMEM Insufficient kernel memory was available.
457 * - EEXIST The target file, nurl, already exists.
460 * @todo Are we going to support copying when urls are not on the same
461 * share? I say no... NOTE. I agree for the moment.
464 int smbc_rename(const char *ourl
, const char *nurl
);
467 /**@ingroup directory
468 * Open a directory used to obtain directory entries.
470 * @param durl The smb url of the directory to open
472 * @return Valid directory handle. < 0 on error with errno set:
473 * - EACCES Permission denied.
474 * - EINVAL A NULL file/URL was passed, or the URL would
475 * not parse, or was of incorrect form or smbc_init not
477 * - ENOENT durl does not exist, or name is an
478 * - ENOMEM Insufficient memory to complete the
480 * - ENOTDIR name is not a directory.
481 * - EPERM the workgroup could not be found.
482 * - ENODEV the workgroup or server could not be found.
484 * @see smbc_getdents(), smbc_readdir(), smbc_closedir()
487 int smbc_opendir(const char *durl
);
490 /**@ingroup directory
491 * Close a directory handle opened by smbc_opendir().
493 * @param dh Directory handle to close
495 * @return 0 on success, < 0 on error with errno set:
496 * - EBADF dh is an invalid directory handle
498 * @see smbc_opendir()
500 int smbc_closedir(int dh
);
503 /**@ingroup directory
504 * Get multiple directory entries.
506 * smbc_getdents() reads as many dirent structures from the an open
507 * directory handle into a specified memory area as will fit.
509 * @param dh Valid directory as returned by smbc_opendir()
511 * @param dirp pointer to buffer that will receive the directory
514 * @param count The size of the dirp buffer in bytes
516 * @returns If any dirents returned, return will indicate the
517 * total size. If there were no more dirents available,
518 * 0 is returned. < 0 indicates an error.
519 * - EBADF Invalid directory handle
520 * - EINVAL Result buffer is too small or smbc_init
522 * - ENOENT No such directory.
523 * @see , smbc_dirent, smbc_readdir(), smbc_open()
525 * @todo Are errno values complete and correct?
527 * @todo Add example code so people know how to parse buffers.
529 int smbc_getdents(unsigned int dh
, struct smbc_dirent
*dirp
, int count
);
532 /**@ingroup directory
533 * Get a single directory entry.
535 * @param dh Valid directory as returned by smbc_opendir()
537 * @return A pointer to a smbc_dirent structure, or NULL if an
538 * error occurs or end-of-directory is reached:
539 * - EBADF Invalid directory handle
540 * - EINVAL smbc_init() failed or has not been called
542 * @see smbc_dirent, smbc_getdents(), smbc_open()
544 struct smbc_dirent
* smbc_readdir(unsigned int dh
);
547 /**@ingroup directory
548 * Get the current directory offset.
550 * smbc_telldir() may be used in conjunction with smbc_readdir() and
553 * @param dh Valid directory as returned by smbc_opendir()
555 * @return The current location in the directory stream or -1
556 * if an error occur. The current location is not
557 * an offset. Becuase of the implementation, it is a
558 * handle that allows the library to find the entry
560 * - EBADF dh is not a valid directory handle
561 * - EINVAL smbc_init() failed or has not been called
562 * - ENOTDIR if dh is not a directory
564 * @see smbc_readdir()
567 off_t
smbc_telldir(int dh
);
570 /**@ingroup directory
571 * lseek on directories.
573 * smbc_lseekdir() may be used in conjunction with smbc_readdir() and
574 * smbc_telldir(). (rewind by smbc_lseekdir(fd, NULL))
576 * @param fd Valid directory as returned by smbc_opendir()
578 * @param offset The offset (as returned by smbc_telldir). Can be
579 * NULL, in which case we will rewind
581 * @return 0 on success, -1 on failure
582 * - EBADF dh is not a valid directory handle
583 * - ENOTDIR if dh is not a directory
584 * - EINVAL offset did not refer to a valid dirent or
585 * smbc_init not called.
587 * @see smbc_telldir()
590 * @todo In what does the reture and errno values mean?
592 int smbc_lseekdir(int fd
, off_t offset
);
594 /**@ingroup directory
595 * Create a directory.
597 * @param durl The url of the directory to create
599 * @param mode Specifies the permissions to use. It is modified
600 * by the process's umask in the usual way: the
601 * permissions of the created file are (mode & ~umask).
603 * @return 0 on success, < 0 on error with errno set:
604 * - EEXIST directory url already exists
605 * - EACCES The parent directory does not allow write
606 * permission to the process, or one of the directories
607 * - ENOENT A directory component in pathname does not
609 * - EINVAL NULL durl passed or smbc_init not called.
610 * - ENOMEM Insufficient memory was available.
615 int smbc_mkdir(const char *durl
, mode_t mode
);
618 /**@ingroup directory
619 * Remove a directory.
621 * @param durl The smb url of the directory to remove
623 * @return 0 on success, < 0 on error with errno set:
624 * - EACCES or EPERM Write access to the directory
625 * containing pathname was not allowed.
626 * - EINVAL durl is NULL or smbc_init not called.
627 * - ENOENT A directory component in pathname does not
629 * - ENOTEMPTY directory contains entries.
630 * - ENOMEM Insufficient kernel memory was available.
632 * @see smbc_mkdir(), smbc_unlink()
634 * @todo Are errno values complete and correct?
636 int smbc_rmdir(const char *durl
);
639 /**@ingroup attribute
640 * Get information about a file or directory.
642 * @param url The smb url to get information for
644 * @param st pointer to a buffer that will be filled with
645 * standard Unix struct stat information.
647 * @return 0 on success, < 0 on error with errno set:
648 * - ENOENT A component of the path file_name does not
650 * - EINVAL a NULL url was passed or smbc_init not called.
651 * - EACCES Permission denied.
652 * - ENOMEM Out of memory
653 * - ENOTDIR The target dir, url, is not a directory.
658 int smbc_stat(const char *url
, struct stat
*st
);
661 /**@ingroup attribute
662 * Get file information via an file descriptor.
664 * @param fd Open file handle from smbc_open() or smbc_creat()
666 * @param st pointer to a buffer that will be filled with
667 * standard Unix struct stat information.
669 * @return EBADF filedes is bad.
670 * - EACCES Permission denied.
671 * - EBADF fd is not a valid file descriptor
672 * - EINVAL Problems occurred in the underlying routines
673 * or smbc_init not called.
674 * - ENOMEM Out of memory
676 * @see smbc_stat(), Unix stat()
679 int smbc_fstat(int fd
, struct stat
*st
);
683 * Change the ownership of a file or directory.
685 * @param url The smb url of the file or directory to change
688 * @param owner I have no idea?
690 * @param group I have not idea?
692 * @return 0 on success, < 0 on error with errno set:
693 * - EPERM The effective UID does not match the owner
694 * of the file, and is not zero; or the owner or group
695 * were specified incorrectly.
696 * - ENOENT The file does not exist.
697 * - ENOMEM Insufficient was available.
698 * - ENOENT file or directory does not exist
700 * @todo Are we actually going to be able to implement this function
702 * @todo How do we abstract owner and group uid and gid?
705 int smbc_chown(const char *url
, uid_t owner
, gid_t group
);
708 /**@ingroup attribute
709 * Change the permissions of a file.
711 * @param url The smb url of the file or directory to change
714 * @param mode The permissions to set:
715 * - Put good explaination of permissions here!
717 * @return 0 on success, < 0 on error with errno set:
718 * - EPERM The effective UID does not match the owner
719 * of the file, and is not zero
720 * - ENOENT The file does not exist.
721 * - ENOMEM Insufficient was available.
722 * - ENOENT file or directory does not exist
724 * @todo Actually implement this fuction?
726 * @todo Are errno values complete and correct?
728 int smbc_chmod(const char *url
, mode_t mode
);
732 * Print a file given the name in fname. It would be a URL ...
734 * @param fname The URL of a file on a remote SMB server that the
735 * caller wants printed
737 * @param printq The URL of the print share to print the file to.
739 * @return 0 on success, < 0 on error with errno set:
741 * - EINVAL fname or printq was NULL or smbc_init not
743 * and errors returned by smbc_open
746 int smbc_print_file(const char *fname
, const char *printq
);
749 * Open a print file that can be written to by other calls. This simply
750 * does an smbc_open call after checking if there is a file name on the
751 * URI. If not, a temporary name is added ...
753 * @param fname The URL of the print share to print to?
755 * @returns A file handle for the print file if successful.
756 * Returns -1 if an error ocurred and errno has the values
757 * - EINVAL fname was NULL or smbc_init not called.
758 * - all errors returned by smbc_open
761 int smbc_open_print_job(const char *fname
);
764 * List the print jobs on a print share, for the moment, pass a callback
766 * @param purl The url of the print share to list the jobs of
768 * @param fn Callback function the receives printjob info
770 * @return 0 on success, < 0 on error with errno set:
771 * - EINVAL fname was NULL or smbc_init not called
774 int smbc_list_print_jobs(const char *purl
, smbc_get_print_job_info fn
);
779 * @param purl Url of the print share
781 * @param id The id of the job to delete
783 * @return 0 on success, < 0 on error with errno set:
784 * - EINVAL fname was NULL or smbc_init not called
786 * @todo what errno values are possible here?
788 int smbc_unlink_print_job(const char *purl
, int id
);
791 #endif /* SMBCLIENT_H_INCLUDED */