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