1/*===================================================================== 2 Unix SMB/Netbios implementation. 3 SMB client library API definitions 4 Copyright (C) Andrew Tridgell 1998 5 Copyright (C) Richard Sharpe 2000 6 Copyright (C) John Terpsra 2000 7 Copyright (C) Tom Jansen (Ninja ISD) 2002 8 Copyright (C) Derrell Lipman 2003 9 10 11 This program is free software; you can redistribute it and/or modify 12 it under the terms of the GNU General Public License as published by 13 the Free Software Foundation; either version 2 of the License, or 14 (at your option) any later version. 15 16 This program is distributed in the hope that it will be useful, 17 but WITHOUT ANY WARRANTY; without even the implied warranty of 18 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 19 GNU General Public License for more details. 20 21 You should have received a copy of the GNU General Public License 22 along with this program; if not, write to the Free Software 23 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. 24 =====================================================================*/ 25 26#ifndef SMBCLIENT_H_INCLUDED 27#define SMBCLIENT_H_INCLUDED 28 29/*-------------------------------------------------------------------*/ 30/* The following are special comments to instruct DOXYGEN (automated 31 * documentation tool: 32*/ 33/** \defgroup libsmbclient 34*/ 35/** \defgroup structure Data Structures Type and Constants 36* \ingroup libsmbclient 37* Data structures, types, and constants 38*/ 39/** \defgroup callback Callback function types 40* \ingroup libsmbclient 41* Callback functions 42*/ 43/** \defgroup file File Functions 44* \ingroup libsmbclient 45* Functions used to access individual file contents 46*/ 47/** \defgroup directory Directory Functions 48* \ingroup libsmbclient 49* Functions used to access directory entries 50*/ 51/** \defgroup attribute Attributes Functions 52* \ingroup libsmbclient 53* Functions used to view or change file and directory attributes 54*/ 55/** \defgroup print Print Functions 56* \ingroup libsmbclient 57* Functions used to access printing functionality 58*/ 59/** \defgroup misc Miscellaneous Functions 60* \ingroup libsmbclient 61* Functions that don't fit in to other categories 62*/ 63/*-------------------------------------------------------------------*/ 64 65/* Make sure we have the following includes for now ... */ 66#include <sys/types.h> 67#include <sys/stat.h> 68#include <fcntl.h> 69#include <utime.h> 70 71#define SMBC_BASE_FD 10000 /* smallest file descriptor returned */ 72 73#define SMBC_WORKGROUP 1 74#define SMBC_SERVER 2 75#define SMBC_FILE_SHARE 3 76#define SMBC_PRINTER_SHARE 4 77#define SMBC_COMMS_SHARE 5 78#define SMBC_IPC_SHARE 6 79#define SMBC_DIR 7 80#define SMBC_FILE 8 81#define SMBC_LINK 9 82 83/**@ingroup structure 84 * Structure that represents a directory entry. 85 * 86 */ 87struct smbc_dirent 88{ 89 /** Type of entity. 90 SMBC_WORKGROUP=1, 91 SMBC_SERVER=2, 92 SMBC_FILE_SHARE=3, 93 SMBC_PRINTER_SHARE=4, 94 SMBC_COMMS_SHARE=5, 95 SMBC_IPC_SHARE=6, 96 SMBC_DIR=7, 97 SMBC_FILE=8, 98 SMBC_LINK=9,*/ 99 unsigned int smbc_type; 100 101 /** Length of this smbc_dirent in bytes 102 */ 103 unsigned int dirlen; 104 /** The length of the comment string in bytes (includes null 105 * terminator) 106 */ 107 unsigned int commentlen; 108 /** Points to the null terminated comment string 109 */ 110 char *comment; 111 /** The length of the name string in bytes (includes null 112 * terminator) 113 */ 114 unsigned int namelen; 115 /** Points to the null terminated name string 116 */ 117 char name[1]; 118}; 119 120/* 121 * Flags for smbc_setxattr() 122 * Specify a bitwise OR of these, or 0 to add or replace as necessary 123 */ 124#define SMBC_XATTR_FLAG_CREATE 0x1 /* fail if attr already exists */ 125#define SMBC_XATTR_FLAG_REPLACE 0x2 /* fail if attr does not exist */ 126 127 128/* 129 * Mappings of the DOS mode bits, as returned by smbc_getxattr() when the 130 * attribute name "system.dos_attr.mode" (or "system.dos_attr.*" or 131 * "system.*") is specified. 132 */ 133#define SMBC_DOS_MODE_READONLY 0x01 134#define SMBC_DOS_MODE_HIDDEN 0x02 135#define SMBC_DOS_MODE_SYSTEM 0x04 136#define SMBC_DOS_MODE_VOLUME_ID 0x08 137#define SMBC_DOS_MODE_DIRECTORY 0x10 138#define SMBC_DOS_MODE_ARCHIVE 0x20 139 140 141#ifndef ENOATTR 142# define ENOATTR ENOENT /* No such attribute */ 143#endif 144 145 146 147 148/**@ingroup structure 149 * Structure that represents a print job. 150 * 151 */ 152#ifndef _CLIENT_H 153struct print_job_info 154{ 155 /** numeric ID of the print job 156 */ 157 unsigned short id; 158 159 /** represents print job priority (lower numbers mean higher priority) 160 */ 161 unsigned short priority; 162 163 /** Size of the print job 164 */ 165 size_t size; 166 167 /** Name of the user that owns the print job 168 */ 169 char user[128]; 170 171 /** Name of the print job. This will have no name if an anonymous print 172 * file was opened. Ie smb://server/printer 173 */ 174 char name[128]; 175 176 /** Time the print job was spooled 177 */ 178 time_t t; 179}; 180#endif /* _CLIENT_H */ 181 182 183/**@ingroup structure 184 * Server handle 185 */ 186typedef struct _SMBCSRV SMBCSRV; 187 188/**@ingroup structure 189 * File or directory handle 190 */ 191typedef struct _SMBCFILE SMBCFILE; 192 193/**@ingroup structure 194 * File or directory handle 195 */ 196typedef struct _SMBCCTX SMBCCTX; 197 198 199 200 201 202/**@ingroup callback 203 * Authentication callback function type. 204 * 205 * Type for the the authentication function called by the library to 206 * obtain authentication credentals 207 * 208 * @param srv Server being authenticated to 209 * 210 * @param shr Share being authenticated to 211 * 212 * @param wg Pointer to buffer containing a "hint" for the 213 * workgroup to be authenticated. Should be filled in 214 * with the correct workgroup if the hint is wrong. 215 * 216 * @param wglen The size of the workgroup buffer in bytes 217 * 218 * @param un Pointer to buffer containing a "hint" for the 219 * user name to be use for authentication. Should be 220 * filled in with the correct workgroup if the hint is 221 * wrong. 222 * 223 * @param unlen The size of the username buffer in bytes 224 * 225 * @param pw Pointer to buffer containing to which password 226 * copied 227 * 228 * @param pwlen The size of the password buffer in bytes 229 * 230 */ 231typedef void (*smbc_get_auth_data_fn)(const char *srv, 232 const char *shr, 233 char *wg, int wglen, 234 char *un, int unlen, 235 char *pw, int pwlen); 236 237 238/**@ingroup callback 239 * Print job info callback function type. 240 * 241 * @param i pointer to print job information structure 242 * 243 */ 244typedef void (*smbc_list_print_job_fn)(struct print_job_info *i); 245 246 247/**@ingroup callback 248 * Check if a server is still good 249 * 250 * @param c pointer to smb context 251 * 252 * @param srv pointer to server to check 253 * 254 * @return 0 when connection is good. 1 on error. 255 * 256 */ 257typedef int (*smbc_check_server_fn)(SMBCCTX * c, SMBCSRV *srv); 258 259/**@ingroup callback 260 * Remove a server if unused 261 * 262 * @param c pointer to smb context 263 * 264 * @param srv pointer to server to remove 265 * 266 * @return 0 on success. 1 on failure. 267 * 268 */ 269typedef int (*smbc_remove_unused_server_fn)(SMBCCTX * c, SMBCSRV *srv); 270 271 272/**@ingroup callback 273 * Add a server to the cache system 274 * 275 * @param c pointer to smb context 276 * 277 * @param srv pointer to server to add 278 * 279 * @param server server name 280 * 281 * @param share share name 282 * 283 * @param workgroup workgroup used to connect 284 * 285 * @param username username used to connect 286 * 287 * @return 0 on success. 1 on failure. 288 * 289 */ 290typedef int (*smbc_add_cached_srv_fn) (SMBCCTX * c, SMBCSRV *srv, 291 const char * server, const char * share, 292 const char * workgroup, const char * username); 293 294/**@ingroup callback 295 * Look up a server in the cache system 296 * 297 * @param c pointer to smb context 298 * 299 * @param server server name to match 300 * 301 * @param share share name to match 302 * 303 * @param workgroup workgroup to match 304 * 305 * @param username username to match 306 * 307 * @return pointer to SMBCSRV on success. NULL on failure. 308 * 309 */ 310typedef SMBCSRV * (*smbc_get_cached_srv_fn) (SMBCCTX * c, const char * server, 311 const char * share, const char * workgroup, 312 const char * username); 313 314/**@ingroup callback 315 * Check if a server is still good 316 * 317 * @param c pointer to smb context 318 * 319 * @param srv pointer to server to remove 320 * 321 * @return 0 when found and removed. 1 on failure. 322 * 323 */ 324typedef int (*smbc_remove_cached_srv_fn)(SMBCCTX * c, SMBCSRV *srv); 325 326 327/**@ingroup callback 328 * Try to remove all servers from the cache system and disconnect 329 * 330 * @param c pointer to smb context 331 * 332 * @return 0 when found and removed. 1 on failure. 333 * 334 */ 335typedef int (*smbc_purge_cached_fn) (SMBCCTX * c); 336 337 338 339 340/**@ingroup structure 341 * Structure that contains a client context information 342 * This structure is know as SMBCCTX 343 */ 344struct _SMBCCTX { 345 /** debug level 346 */ 347 int debug; 348 349 /** netbios name used for making connections 350 */ 351 char * netbios_name; 352 353 /** workgroup name used for making connections 354 */ 355 char * workgroup; 356 357 /** username used for making connections 358 */ 359 char * user; 360 361 /** timeout used for waiting on connections / response data (in milliseconds) 362 */ 363 int timeout; 364 365 /** callable functions for files: 366 * For usage and return values see the smbc_* functions 367 */ 368 SMBCFILE * (*open) (SMBCCTX *c, const char *fname, int flags, mode_t mode); 369 SMBCFILE * (*creat) (SMBCCTX *c, const char *path, mode_t mode); 370 ssize_t (*read) (SMBCCTX *c, SMBCFILE *file, void *buf, size_t count); 371 ssize_t (*write) (SMBCCTX *c, SMBCFILE *file, void *buf, size_t count); 372 int (*unlink) (SMBCCTX *c, const char *fname); 373 int (*rename) (SMBCCTX *ocontext, const char *oname, 374 SMBCCTX *ncontext, const char *nname); 375 off_t (*lseek) (SMBCCTX *c, SMBCFILE * file, off_t offset, int whence); 376 int (*stat) (SMBCCTX *c, const char *fname, struct stat *st); 377 int (*fstat) (SMBCCTX *c, SMBCFILE *file, struct stat *st); 378 int (*close) (SMBCCTX *c, SMBCFILE *file); 379 380 /** callable functions for dirs 381 */ 382 SMBCFILE * (*opendir) (SMBCCTX *c, const char *fname); 383 int (*closedir)(SMBCCTX *c, SMBCFILE *dir); 384 struct smbc_dirent * (*readdir)(SMBCCTX *c, SMBCFILE *dir); 385 int (*getdents)(SMBCCTX *c, SMBCFILE *dir, 386 struct smbc_dirent *dirp, int count); 387 int (*mkdir) (SMBCCTX *c, const char *fname, mode_t mode); 388 int (*rmdir) (SMBCCTX *c, const char *fname); 389 off_t (*telldir) (SMBCCTX *c, SMBCFILE *dir); 390 int (*lseekdir)(SMBCCTX *c, SMBCFILE *dir, off_t offset); 391 int (*fstatdir)(SMBCCTX *c, SMBCFILE *dir, struct stat *st); 392 int (*chmod)(SMBCCTX *c, const char *fname, mode_t mode); 393 int (*utimes)(SMBCCTX *c, 394 const char *fname, struct timeval *tbuf); 395 int (*setxattr)(SMBCCTX *context, 396 const char *fname, 397 const char *name, 398 const void *value, 399 size_t size, 400 int flags); 401 int (*getxattr)(SMBCCTX *context, 402 const char *fname, 403 const char *name, 404 const void *value, 405 size_t size); 406 int (*removexattr)(SMBCCTX *context, 407 const char *fname, 408 const char *name); 409 int (*listxattr)(SMBCCTX *context, 410 const char *fname, 411 char *list, 412 size_t size); 413 414 /** callable functions for printing 415 */ 416 int (*print_file)(SMBCCTX *c_file, const char *fname, 417 SMBCCTX *c_print, const char *printq); 418 SMBCFILE * (*open_print_job)(SMBCCTX *c, const char *fname); 419 int (*list_print_jobs)(SMBCCTX *c, const char *fname, smbc_list_print_job_fn fn); 420 int (*unlink_print_job)(SMBCCTX *c, const char *fname, int id); 421 422 423 /** Callbacks 424 * These callbacks _always_ have to be initialized because they will not be checked 425 * at dereference for increased speed. 426 */ 427 struct _smbc_callbacks { 428 /** authentication function callback: called upon auth requests 429 */ 430 smbc_get_auth_data_fn auth_fn; 431 432 /** check if a server is still good 433 */ 434 smbc_check_server_fn check_server_fn; 435 436 /** remove a server if unused 437 */ 438 smbc_remove_unused_server_fn remove_unused_server_fn; 439 440 /** Cache subsystem 441 * For an example cache system see samba/source/libsmb/libsmb_cache.c 442 * Cache subsystem functions follow. 443 */ 444 445 /** server cache addition 446 */ 447 smbc_add_cached_srv_fn add_cached_srv_fn; 448 449 /** server cache lookup 450 */ 451 smbc_get_cached_srv_fn get_cached_srv_fn; 452 453 /** server cache removal 454 */ 455 smbc_remove_cached_srv_fn remove_cached_srv_fn; 456 457 /** server cache purging, try to remove all cached servers (disconnect) 458 */ 459 smbc_purge_cached_fn purge_cached_fn; 460 } callbacks; 461 462 463 /** Space to store private data of the server cache. 464 */ 465 struct smbc_server_cache * server_cache; 466 467 int flags; 468 469 /** user options selections that apply to this session 470 */ 471 struct _smbc_options { 472 473 /* 474 * From how many local master browsers should the list of 475 * workgroups be retrieved? It can take up to 12 minutes or 476 * longer after a server becomes a local master browser, for 477 * it to have the entire browse list (the list of 478 * workgroups/domains) from an entire network. Since a client 479 * never knows which local master browser will be found first, 480 * the one which is found first and used to retrieve a browse 481 * list may have an incomplete or empty browse list. By 482 * requesting the browse list from multiple local master 483 * browsers, a more complete list can be generated. For small 484 * networks (few workgroups), it is recommended that this 485 * value be set to 0, causing the browse lists from all found 486 * local master browsers to be retrieved and merged. For 487 * networks with many workgroups, a suitable value for this 488 * variable is probably somewhere around 3. (Default: 3). 489 */ 490 int browse_max_lmb_count; 491 492 /* 493 * There is a difference in the desired return strings from 494 * smbc_readdir() depending upon whether the filenames are to 495 * be displayed to the user, or whether they are to be 496 * appended to the path name passed to smbc_opendir() to call 497 * a further smbc_ function (e.g. open the file with 498 * smbc_open()). In the former case, the filename should be 499 * in "human readable" form. In the latter case, the smbc_ 500 * functions expect a URL which must be url-encoded. Those 501 * functions decode the URL. If, for example, smbc_readdir() 502 * returned a file name of "abc%20def.txt", passing a path 503 * with this file name attached to smbc_open() would cause 504 * smbc_open to attempt to open the file "abc def.txt" since 505 * the %20 is decoded into a space. 506 * 507 * Set this option to True if the names returned by 508 * smbc_readdir() should be url-encoded such that they can be 509 * passed back to another smbc_ call. Set it to False if the 510 * names returned by smbc_readdir() are to be presented to the 511 * user. 512 * 513 * For backwards compatibility, this option defaults to False. 514 */ 515 int urlencode_readdir_entries; 516 517 /* 518 * Some Windows versions appear to have a limit to the number 519 * of concurrent SESSIONs and/or TREE CONNECTions. In 520 * one-shot programs (i.e. the program runs and then quickly 521 * ends, thereby shutting down all connections), it is 522 * probably reasonable to establish a new connection for each 523 * share. In long-running applications, the limitation can be 524 * avoided by using only a single connection to each server, 525 * and issuing a new TREE CONNECT when the share is accessed. 526 */ 527 int one_share_per_server; 528 } options; 529 530 /** INTERNAL DATA 531 * do _NOT_ touch this from your program ! 532 */ 533 struct smbc_internal_data * internal; 534}; 535 536/* Flags for SMBCCTX->flags */ 537#define SMB_CTX_FLAG_USE_KERBEROS (1 << 0) 538#define SMB_CTX_FLAG_FALLBACK_AFTER_KERBEROS (1 << 1) 539#define SMBCCTX_FLAG_NO_AUTO_ANONYMOUS_LOGON (1 << 2) /* don't try to do automatic anon login */ 540 541/**@ingroup misc 542 * Create a new SBMCCTX (a context). 543 * 544 * Must be called before the context is passed to smbc_context_init() 545 * 546 * @return The given SMBCCTX pointer on success, NULL on error with errno set: 547 * - ENOMEM Out of memory 548 * 549 * @see smbc_free_context(), smbc_init_context() 550 * 551 * @note Do not forget to smbc_init_context() the returned SMBCCTX pointer ! 552 */ 553#ifdef __cplusplus 554extern "C" { 555#endif 556SMBCCTX * smbc_new_context(void); 557#ifdef __cplusplus 558} 559#endif 560 561/**@ingroup misc 562 * Delete a SBMCCTX (a context) acquired from smbc_new_context(). 563 * 564 * The context will be deleted if possible. 565 * 566 * @param context A pointer to a SMBCCTX obtained from smbc_new_context() 567 * 568 * @param shutdown_ctx If 1, all connections and files will be closed even if they are busy. 569 * 570 * 571 * @return Returns 0 on succes. Returns 1 on failure with errno set: 572 * - EBUSY Server connections are still used, Files are open or cache 573 * could not be purged 574 * - EBADF context == NULL 575 * 576 * @see smbc_new_context() 577 * 578 * @note It is advised to clean up all the contexts with shutdown_ctx set to 1 579 * just before exit()'ing. When shutdown_ctx is 0, this function can be 580 * use in periodical cleanup functions for example. 581 */ 582#ifdef __cplusplus 583extern "C" { 584#endif 585int smbc_free_context(SMBCCTX * context, int shutdown_ctx); 586#ifdef __cplusplus 587} 588#endif 589 590/**@ingroup misc 591 * Initialize a SBMCCTX (a context). 592 * 593 * Must be called before using any SMBCCTX API function 594 * 595 * @param context A pointer to a SMBCCTX obtained from smbc_new_context() 596 * 597 * @return A pointer to the given SMBCCTX on success, NULL on error with errno set: 598 * - EBADF NULL context given 599 * - ENOMEM Out of memory 600 * - ENOENT The smb.conf file would not load 601 * 602 * @see smbc_new_context() 603 * 604 * @note my_context = smbc_init_context(smbc_new_context()) is perfectly safe, 605 * but it might leak memory on smbc_context_init() failure. Avoid this. 606 * You'll have to call smbc_free_context() yourself on failure. 607 */ 608#ifdef __cplusplus 609extern "C" { 610#endif 611SMBCCTX * smbc_init_context(SMBCCTX * context); 612#ifdef __cplusplus 613} 614#endif 615 616/**@ingroup misc 617 * Initialize the samba client library. 618 * 619 * Must be called before using any of the smbclient API function 620 * 621 * @param fn The function that will be called to obtaion 622 * authentication credentials. 623 * 624 * @param debug Allows caller to set the debug level. Can be 625 * changed in smb.conf file. Allows caller to set 626 * debugging if no smb.conf. 627 * 628 * @return 0 on success, < 0 on error with errno set: 629 * - ENOMEM Out of memory 630 * - ENOENT The smb.conf file would not load 631 * 632 */ 633 634#ifdef __cplusplus 635extern "C" { 636#endif 637int smbc_init(smbc_get_auth_data_fn fn, int debug); 638#ifdef __cplusplus 639} 640#endif 641 642/**@ingroup misc 643 * Set or retrieve the compatibility library's context pointer 644 * 645 * @param context New context to use, or NULL. If a new context is provided, 646 * it must have allocated with smbc_new_context() and 647 * initialized with smbc_init_context(), followed, optionally, 648 * by some manual changes to some of the non-internal fields. 649 * 650 * @return The old context. 651 * 652 * @see smbc_new_context(), smbc_init_context(), smbc_init() 653 * 654 * @note This function may be called prior to smbc_init() to force 655 * use of the next context without any internal calls to 656 * smbc_new_context() or smbc_init_context(). It may also 657 * be called after smbc_init() has already called those two 658 * functions, to replace the existing context with a new one. 659 * Care should be taken, in this latter case, to ensure that 660 * the server cache and any data allocated by the 661 * authentication functions have been freed, if necessary. 662 */ 663 664#ifdef __cplusplus 665extern "C" { 666#endif 667SMBCCTX * smbc_set_context(SMBCCTX * new_context); 668#ifdef __cplusplus 669} 670#endif 671 672/**@ingroup file 673 * Open a file on an SMB server. 674 * 675 * @param furl The smb url of the file to be opened. 676 * 677 * @param flags Is one of O_RDONLY, O_WRONLY or O_RDWR which 678 * request opening the file read-only,write-only 679 * or read/write. flags may also be bitwise-or'd with 680 * one or more of the following: 681 * O_CREAT - If the file does not exist it will be 682 * created. 683 * O_EXCL - When used with O_CREAT, if the file 684 * already exists it is an error and the open will 685 * fail. 686 * O_TRUNC - If the file already exists it will be 687 * truncated. 688 * O_APPEND The file is opened in append mode 689 * 690 * @param mode mode specifies the permissions to use if a new 691 * file is created. It is modified by the 692 * process's umask in the usual way: the permissions 693 * of the created file are (mode & ~umask) 694 * 695 * Not currently use, but there for future use. 696 * We will map this to SYSTEM, HIDDEN, etc bits 697 * that reverses the mapping that smbc_fstat does. 698 * 699 * @return Valid file handle, < 0 on error with errno set: 700 * - ENOMEM Out of memory 701 * - EINVAL if an invalid parameter passed, like no 702 * file, or smbc_init not called. 703 * - EEXIST pathname already exists and O_CREAT and 704 * O_EXCL were used. 705 * - EISDIR pathname refers to a directory and 706 * the access requested involved writing. 707 * - EACCES The requested access to the file is not 708 * allowed 709 * - ENODEV The requested share does not exist 710 * - ENOTDIR A file on the path is not a directory 711 * - ENOENT A directory component in pathname does 712 * not exist. 713 * 714 * @see smbc_creat() 715 * 716 * @note This call uses an underlying routine that may create 717 * a new connection to the server specified in the URL. 718 * If the credentials supplied in the URL, or via the 719 * auth_fn in the smbc_init call, fail, this call will 720 * try again with an empty username and password. This 721 * often gets mapped to the guest account on some machines. 722 */ 723#ifdef __cplusplus 724extern "C" { 725#endif 726int smbc_open(const char *furl, int flags, mode_t mode); 727#ifdef __cplusplus 728} 729#endif 730 731/**@ingroup file 732 * Create a file on an SMB server. 733 * 734 * Same as calling smbc_open() with flags = O_CREAT|O_WRONLY|O_TRUNC 735 * 736 * @param furl The smb url of the file to be created 737 * 738 * @param mode mode specifies the permissions to use if a new 739 * file is created. It is modified by the 740 * process's umask in the usual way: the permissions 741 * of the created file are (mode & ~umask) 742 * 743 * NOTE, the above is not true. We are dealing with 744 * an SMB server, which has no concept of a umask! 745 * 746 * @return Valid file handle, < 0 on error with errno set: 747 * - ENOMEM Out of memory 748 * - EINVAL if an invalid parameter passed, like no 749 * file, or smbc_init not called. 750 * - EEXIST pathname already exists and O_CREAT and 751 * O_EXCL were used. 752 * - EISDIR pathname refers to a directory and 753 * the access requested involved writing. 754 * - EACCES The requested access to the file is not 755 * allowed 756 * - ENOENT A directory component in pathname does 757 * not exist. 758 * - ENODEV The requested share does not exist. 759 * @see smbc_open() 760 * 761 */ 762#ifdef __cplusplus 763extern "C" { 764#endif 765int smbc_creat(const char *furl, mode_t mode); 766#ifdef __cplusplus 767} 768#endif 769 770/**@ingroup file 771 * Read from a file using an opened file handle. 772 * 773 * @param fd Open file handle from smbc_open() or smbc_creat() 774 * 775 * @param buf Pointer to buffer to recieve read data 776 * 777 * @param bufsize Size of buf in bytes 778 * 779 * @return Number of bytes read, < 0 on error with errno set: 780 * - EISDIR fd refers to a directory 781 * - EBADF fd is not a valid file descriptor or 782 * is not open for reading. 783 * - EINVAL fd is attached to an object which is 784 * unsuitable for reading, or no buffer passed or 785 * smbc_init not called. 786 * 787 * @see smbc_open(), smbc_write() 788 * 789 */ 790#ifdef __cplusplus 791extern "C" { 792#endif 793ssize_t smbc_read(int fd, void *buf, size_t bufsize); 794#ifdef __cplusplus 795} 796#endif 797 798/**@ingroup file 799 * Write to a file using an opened file handle. 800 * 801 * @param fd Open file handle from smbc_open() or smbc_creat() 802 * 803 * @param buf Pointer to buffer to recieve read data 804 * 805 * @param bufsize Size of buf in bytes 806 * 807 * @return Number of bytes written, < 0 on error with errno set: 808 * - EISDIR fd refers to a directory. 809 * - EBADF fd is not a valid file descriptor or 810 * is not open for reading. 811 * - EINVAL fd is attached to an object which is 812 * unsuitable for reading, or no buffer passed or 813 * smbc_init not called. 814 * 815 * @see smbc_open(), smbc_read() 816 * 817 */ 818#ifdef __cplusplus 819extern "C" { 820#endif 821ssize_t smbc_write(int fd, void *buf, size_t bufsize); 822#ifdef __cplusplus 823} 824#endif 825 826/**@ingroup file 827 * Seek to a specific location in a file. 828 * 829 * @param fd Open file handle from smbc_open() or smbc_creat() 830 * 831 * @param offset Offset in bytes from whence 832 * 833 * @param whence A location in the file: 834 * - SEEK_SET The offset is set to offset bytes from 835 * the beginning of the file 836 * - SEEK_CUR The offset is set to current location 837 * plus offset bytes. 838 * - SEEK_END The offset is set to the size of the 839 * file plus offset bytes. 840 * 841 * @return Upon successful completion, lseek returns the 842 * resulting offset location as measured in bytes 843 * from the beginning of the file. Otherwise, a value 844 * of (off_t)-1 is returned and errno is set to 845 * indicate the error: 846 * - EBADF Fildes is not an open file descriptor. 847 * - EINVAL Whence is not a proper value or smbc_init 848 * not called. 849 * 850 * @todo Are all the whence values really supported? 851 * 852 * @todo Are errno values complete and correct? 853 */ 854#ifdef __cplusplus 855extern "C" { 856#endif 857off_t smbc_lseek(int fd, off_t offset, int whence); 858#ifdef __cplusplus 859} 860#endif 861 862/**@ingroup file 863 * Close an open file handle. 864 * 865 * @param fd The file handle to close 866 * 867 * @return 0 on success, < 0 on error with errno set: 868 * - EBADF fd isn't a valid open file descriptor 869 * - EINVAL smbc_init() failed or has not been called 870 * 871 * @see smbc_open(), smbc_creat() 872 */ 873#ifdef __cplusplus 874extern "C" { 875#endif 876int smbc_close(int fd); 877#ifdef __cplusplus 878} 879#endif 880 881/**@ingroup directory 882 * Unlink (delete) a file or directory. 883 * 884 * @param furl The smb url of the file to delete 885 * 886 * @return 0 on success, < 0 on error with errno set: 887 * - EACCES or EPERM Write access to the directory 888 * containing pathname is not allowed or one 889 * of the directories in pathname did not allow 890 * search (execute) permission 891 * - ENOENT A directory component in pathname does 892 * not exist 893 * - EINVAL NULL was passed in the file param or 894 * smbc_init not called. 895 * - EACCES You do not have access to the file 896 * - ENOMEM Insufficient kernel memory was available 897 * 898 * @see smbc_rmdir()s 899 * 900 * @todo Are errno values complete and correct? 901 */ 902#ifdef __cplusplus 903extern "C" { 904#endif 905int smbc_unlink(const char *furl); 906#ifdef __cplusplus 907} 908#endif 909 910/**@ingroup directory 911 * Rename or move a file or directory. 912 * 913 * @param ourl The original smb url (source url) of file or 914 * directory to be moved 915 * 916 * @param nurl The new smb url (destination url) of the file 917 * or directory after the move. Currently nurl must 918 * be on the same share as ourl. 919 * 920 * @return 0 on success, < 0 on error with errno set: 921 * - EISDIR nurl is an existing directory, but ourl is 922 * not a directory. 923 * - EEXIST nurl is a non-empty directory, 924 * i.e., contains entries other than "." and ".." 925 * - EINVAL The new url contained a path prefix 926 * of the old, or, more generally, an attempt was 927 * made to make a directory a subdirectory of itself 928 * or smbc_init not called. 929 * - ENOTDIR A component used as a directory in ourl 930 * or nurl path is not, in fact, a directory. Or, 931 * ourl is a directory, and newpath exists but is not 932 * a directory. 933 * - EACCES or EPERM Write access to the directory 934 * containing ourl or nurl is not allowed for the 935 * process's effective uid, or one of the 936 * directories in ourl or nurl did not allow search 937 * (execute) permission, or ourl was a directory 938 * and did not allow write permission. 939 * - ENOENT A directory component in ourl or nurl 940 * does not exist. 941 * - EXDEV Rename across shares not supported. 942 * - ENOMEM Insufficient kernel memory was available. 943 * - EEXIST The target file, nurl, already exists. 944 * 945 * 946 * @todo Are we going to support copying when urls are not on the same 947 * share? I say no... NOTE. I agree for the moment. 948 * 949 */ 950#ifdef __cplusplus 951extern "C" { 952#endif 953int smbc_rename(const char *ourl, const char *nurl); 954#ifdef __cplusplus 955} 956#endif 957 958/**@ingroup directory 959 * Open a directory used to obtain directory entries. 960 * 961 * @param durl The smb url of the directory to open 962 * 963 * @return Valid directory handle. < 0 on error with errno set: 964 * - EACCES Permission denied. 965 * - EINVAL A NULL file/URL was passed, or the URL would 966 * not parse, or was of incorrect form or smbc_init not 967 * called. 968 * - ENOENT durl does not exist, or name is an 969 * - ENOMEM Insufficient memory to complete the 970 * operation. 971 * - ENOTDIR name is not a directory. 972 * - EPERM the workgroup could not be found. 973 * - ENODEV the workgroup or server could not be found. 974 * 975 * @see smbc_getdents(), smbc_readdir(), smbc_closedir() 976 * 977 */ 978#ifdef __cplusplus 979extern "C" { 980#endif 981int smbc_opendir(const char *durl); 982#ifdef __cplusplus 983} 984#endif 985 986/**@ingroup directory 987 * Close a directory handle opened by smbc_opendir(). 988 * 989 * @param dh Directory handle to close 990 * 991 * @return 0 on success, < 0 on error with errno set: 992 * - EBADF dh is an invalid directory handle 993 * 994 * @see smbc_opendir() 995 */ 996#ifdef __cplusplus 997extern "C" { 998#endif 999int smbc_closedir(int dh); 1000#ifdef __cplusplus 1001} 1002#endif 1003 1004/**@ingroup directory 1005 * Get multiple directory entries. 1006 * 1007 * smbc_getdents() reads as many dirent structures from the an open 1008 * directory handle into a specified memory area as will fit. 1009 * 1010 * @param dh Valid directory as returned by smbc_opendir() 1011 * 1012 * @param dirp pointer to buffer that will receive the directory 1013 * entries. 1014 * 1015 * @param count The size of the dirp buffer in bytes 1016 * 1017 * @returns If any dirents returned, return will indicate the 1018 * total size. If there were no more dirents available, 1019 * 0 is returned. < 0 indicates an error. 1020 * - EBADF Invalid directory handle 1021 * - EINVAL Result buffer is too small or smbc_init 1022 * not called. 1023 * - ENOENT No such directory. 1024 * @see , smbc_dirent, smbc_readdir(), smbc_open() 1025 * 1026 * @todo Are errno values complete and correct? 1027 * 1028 * @todo Add example code so people know how to parse buffers. 1029 */ 1030#ifdef __cplusplus 1031extern "C" { 1032#endif 1033int smbc_getdents(unsigned int dh, struct smbc_dirent *dirp, int count); 1034#ifdef __cplusplus 1035} 1036#endif 1037 1038/**@ingroup directory 1039 * Get a single directory entry. 1040 * 1041 * @param dh Valid directory as returned by smbc_opendir() 1042 * 1043 * @return A pointer to a smbc_dirent structure, or NULL if an 1044 * error occurs or end-of-directory is reached: 1045 * - EBADF Invalid directory handle 1046 * - EINVAL smbc_init() failed or has not been called 1047 * 1048 * @see smbc_dirent, smbc_getdents(), smbc_open() 1049 */ 1050#ifdef __cplusplus 1051extern "C" { 1052#endif 1053struct smbc_dirent* smbc_readdir(unsigned int dh); 1054#ifdef __cplusplus 1055} 1056#endif 1057 1058/**@ingroup directory 1059 * Get the current directory offset. 1060 * 1061 * smbc_telldir() may be used in conjunction with smbc_readdir() and 1062 * smbc_lseekdir(). 1063 * 1064 * @param dh Valid directory as returned by smbc_opendir() 1065 * 1066 * @return The current location in the directory stream or -1 1067 * if an error occur. The current location is not 1068 * an offset. Becuase of the implementation, it is a 1069 * handle that allows the library to find the entry 1070 * later. 1071 * - EBADF dh is not a valid directory handle 1072 * - EINVAL smbc_init() failed or has not been called 1073 * - ENOTDIR if dh is not a directory 1074 * 1075 * @see smbc_readdir() 1076 * 1077 */ 1078#ifdef __cplusplus 1079extern "C" { 1080#endif 1081off_t smbc_telldir(int dh); 1082#ifdef __cplusplus 1083} 1084#endif 1085 1086/**@ingroup directory 1087 * lseek on directories. 1088 * 1089 * smbc_lseekdir() may be used in conjunction with smbc_readdir() and 1090 * smbc_telldir(). (rewind by smbc_lseekdir(fd, NULL)) 1091 * 1092 * @param fd Valid directory as returned by smbc_opendir() 1093 * 1094 * @param offset The offset (as returned by smbc_telldir). Can be 1095 * NULL, in which case we will rewind 1096 * 1097 * @return 0 on success, -1 on failure 1098 * - EBADF dh is not a valid directory handle 1099 * - ENOTDIR if dh is not a directory 1100 * - EINVAL offset did not refer to a valid dirent or 1101 * smbc_init not called. 1102 * 1103 * @see smbc_telldir() 1104 * 1105 * 1106 * @todo In what does the reture and errno values mean? 1107 */ 1108#ifdef __cplusplus 1109extern "C" { 1110#endif 1111int smbc_lseekdir(int fd, off_t offset); 1112#ifdef __cplusplus 1113} 1114#endif 1115 1116/**@ingroup directory 1117 * Create a directory. 1118 * 1119 * @param durl The url of the directory to create 1120 * 1121 * @param mode Specifies the permissions to use. It is modified 1122 * by the process's umask in the usual way: the 1123 * permissions of the created file are (mode & ~umask). 1124 * 1125 * @return 0 on success, < 0 on error with errno set: 1126 * - EEXIST directory url already exists 1127 * - EACCES The parent directory does not allow write 1128 * permission to the process, or one of the directories 1129 * - ENOENT A directory component in pathname does not 1130 * exist. 1131 * - EINVAL NULL durl passed or smbc_init not called. 1132 * - ENOMEM Insufficient memory was available. 1133 * 1134 * @see smbc_rmdir() 1135 * 1136 */ 1137#ifdef __cplusplus 1138extern "C" { 1139#endif 1140int smbc_mkdir(const char *durl, mode_t mode); 1141#ifdef __cplusplus 1142} 1143#endif 1144 1145/**@ingroup directory 1146 * Remove a directory. 1147 * 1148 * @param durl The smb url of the directory to remove 1149 * 1150 * @return 0 on success, < 0 on error with errno set: 1151 * - EACCES or EPERM Write access to the directory 1152 * containing pathname was not allowed. 1153 * - EINVAL durl is NULL or smbc_init not called. 1154 * - ENOENT A directory component in pathname does not 1155 * exist. 1156 * - ENOTEMPTY directory contains entries. 1157 * - ENOMEM Insufficient kernel memory was available. 1158 * 1159 * @see smbc_mkdir(), smbc_unlink() 1160 * 1161 * @todo Are errno values complete and correct? 1162 */ 1163#ifdef __cplusplus 1164extern "C" { 1165#endif 1166int smbc_rmdir(const char *durl); 1167#ifdef __cplusplus 1168} 1169#endif 1170 1171/**@ingroup attribute 1172 * Get information about a file or directory. 1173 * 1174 * @param url The smb url to get information for 1175 * 1176 * @param st pointer to a buffer that will be filled with 1177 * standard Unix struct stat information. 1178 * 1179 * @return 0 on success, < 0 on error with errno set: 1180 * - ENOENT A component of the path file_name does not 1181 * exist. 1182 * - EINVAL a NULL url was passed or smbc_init not called. 1183 * - EACCES Permission denied. 1184 * - ENOMEM Out of memory 1185 * - ENOTDIR The target dir, url, is not a directory. 1186 * 1187 * @see Unix stat() 1188 * 1189 */ 1190#ifdef __cplusplus 1191extern "C" { 1192#endif 1193int smbc_stat(const char *url, struct stat *st); 1194#ifdef __cplusplus 1195} 1196#endif 1197 1198/**@ingroup attribute 1199 * Get file information via an file descriptor. 1200 * 1201 * @param fd Open file handle from smbc_open() or smbc_creat() 1202 * 1203 * @param st pointer to a buffer that will be filled with 1204 * standard Unix struct stat information. 1205 * 1206 * @return EBADF filedes is bad. 1207 * - EACCES Permission denied. 1208 * - EBADF fd is not a valid file descriptor 1209 * - EINVAL Problems occurred in the underlying routines 1210 * or smbc_init not called. 1211 * - ENOMEM Out of memory 1212 * 1213 * @see smbc_stat(), Unix stat() 1214 * 1215 */ 1216#ifdef __cplusplus 1217extern "C" { 1218#endif 1219int smbc_fstat(int fd, struct stat *st); 1220#ifdef __cplusplus 1221} 1222#endif 1223 1224/**@ingroup attribue 1225 * Change the ownership of a file or directory. 1226 * 1227 * @param url The smb url of the file or directory to change 1228 * ownership of. 1229 * 1230 * @param owner I have no idea? 1231 * 1232 * @param group I have not idea? 1233 * 1234 * @return 0 on success, < 0 on error with errno set: 1235 * - EPERM The effective UID does not match the owner 1236 * of the file, and is not zero; or the owner or group 1237 * were specified incorrectly. 1238 * - ENOENT The file does not exist. 1239 * - ENOMEM Insufficient was available. 1240 * - ENOENT file or directory does not exist 1241 * 1242 * @todo Are we actually going to be able to implement this function 1243 * 1244 * @todo How do we abstract owner and group uid and gid? 1245 * 1246 */ 1247#ifdef __cplusplus 1248extern "C" { 1249#endif 1250int smbc_chown(const char *url, uid_t owner, gid_t group); 1251#ifdef __cplusplus 1252} 1253#endif 1254 1255/**@ingroup attribute 1256 * Change the permissions of a file. 1257 * 1258 * @param url The smb url of the file or directory to change 1259 * permissions of 1260 * 1261 * @param mode The permissions to set: 1262 * - Put good explaination of permissions here! 1263 * 1264 * @return 0 on success, < 0 on error with errno set: 1265 * - EPERM The effective UID does not match the owner 1266 * of the file, and is not zero 1267 * - ENOENT The file does not exist. 1268 * - ENOMEM Insufficient was available. 1269 * - ENOENT file or directory does not exist 1270 * 1271 * @todo Actually implement this fuction? 1272 * 1273 * @todo Are errno values complete and correct? 1274 */ 1275#ifdef __cplusplus 1276extern "C" { 1277#endif 1278int smbc_chmod(const char *url, mode_t mode); 1279#ifdef __cplusplus 1280} 1281#endif 1282 1283/**@ingroup attribute 1284 * Change the last modification time on a file 1285 * 1286 * @param url The smb url of the file or directory to change 1287 * the modification time of 1288 * 1289 * @param tbuf A timeval structure which contains the desired 1290 * modification time. NOTE: Only the tv_sec field is 1291 * used. The tv_usec (microseconds) portion is ignored. 1292 * 1293 * @return 0 on success, < 0 on error with errno set: 1294 * - EINVAL The client library is not properly initialized 1295 * - EPERM Permission was denied. 1296 * 1297 */ 1298#ifdef __cplusplus 1299extern "C" { 1300#endif 1301int smbc_utimes(const char *url, struct timeval *tbuf); 1302#ifdef __cplusplus 1303} 1304#endif 1305 1306#ifdef HAVE_UTIME_H 1307/**@ingroup attribute 1308 * Change the last modification time on a file 1309 * 1310 * @param url The smb url of the file or directory to change 1311 * the modification time of 1312 * 1313 * @param utbuf A utimebuf structure which contains the desired 1314 * modification time. NOTE: Although the structure contains 1315 * an access time as well, the access time value is ignored. 1316 * 1317 * @return 0 on success, < 0 on error with errno set: 1318 * - EINVAL The client library is not properly initialized 1319 * - ENOMEM No memory was available for internal needs 1320 * - EPERM Permission was denied. 1321 * 1322 */ 1323#ifdef __cplusplus 1324extern "C" { 1325#endif 1326int smbc_utime(const char *fname, struct utimbuf *utbuf); 1327#ifdef __cplusplus 1328} 1329#endif 1330#endif 1331 1332/**@ingroup attribute 1333 * Set extended attributes for a file. This is used for modifying a file's 1334 * security descriptor (i.e. owner, group, and access control list) 1335 * 1336 * @param url The smb url of the file or directory to set extended 1337 * attributes for. 1338 * 1339 * @param name The name of an attribute to be changed. Names are of 1340 * one of the following forms: 1341 * 1342 * system.nt_sec_desc.<attribute name> 1343 * system.nt_sec_desc.* 1344 * system.nt_sec_desc.*+ 1345 * 1346 * where <attribute name> is one of: 1347 * 1348 * revision 1349 * owner 1350 * owner+ 1351 * group 1352 * group+ 1353 * acl:<name or sid> 1354 * acl+:<name or sid> 1355 * 1356 * In the forms "system.nt_sec_desc.*" and 1357 * "system.nt_sec_desc.*+", the asterisk and plus signs are 1358 * literal, i.e. the string is provided exactly as shown, and 1359 * the value parameter should contain a complete security 1360 * descriptor with name:value pairs separated by tabs, 1361 * commas, or newlines (not spaces!). 1362 * 1363 * The plus sign ('+') indicates that SIDs should be mapped 1364 * to names. Without the plus sign, SIDs are not mapped; 1365 * rather they are simply converted to a string format. 1366 * 1367 * @param value The value to be assigned to the specified attribute name. 1368 * This buffer should contain only the attribute value if the 1369 * name was of the "system.nt_sec_desc.<attribute_name>" 1370 * form. If the name was of the "system.nt_sec_desc.*" form 1371 * then a complete security descriptor, with name:value pairs 1372 * separated by tabs, commas, or newlines (not spaces!), 1373 * should be provided in this value buffer. A complete 1374 * security descriptor will contain one or more entries 1375 * selected from the following: 1376 * 1377 * REVISION:<revision number> 1378 * OWNER:<sid or name> 1379 * GROUP:<sid or name> 1380 * ACL:<sid or name>:<type>/<flags>/<mask> 1381 * 1382 * The revision of the ACL specifies the internal Windows NT 1383 * ACL revision for the security descriptor. If not specified 1384 * it defaults to 1. Using values other than 1 may cause 1385 * strange behaviour. 1386 * 1387 * The owner and group specify the owner and group sids for 1388 * the object. If the attribute name (either '*+' with a 1389 * complete security descriptor, or individual 'owner+' or 1390 * 'group+' attribute names) ended with a plus sign, the 1391 * specified name is resolved to a SID value, using the 1392 * server on which the file or directory resides. Otherwise, 1393 * the value should be provided in SID-printable format as 1394 * S-1-x-y-z, and is used directly. The <sid or name> 1395 * associated with the ACL: attribute should be provided 1396 * similarly. 1397 * 1398 * @param size The number of the bytes of data in the value buffer 1399 * 1400 * @param flags A bit-wise OR of zero or more of the following: 1401 * SMBC_XATTR_FLAG_CREATE - 1402 * fail if the named attribute already exists 1403 * SMBC_XATTR_FLAG_REPLACE - 1404 * fail if the attribute does not already exist 1405 * 1406 * If neither flag is specified, the specified attributes 1407 * will be added or replace existing attributes of the same 1408 * name, as necessary. 1409 * 1410 * @return 0 on success, < 0 on error with errno set: 1411 * - EINVAL The client library is not properly initialized 1412 * or one of the parameters is not of a correct 1413 * form 1414 * - ENOMEM No memory was available for internal needs 1415 * - EEXIST If the attribute already exists and the flag 1416 * SMBC_XATTR_FLAG_CREAT was specified 1417 * - ENOATTR If the attribute does not exist and the flag 1418 * SMBC_XATTR_FLAG_REPLACE was specified 1419 * - EPERM Permission was denied. 1420 * - ENOTSUP The referenced file system does not support 1421 * extended attributes 1422 * 1423 * @note Attribute names are compared in a case-insensitive 1424 * fashion. All of the following are equivalent, although 1425 * the all-lower-case name is the preferred format: 1426 * system.nt_sec_desc.owner 1427 * SYSTEM.NT_SEC_DESC.OWNER 1428 * sYsTeM.nt_sEc_desc.owNER 1429 * 1430 */ 1431#ifdef __cplusplus 1432extern "C" { 1433#endif 1434int smbc_setxattr(const char *url, 1435 const char *name, 1436 const void *value, 1437 size_t size, 1438 int flags); 1439#ifdef __cplusplus 1440} 1441#endif 1442 1443/**@ingroup attribute 1444 * Set extended attributes for a file. This is used for modifying a file's 1445 * security descriptor (i.e. owner, group, and access control list). The 1446 * POSIX function which this maps to would act on a symbolic link rather than 1447 * acting on what the symbolic link points to, but with no symbolic links in 1448 * SMB file systems, this function is functionally identical to 1449 * smbc_setxattr(). 1450 * 1451 * @param url The smb url of the file or directory to set extended 1452 * attributes for. 1453 * 1454 * @param name The name of an attribute to be changed. Names are of 1455 * one of the following forms: 1456 * 1457 * system.nt_sec_desc.<attribute name> 1458 * system.nt_sec_desc.* 1459 * system.nt_sec_desc.*+ 1460 * 1461 * where <attribute name> is one of: 1462 * 1463 * revision 1464 * owner 1465 * owner+ 1466 * group 1467 * group+ 1468 * acl:<name or sid> 1469 * acl+:<name or sid> 1470 * 1471 * In the forms "system.nt_sec_desc.*" and 1472 * "system.nt_sec_desc.*+", the asterisk and plus signs are 1473 * literal, i.e. the string is provided exactly as shown, and 1474 * the value parameter should contain a complete security 1475 * descriptor with name:value pairs separated by tabs, 1476 * commas, or newlines (not spaces!). 1477 * 1478 * The plus sign ('+') indicates that SIDs should be mapped 1479 * to names. Without the plus sign, SIDs are not mapped; 1480 * rather they are simply converted to a string format. 1481 * 1482 * @param value The value to be assigned to the specified attribute name. 1483 * This buffer should contain only the attribute value if the 1484 * name was of the "system.nt_sec_desc.<attribute_name>" 1485 * form. If the name was of the "system.nt_sec_desc.*" form 1486 * then a complete security descriptor, with name:value pairs 1487 * separated by tabs, commas, or newlines (not spaces!), 1488 * should be provided in this value buffer. A complete 1489 * security descriptor will contain one or more entries 1490 * selected from the following: 1491 * 1492 * REVISION:<revision number> 1493 * OWNER:<sid or name> 1494 * GROUP:<sid or name> 1495 * ACL:<sid or name>:<type>/<flags>/<mask> 1496 * 1497 * The revision of the ACL specifies the internal Windows NT 1498 * ACL revision for the security descriptor. If not specified 1499 * it defaults to 1. Using values other than 1 may cause 1500 * strange behaviour. 1501 * 1502 * The owner and group specify the owner and group sids for 1503 * the object. If the attribute name (either '*+' with a 1504 * complete security descriptor, or individual 'owner+' or 1505 * 'group+' attribute names) ended with a plus sign, the 1506 * specified name is resolved to a SID value, using the 1507 * server on which the file or directory resides. Otherwise, 1508 * the value should be provided in SID-printable format as 1509 * S-1-x-y-z, and is used directly. The <sid or name> 1510 * associated with the ACL: attribute should be provided 1511 * similarly. 1512 * 1513 * @param size The number of the bytes of data in the value buffer 1514 * 1515 * @param flags A bit-wise OR of zero or more of the following: 1516 * SMBC_XATTR_FLAG_CREATE - 1517 * fail if the named attribute already exists 1518 * SMBC_XATTR_FLAG_REPLACE - 1519 * fail if the attribute does not already exist 1520 * 1521 * If neither flag is specified, the specified attributes 1522 * will be added or replace existing attributes of the same 1523 * name, as necessary. 1524 * 1525 * @return 0 on success, < 0 on error with errno set: 1526 * - EINVAL The client library is not properly initialized 1527 * or one of the parameters is not of a correct 1528 * form 1529 * - ENOMEM No memory was available for internal needs 1530 * - EEXIST If the attribute already exists and the flag 1531 * SMBC_XATTR_FLAG_CREAT was specified 1532 * - ENOATTR If the attribute does not exist and the flag 1533 * SMBC_XATTR_FLAG_REPLACE was specified 1534 * - EPERM Permission was denied. 1535 * - ENOTSUP The referenced file system does not support 1536 * extended attributes 1537 * 1538 * @note Attribute names are compared in a case-insensitive 1539 * fashion. All of the following are equivalent, although 1540 * the all-lower-case name is the preferred format: 1541 * system.nt_sec_desc.owner 1542 * SYSTEM.NT_SEC_DESC.OWNER 1543 * sYsTeM.nt_sEc_desc.owNER 1544 * 1545 */ 1546#ifdef __cplusplus 1547extern "C" { 1548#endif 1549int smbc_lsetxattr(const char *url, 1550 const char *name, 1551 const void *value, 1552 size_t size, 1553 int flags); 1554#ifdef __cplusplus 1555} 1556#endif 1557 1558/**@ingroup attribute 1559 * Set extended attributes for a file. This is used for modifying a file's 1560 * security descriptor (i.e. owner, group, and access control list) 1561 * 1562 * @param fd A file descriptor associated with an open file (as 1563 * previously returned by smbc_open(), to get extended 1564 * attributes for. 1565 * 1566 * @param name The name of an attribute to be changed. Names are of 1567 * one of the following forms: 1568 * 1569 * system.nt_sec_desc.<attribute name> 1570 * system.nt_sec_desc.* 1571 * system.nt_sec_desc.*+ 1572 * 1573 * where <attribute name> is one of: 1574 * 1575 * revision 1576 * owner 1577 * owner+ 1578 * group 1579 * group+ 1580 * acl:<name or sid> 1581 * acl+:<name or sid> 1582 * 1583 * In the forms "system.nt_sec_desc.*" and 1584 * "system.nt_sec_desc.*+", the asterisk and plus signs are 1585 * literal, i.e. the string is provided exactly as shown, and 1586 * the value parameter should contain a complete security 1587 * descriptor with name:value pairs separated by tabs, 1588 * commas, or newlines (not spaces!). 1589 * 1590 * The plus sign ('+') indicates that SIDs should be mapped 1591 * to names. Without the plus sign, SIDs are not mapped; 1592 * rather they are simply converted to a string format. 1593 * 1594 * @param value The value to be assigned to the specified attribute name. 1595 * This buffer should contain only the attribute value if the 1596 * name was of the "system.nt_sec_desc.<attribute_name>" 1597 * form. If the name was of the "system.nt_sec_desc.*" form 1598 * then a complete security descriptor, with name:value pairs 1599 * separated by tabs, commas, or newlines (not spaces!), 1600 * should be provided in this value buffer. A complete 1601 * security descriptor will contain one or more entries 1602 * selected from the following: 1603 * 1604 * REVISION:<revision number> 1605 * OWNER:<sid or name> 1606 * GROUP:<sid or name> 1607 * ACL:<sid or name>:<type>/<flags>/<mask> 1608 * 1609 * The revision of the ACL specifies the internal Windows NT 1610 * ACL revision for the security descriptor. If not specified 1611 * it defaults to 1. Using values other than 1 may cause 1612 * strange behaviour. 1613 * 1614 * The owner and group specify the owner and group sids for 1615 * the object. If the attribute name (either '*+' with a 1616 * complete security descriptor, or individual 'owner+' or 1617 * 'group+' attribute names) ended with a plus sign, the 1618 * specified name is resolved to a SID value, using the 1619 * server on which the file or directory resides. Otherwise, 1620 * the value should be provided in SID-printable format as 1621 * S-1-x-y-z, and is used directly. The <sid or name> 1622 * associated with the ACL: attribute should be provided 1623 * similarly. 1624 * 1625 * @param size The number of the bytes of data in the value buffer 1626 * 1627 * @param flags A bit-wise OR of zero or more of the following: 1628 * SMBC_XATTR_FLAG_CREATE - 1629 * fail if the named attribute already exists 1630 * SMBC_XATTR_FLAG_REPLACE - 1631 * fail if the attribute does not already exist 1632 * 1633 * If neither flag is specified, the specified attributes 1634 * will be added or replace existing attributes of the same 1635 * name, as necessary. 1636 * 1637 * @return 0 on success, < 0 on error with errno set: 1638 * - EINVAL The client library is not properly initialized 1639 * or one of the parameters is not of a correct 1640 * form 1641 * - ENOMEM No memory was available for internal needs 1642 * - EEXIST If the attribute already exists and the flag 1643 * SMBC_XATTR_FLAG_CREAT was specified 1644 * - ENOATTR If the attribute does not exist and the flag 1645 * SMBC_XATTR_FLAG_REPLACE was specified 1646 * - EPERM Permission was denied. 1647 * - ENOTSUP The referenced file system does not support 1648 * extended attributes 1649 * 1650 * @note Attribute names are compared in a case-insensitive 1651 * fashion. All of the following are equivalent, although 1652 * the all-lower-case name is the preferred format: 1653 * system.nt_sec_desc.owner 1654 * SYSTEM.NT_SEC_DESC.OWNER 1655 * sYsTeM.nt_sEc_desc.owNER 1656 * 1657 */ 1658#ifdef __cplusplus 1659extern "C" { 1660#endif 1661int smbc_fsetxattr(int fd, 1662 const char *name, 1663 const void *value, 1664 size_t size, 1665 int flags); 1666#ifdef __cplusplus 1667} 1668#endif 1669 1670/**@ingroup attribute 1671 * Get extended attributes for a file. 1672 * 1673 * @param url The smb url of the file or directory to get extended 1674 * attributes for. 1675 * 1676 * @param name The name of an attribute to be retrieved. Names are of 1677 * one of the following forms: 1678 * 1679 * system.nt_sec_desc.<attribute name> 1680 * system.nt_sec_desc.* 1681 * system.nt_sec_desc.*+ 1682 * 1683 * where <attribute name> is one of: 1684 * 1685 * revision 1686 * owner 1687 * owner+ 1688 * group 1689 * group+ 1690 * acl:<name or sid> 1691 * acl+:<name or sid> 1692 * 1693 * In the forms "system.nt_sec_desc.*" and 1694 * "system.nt_sec_desc.*+", the asterisk and plus signs are 1695 * literal, i.e. the string is provided exactly as shown, and 1696 * the value parameter will return a complete security 1697 * descriptor with name:value pairs separated by tabs, 1698 * commas, or newlines (not spaces!). 1699 * 1700 * The plus sign ('+') indicates that SIDs should be mapped 1701 * to names. Without the plus sign, SIDs are not mapped; 1702 * rather they are simply converted to a string format. 1703 * 1704 * @param value A pointer to a buffer in which the value of the specified 1705 * attribute will be placed (unless size is zero). 1706 * 1707 * @param size The size of the buffer pointed to by value. This parameter 1708 * may also be zero, in which case the size of the buffer 1709 * required to hold the attribute value will be returned, 1710 * but nothing will be placed into the value buffer. 1711 * 1712 * @return 0 on success, < 0 on error with errno set: 1713 * - EINVAL The client library is not properly initialized 1714 * or one of the parameters is not of a correct 1715 * form 1716 * - ENOMEM No memory was available for internal needs 1717 * - EEXIST If the attribute already exists and the flag 1718 * SMBC_XATTR_FLAG_CREAT was specified 1719 * - ENOATTR If the attribute does not exist and the flag 1720 * SMBC_XATTR_FLAG_REPLACE was specified 1721 * - EPERM Permission was denied. 1722 * - ENOTSUP The referenced file system does not support 1723 * extended attributes 1724 * 1725 */ 1726#ifdef __cplusplus 1727extern "C" { 1728#endif 1729int smbc_getxattr(const char *url, 1730 const char *name, 1731 const void *value, 1732 size_t size); 1733#ifdef __cplusplus 1734} 1735#endif 1736 1737/**@ingroup attribute 1738 * Get extended attributes for a file. The POSIX function which this maps to 1739 * would act on a symbolic link rather than acting on what the symbolic link 1740 * points to, but with no symbolic links in SMB file systems, this function 1741 * is functionally identical to smbc_getxattr(). 1742 * 1743 * @param url The smb url of the file or directory to get extended 1744 * attributes for. 1745 * 1746 * @param name The name of an attribute to be retrieved. Names are of 1747 * one of the following forms: 1748 * 1749 * system.nt_sec_desc.<attribute name> 1750 * system.nt_sec_desc.* 1751 * system.nt_sec_desc.*+ 1752 * 1753 * where <attribute name> is one of: 1754 * 1755 * revision 1756 * owner 1757 * owner+ 1758 * group 1759 * group+ 1760 * acl:<name or sid> 1761 * acl+:<name or sid> 1762 * 1763 * In the forms "system.nt_sec_desc.*" and 1764 * "system.nt_sec_desc.*+", the asterisk and plus signs are 1765 * literal, i.e. the string is provided exactly as shown, and 1766 * the value parameter will return a complete security 1767 * descriptor with name:value pairs separated by tabs, 1768 * commas, or newlines (not spaces!). 1769 * 1770 * The plus sign ('+') indicates that SIDs should be mapped 1771 * to names. Without the plus sign, SIDs are not mapped; 1772 * rather they are simply converted to a string format. 1773 * 1774 * @param value A pointer to a buffer in which the value of the specified 1775 * attribute will be placed (unless size is zero). 1776 * 1777 * @param size The size of the buffer pointed to by value. This parameter 1778 * may also be zero, in which case the size of the buffer 1779 * required to hold the attribute value will be returned, 1780 * but nothing will be placed into the value buffer. 1781 * 1782 * @return 0 on success, < 0 on error with errno set: 1783 * - EINVAL The client library is not properly initialized 1784 * or one of the parameters is not of a correct 1785 * form 1786 * - ENOMEM No memory was available for internal needs 1787 * - EEXIST If the attribute already exists and the flag 1788 * SMBC_XATTR_FLAG_CREAT was specified 1789 * - ENOATTR If the attribute does not exist and the flag 1790 * SMBC_XATTR_FLAG_REPLACE was specified 1791 * - EPERM Permission was denied. 1792 * - ENOTSUP The referenced file system does not support 1793 * extended attributes 1794 * 1795 */ 1796#ifdef __cplusplus 1797extern "C" { 1798#endif 1799int smbc_lgetxattr(const char *url, 1800 const char *name, 1801 const void *value, 1802 size_t size); 1803#ifdef __cplusplus 1804} 1805#endif 1806 1807/**@ingroup attribute 1808 * Get extended attributes for a file. 1809 * 1810 * @param fd A file descriptor associated with an open file (as 1811 * previously returned by smbc_open(), to get extended 1812 * attributes for. 1813 * 1814 * @param name The name of an attribute to be retrieved. Names are of 1815 * one of the following forms: 1816 * 1817 * system.nt_sec_desc.<attribute name> 1818 * system.nt_sec_desc.* 1819 * system.nt_sec_desc.*+ 1820 * 1821 * where <attribute name> is one of: 1822 * 1823 * revision 1824 * owner 1825 * owner+ 1826 * group 1827 * group+ 1828 * acl:<name or sid> 1829 * acl+:<name or sid> 1830 * 1831 * In the forms "system.nt_sec_desc.*" and 1832 * "system.nt_sec_desc.*+", the asterisk and plus signs are 1833 * literal, i.e. the string is provided exactly as shown, and 1834 * the value parameter will return a complete security 1835 * descriptor with name:value pairs separated by tabs, 1836 * commas, or newlines (not spaces!). 1837 * 1838 * The plus sign ('+') indicates that SIDs should be mapped 1839 * to names. Without the plus sign, SIDs are not mapped; 1840 * rather they are simply converted to a string format. 1841 * 1842 * @param value A pointer to a buffer in which the value of the specified 1843 * attribute will be placed (unless size is zero). 1844 * 1845 * @param size The size of the buffer pointed to by value. This parameter 1846 * may also be zero, in which case the size of the buffer 1847 * required to hold the attribute value will be returned, 1848 * but nothing will be placed into the value buffer. 1849 * 1850 * @return 0 on success, < 0 on error with errno set: 1851 * - EINVAL The client library is not properly initialized 1852 * or one of the parameters is not of a correct 1853 * form 1854 * - ENOMEM No memory was available for internal needs 1855 * - EEXIST If the attribute already exists and the flag 1856 * SMBC_XATTR_FLAG_CREAT was specified 1857 * - ENOATTR If the attribute does not exist and the flag 1858 * SMBC_XATTR_FLAG_REPLACE was specified 1859 * - EPERM Permission was denied. 1860 * - ENOTSUP The referenced file system does not support 1861 * extended attributes 1862 * 1863 */ 1864#ifdef __cplusplus 1865extern "C" { 1866#endif 1867int smbc_fgetxattr(int fd, 1868 const char *name, 1869 const void *value, 1870 size_t size); 1871#ifdef __cplusplus 1872} 1873#endif 1874 1875/**@ingroup attribute 1876 * Remove extended attributes for a file. This is used for modifying a file's 1877 * security descriptor (i.e. owner, group, and access control list) 1878 * 1879 * @param url The smb url of the file or directory to remove the extended 1880 * attributes for. 1881 * 1882 * @param name The name of an attribute to be removed. Names are of 1883 * one of the following forms: 1884 * 1885 * system.nt_sec_desc.<attribute name> 1886 * system.nt_sec_desc.* 1887 * system.nt_sec_desc.*+ 1888 * 1889 * where <attribute name> is one of: 1890 * 1891 * revision 1892 * owner 1893 * owner+ 1894 * group 1895 * group+ 1896 * acl:<name or sid> 1897 * acl+:<name or sid> 1898 * 1899 * In the forms "system.nt_sec_desc.*" and 1900 * "system.nt_sec_desc.*+", the asterisk and plus signs are 1901 * literal, i.e. the string is provided exactly as shown, and 1902 * the value parameter will return a complete security 1903 * descriptor with name:value pairs separated by tabs, 1904 * commas, or newlines (not spaces!). 1905 * 1906 * The plus sign ('+') indicates that SIDs should be mapped 1907 * to names. Without the plus sign, SIDs are not mapped; 1908 * rather they are simply converted to a string format. 1909 * 1910 * @return 0 on success, < 0 on error with errno set: 1911 * - EINVAL The client library is not properly initialized 1912 * - ENOMEM No memory was available for internal needs 1913 * - EPERM Permission was denied. 1914 * - ENOTSUP The referenced file system does not support 1915 * extended attributes 1916 * 1917 */ 1918#ifdef __cplusplus 1919extern "C" { 1920#endif 1921int smbc_removexattr(const char *url, 1922 const char *name); 1923#ifdef __cplusplus 1924} 1925#endif 1926 1927/**@ingroup attribute 1928 * Remove extended attributes for a file. This is used for modifying a file's 1929 * security descriptor (i.e. owner, group, and access control list) The POSIX 1930 * function which this maps to would act on a symbolic link rather than acting 1931 * on what the symbolic link points to, but with no symbolic links in SMB file 1932 * systems, this function is functionally identical to smbc_removexattr(). 1933 * 1934 * @param url The smb url of the file or directory to remove the extended 1935 * attributes for. 1936 * 1937 * @param name The name of an attribute to be removed. Names are of 1938 * one of the following forms: 1939 * 1940 * system.nt_sec_desc.<attribute name> 1941 * system.nt_sec_desc.* 1942 * system.nt_sec_desc.*+ 1943 * 1944 * where <attribute name> is one of: 1945 * 1946 * revision 1947 * owner 1948 * owner+ 1949 * group 1950 * group+ 1951 * acl:<name or sid> 1952 * acl+:<name or sid> 1953 * 1954 * In the forms "system.nt_sec_desc.*" and 1955 * "system.nt_sec_desc.*+", the asterisk and plus signs are 1956 * literal, i.e. the string is provided exactly as shown, and 1957 * the value parameter will return a complete security 1958 * descriptor with name:value pairs separated by tabs, 1959 * commas, or newlines (not spaces!). 1960 * 1961 * The plus sign ('+') indicates that SIDs should be mapped 1962 * to names. Without the plus sign, SIDs are not mapped; 1963 * rather they are simply converted to a string format. 1964 * 1965 * @return 0 on success, < 0 on error with errno set: 1966 * - EINVAL The client library is not properly initialized 1967 * - ENOMEM No memory was available for internal needs 1968 * - EPERM Permission was denied. 1969 * - ENOTSUP The referenced file system does not support 1970 * extended attributes 1971 * 1972 */ 1973#ifdef __cplusplus 1974extern "C" { 1975#endif 1976int smbc_lremovexattr(const char *url, 1977 const char *name); 1978#ifdef __cplusplus 1979} 1980#endif 1981 1982/**@ingroup attribute 1983 * Remove extended attributes for a file. This is used for modifying a file's 1984 * security descriptor (i.e. owner, group, and access control list) 1985 * 1986 * @param fd A file descriptor associated with an open file (as 1987 * previously returned by smbc_open(), to get extended 1988 * attributes for. 1989 * 1990 * @param name The name of an attribute to be removed. Names are of 1991 * one of the following forms: 1992 * 1993 * system.nt_sec_desc.<attribute name> 1994 * system.nt_sec_desc.* 1995 * system.nt_sec_desc.*+ 1996 * 1997 * where <attribute name> is one of: 1998 * 1999 * revision 2000 * owner 2001 * owner+ 2002 * group 2003 * group+ 2004 * acl:<name or sid> 2005 * acl+:<name or sid> 2006 * 2007 * In the forms "system.nt_sec_desc.*" and 2008 * "system.nt_sec_desc.*+", the asterisk and plus signs are 2009 * literal, i.e. the string is provided exactly as shown, and 2010 * the value parameter will return a complete security 2011 * descriptor with name:value pairs separated by tabs, 2012 * commas, or newlines (not spaces!). 2013 * 2014 * The plus sign ('+') indicates that SIDs should be mapped 2015 * to names. Without the plus sign, SIDs are not mapped; 2016 * rather they are simply converted to a string format. 2017 * 2018 * @return 0 on success, < 0 on error with errno set: 2019 * - EINVAL The client library is not properly initialized 2020 * - ENOMEM No memory was available for internal needs 2021 * - EPERM Permission was denied. 2022 * - ENOTSUP The referenced file system does not support 2023 * extended attributes 2024 * 2025 */ 2026#ifdef __cplusplus 2027extern "C" { 2028#endif 2029int smbc_fremovexattr(int fd, 2030 const char *name); 2031#ifdef __cplusplus 2032} 2033#endif 2034 2035/**@ingroup attribute 2036 * List the supported extended attribute names associated with a file 2037 * 2038 * @param url The smb url of the file or directory to list the extended 2039 * attributes for. 2040 * 2041 * @param list A pointer to a buffer in which the list of attributes for 2042 * the specified file or directory will be placed (unless 2043 * size is zero). 2044 * 2045 * @param size The size of the buffer pointed to by list. This parameter 2046 * may also be zero, in which case the size of the buffer 2047 * required to hold all of the attribute names will be 2048 * returned, but nothing will be placed into the list buffer. 2049 * 2050 * @return 0 on success, < 0 on error with errno set: 2051 * - EINVAL The client library is not properly initialized 2052 * - ENOMEM No memory was available for internal needs 2053 * - EPERM Permission was denied. 2054 * - ENOTSUP The referenced file system does not support 2055 * extended attributes 2056 * 2057 * @note This function always returns all attribute names supported 2058 * by NT file systems, regardless of wether the referenced 2059 * file system supports extended attributes (e.g. a Windows 2060 * 2000 machine supports extended attributes if NTFS is used, 2061 * but not if FAT is used, and Windows 98 doesn't support 2062 * extended attributes at all. Whether this is a feature or 2063 * a bug is yet to be decided. 2064 */ 2065#ifdef __cplusplus 2066extern "C" { 2067#endif 2068int smbc_listxattr(const char *url, 2069 char *list, 2070 size_t size); 2071#ifdef __cplusplus 2072} 2073#endif 2074 2075/**@ingroup attribute 2076 * List the supported extended attribute names associated with a file The 2077 * POSIX function which this maps to would act on a symbolic link rather than 2078 * acting on what the symbolic link points to, but with no symbolic links in 2079 * SMB file systems, this function is functionally identical to 2080 * smbc_listxattr(). 2081 * 2082 * @param url The smb url of the file or directory to list the extended 2083 * attributes for. 2084 * 2085 * @param list A pointer to a buffer in which the list of attributes for 2086 * the specified file or directory will be placed (unless 2087 * size is zero). 2088 * 2089 * @param size The size of the buffer pointed to by list. This parameter 2090 * may also be zero, in which case the size of the buffer 2091 * required to hold all of the attribute names will be 2092 * returned, but nothing will be placed into the list buffer. 2093 * 2094 * @return 0 on success, < 0 on error with errno set: 2095 * - EINVAL The client library is not properly initialized 2096 * - ENOMEM No memory was available for internal needs 2097 * - EPERM Permission was denied. 2098 * - ENOTSUP The referenced file system does not support 2099 * extended attributes 2100 * 2101 * @note This function always returns all attribute names supported 2102 * by NT file systems, regardless of wether the referenced 2103 * file system supports extended attributes (e.g. a Windows 2104 * 2000 machine supports extended attributes if NTFS is used, 2105 * but not if FAT is used, and Windows 98 doesn't support 2106 * extended attributes at all. Whether this is a feature or 2107 * a bug is yet to be decided. 2108 */ 2109#ifdef __cplusplus 2110extern "C" { 2111#endif 2112int smbc_llistxattr(const char *url, 2113 char *list, 2114 size_t size); 2115#ifdef __cplusplus 2116} 2117#endif 2118 2119/**@ingroup attribute 2120 * List the supported extended attribute names associated with a file 2121 * 2122 * @param fd A file descriptor associated with an open file (as 2123 * previously returned by smbc_open(), to get extended 2124 * attributes for. 2125 * 2126 * @param list A pointer to a buffer in which the list of attributes for 2127 * the specified file or directory will be placed (unless 2128 * size is zero). 2129 * 2130 * @param size The size of the buffer pointed to by list. This parameter 2131 * may also be zero, in which case the size of the buffer 2132 * required to hold all of the attribute names will be 2133 * returned, but nothing will be placed into the list buffer. 2134 * 2135 * @return 0 on success, < 0 on error with errno set: 2136 * - EINVAL The client library is not properly initialized 2137 * - ENOMEM No memory was available for internal needs 2138 * - EPERM Permission was denied. 2139 * - ENOTSUP The referenced file system does not support 2140 * extended attributes 2141 * 2142 * @note This function always returns all attribute names supported 2143 * by NT file systems, regardless of wether the referenced 2144 * file system supports extended attributes (e.g. a Windows 2145 * 2000 machine supports extended attributes if NTFS is used, 2146 * but not if FAT is used, and Windows 98 doesn't support 2147 * extended attributes at all. Whether this is a feature or 2148 * a bug is yet to be decided. 2149 */ 2150#ifdef __cplusplus 2151extern "C" { 2152#endif 2153int smbc_flistxattr(int fd, 2154 char *list, 2155 size_t size); 2156#ifdef __cplusplus 2157} 2158#endif 2159 2160/**@ingroup print 2161 * Print a file given the name in fname. It would be a URL ... 2162 * 2163 * @param fname The URL of a file on a remote SMB server that the 2164 * caller wants printed 2165 * 2166 * @param printq The URL of the print share to print the file to. 2167 * 2168 * @return 0 on success, < 0 on error with errno set: 2169 * 2170 * - EINVAL fname or printq was NULL or smbc_init not 2171 * not called. 2172 * and errors returned by smbc_open 2173 * 2174 */ 2175#ifdef __cplusplus 2176extern "C" { 2177#endif 2178int smbc_print_file(const char *fname, const char *printq); 2179#ifdef __cplusplus 2180} 2181#endif 2182 2183/**@ingroup print 2184 * Open a print file that can be written to by other calls. This simply 2185 * does an smbc_open call after checking if there is a file name on the 2186 * URI. If not, a temporary name is added ... 2187 * 2188 * @param fname The URL of the print share to print to? 2189 * 2190 * @returns A file handle for the print file if successful. 2191 * Returns -1 if an error ocurred and errno has the values 2192 * - EINVAL fname was NULL or smbc_init not called. 2193 * - all errors returned by smbc_open 2194 * 2195 */ 2196#ifdef __cplusplus 2197extern "C" { 2198#endif 2199int smbc_open_print_job(const char *fname); 2200#ifdef __cplusplus 2201} 2202#endif 2203 2204/**@ingroup print 2205 * List the print jobs on a print share, for the moment, pass a callback 2206 * 2207 * @param purl The url of the print share to list the jobs of 2208 * 2209 * @param fn Callback function the receives printjob info 2210 * 2211 * @return 0 on success, < 0 on error with errno set: 2212 * - EINVAL fname was NULL or smbc_init not called 2213 * - EACCES ??? 2214 */ 2215#ifdef __cplusplus 2216extern "C" { 2217#endif 2218int smbc_list_print_jobs(const char *purl, smbc_list_print_job_fn fn); 2219#ifdef __cplusplus 2220} 2221#endif 2222 2223/**@ingroup print 2224 * Delete a print job 2225 * 2226 * @param purl Url of the print share 2227 * 2228 * @param id The id of the job to delete 2229 * 2230 * @return 0 on success, < 0 on error with errno set: 2231 * - EINVAL fname was NULL or smbc_init not called 2232 * 2233 * @todo what errno values are possible here? 2234 */ 2235#ifdef __cplusplus 2236extern "C" { 2237#endif 2238int smbc_unlink_print_job(const char *purl, int id); 2239#ifdef __cplusplus 2240} 2241#endif 2242 2243/**@ingroup callback 2244 * Remove a server from the cached server list it's unused. 2245 * 2246 * @param context pointer to smb context 2247 * 2248 * @param srv pointer to server to remove 2249 * 2250 * @return On success, 0 is returned. 1 is returned if the server could not 2251 * be removed. Also useable outside libsmbclient. 2252 */ 2253#ifdef __cplusplus 2254extern "C" { 2255#endif 2256int smbc_remove_unused_server(SMBCCTX * context, SMBCSRV * srv); 2257#ifdef __cplusplus 2258} 2259#endif 2260 2261/**@ingroup directory 2262 * Convert strings of %xx to their single character equivalent. 2263 * 2264 * @param dest A pointer to a buffer in which the resulting decoded 2265 * string should be placed. This may be a pointer to the 2266 * same buffer as src_segment. 2267 * 2268 * @param src A pointer to the buffer containing the URL to be decoded. 2269 * Any %xx sequences herein are converted to their single 2270 * character equivalent. Each 'x' must be a valid hexadecimal 2271 * digit, or that % sequence is left undecoded. 2272 * 2273 * @param max_dest_len 2274 * The size of the buffer pointed to by dest_segment. 2275 * 2276 * @return The number of % sequences which could not be converted 2277 * due to lack of two following hexadecimal digits. 2278 */ 2279#ifdef __cplusplus 2280extern "C" { 2281#endif 2282int 2283smbc_urldecode(char *dest, char * src, size_t max_dest_len); 2284#ifdef __cplusplus 2285} 2286#endif 2287 2288 2289/* 2290 * Convert any characters not specifically allowed in a URL into their %xx 2291 * equivalent. 2292 * 2293 * @param dest A pointer to a buffer in which the resulting encoded 2294 * string should be placed. Unlike smbc_urldecode(), this 2295 * must be a buffer unique from src. 2296 * 2297 * @param src A pointer to the buffer containing the string to be encoded. 2298 * Any character not specifically allowed in a URL is converted 2299 * into its hexadecimal value and encoded as %xx. 2300 * 2301 * @param max_dest_len 2302 * The size of the buffer pointed to by dest_segment. 2303 * 2304 * @returns The remaining buffer length. 2305 */ 2306#ifdef __cplusplus 2307extern "C" { 2308#endif 2309int 2310smbc_urlencode(char * dest, char * src, int max_dest_len); 2311#ifdef __cplusplus 2312} 2313#endif 2314 2315 2316/**@ingroup directory 2317 * Return the version of the linked Samba code, and thus the version of the 2318 * libsmbclient code. 2319 * 2320 * @return The version string. 2321 */ 2322#ifdef __cplusplus 2323extern "C" { 2324#endif 2325const char * 2326smbc_version(void); 2327#ifdef __cplusplus 2328} 2329#endif 2330 2331 2332#endif /* SMBCLIENT_H_INCLUDED */ 2333