lib/silcsftp/silcsftp.h

   1 /*
   2
   3   silcsftp.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 2001 - 2007 Pekka Riikonen
   8
   9   This program is free software; you can redistribute it and/or modify
  10   it under the terms of the GNU General Public License as published by
  11   the Free Software Foundation; version 2 of the License.
  12
  13   This program is distributed in the hope that it will be useful,
  14   but WITHOUT ANY WARRANTY; without even the implied warranty of
  15   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16   GNU General Public License for more details.
  17
  18 */
  19
  20 #ifndef SILCSFTP_H
  21 #define SILCSFTP_H
  22
  23 /****h* silcsftp/SILC SFTP Interface
  24  *
  25  * DESCRIPTION
  26  *
  27  * SILC SFTP Interface is the implementation of the Secure File Transfer
  28  * Protocol (or SSH File Transfer Protocol).  The interface defines the SFTP
  29  * client and the SFTP server.  The SFTP is the mandatory file transfer
  30  * protocol in the SILC protocol, and when used in SILC the SFTP packets are
  31  * encapsulated into SILC packets.  The SFTP server implementation is
  32  * filesystem independent and generic interface is defined to represent
  33  * filesystem access.
  34  *
  35  * The SilcSFTP context is the actual SFTP client or SFTP server, and each
  36  * SFTP session should create its own SFTP context.
  37  *
  38  * The SILC SFTP library is a generic SFTP implementation and not directly
  39  * related to either SILC or SSH.  It could be used for any general purpose
  40  * SFTP application.
  41  *
  42  ***/
  43
  44 /****s* silcsftp/SilcSFTPAPI/SilcSFTP
  45  *
  46  * NAME
  47  *
  48  *    typedef struct SilcSFTPStruct *SilcSFTP;
  49  *
  50  * DESCRIPTION
  51  *
  52  *    This context is the actual SFTP client and SFTP server, and is
  53  *    allocated by silc_sftp_client_start or silc_sftp_server_start and
  54  *    given as argument usually to all silc_sftp_* functions.  It is freed
  55  *    by the silc_sftp_client_shutdown or silc_sftp_server_shutdown
  56  *    functions.
  57  *
  58  ***/
  59 typedef struct SilcSFTPStruct *SilcSFTP;
  60
  61 /****d* silcsftp/SilcSFTPAPI/SilcSFTPVersion
  62  *
  63  * NAME
  64  *
  65  *    typedef SilcUInt32 SilcSFTPVersion;
  66  *
  67  * DESCRIPTION
  68  *
  69  *    SFTP Version type.
  70  *
  71  * SOURCE
  72  */
  73 typedef SilcUInt32 SilcSFTPVersion;
  74 /***/
  75
  76 /* SFTP protocol version */
  77 #define SILC_SFTP_PROTOCOL_VERSION       3
  78
  79 /****d* silcsftp/SilcSFTPAPI/SilcSFTPStatus
  80  *
  81  * NAME
  82  *
  83  *    typedef enum { ... } SilcSFTPStatus
  84  *
  85  * DESCRIPTION
  86  *
  87  *    SFTP protocol status types.  These enumerations is used to indicate
  88  *    the status of request.  The server can send these to the client when
  89  *    client has requested an operation.
  90  *
  91  * SOURCE
  92  */
  93 typedef enum {
  94   SILC_SFTP_STATUS_OK                  = 0,  /* Operation successful */
  95   SILC_SFTP_STATUS_EOF                 = 1,  /* No more data available */
  96   SILC_SFTP_STATUS_NO_SUCH_FILE        = 2,  /* File does not exist */
  97   SILC_SFTP_STATUS_PERMISSION_DENIED   = 3,  /* No sufficient permissions */
  98   SILC_SFTP_STATUS_FAILURE             = 4,  /* Operation failed */
  99   SILC_SFTP_STATUS_BAD_MESSAGE         = 5,  /* Bad message received */
 100   SILC_SFTP_STATUS_NO_CONNECTION       = 6,  /* No connection to remote */
 101   SILC_SFTP_STATUS_CONNECTION_LOST     = 7,  /* Connection lost to server */
 102   SILC_SFTP_STATUS_OP_UNSUPPORTED      = 8,  /* Operation unsupported */
 103   SILC_SFTP_STATUS_INVALID_HANDLE      = 9,  /* Invalid file handle */
 104   SILC_SFTP_STATUS_NO_SUCH_PATH        = 10, /* Path does not exist */
 105   SILC_SFTP_STATUS_FILE_ALREADY_EXIST  = 11, /* File already exists */
 106   SILC_SFTP_STATUS_WRITE_PROTECT       = 12, /* Read-only or protected */
 107   SILC_SFTP_STATUS_NO_MEDIA            = 13, /* No media available */
 108   SILC_SFTP_STATUS_NO_SPACE_ON_DEVICE  = 14, /* No space on device */
 109   SILC_SFTP_STATUS_QUOTA_EXCEEDED      = 15, /* Quota limit reached */
 110   SILC_SFTP_STATUS_UNKNOWN_PRINCIBLE   = 16, /* Unknown princible */
 111   SILC_SFTP_STATUS_LOCK_CONFLICT       = 17, /* File already locked */
 112   SILC_SFTP_STATUS_NOT_EMPTY           = 18, /* Directory not empty */
 113   SILC_SFTP_STATUS_NOT_A_DIRECTORY     = 19, /* Not a directory */
 114   SILC_SFTP_STATUS_INVALID_FILENAME    = 20, /* Invalid filename */
 115   SILC_SFTP_STATUS_LINK_LOOP           = 21, /* Too many symlinks */
 116   SILC_SFTP_STATUS_CANNOT_DELETE       = 22, /* Could not delete file */
 117   SILC_SFTP_STATUS_INVALID_PARAMETER   = 23, /* Invalid parameter */
 118   SILC_SFTP_STATUS_FILE_IS_A_DIRECTORY = 24, /* File is a directory file */
 119   SILC_SFTP_STATUS_BR_LOCK_CONFLICT    = 25, /* Byte range lock conflict */
 120   SILC_SFTP_STATUS_BR_LOCK_REFUSED     = 26, /* Byte range lock refused */
 121   SILC_SFTP_STATUS_DELETE_PENDING      = 27, /* File is being deleted */
 122   SILC_SFTP_STATUS_FILE_CORRUPT        = 28, /* File is corrupted */
 123 } SilcSFTPStatus;
 124 /***/
 125
 126 /****d* silcsftp/SilcSFTPAPI/SilcSFTPFileOperation
 127  *
 128  * NAME
 129  *
 130  *    typedef enum { ... } SilcSFTPFileOperation
 131  *
 132  * DESCRIPTION
 133  *
 134  *    SFTP protocol file operation flags.  These enumerations can be used
 135  *    by the client when client is opening an file, to indicate how it
 136  *    would like to open the file.
 137  *
 138  * SOURCE
 139  */
 140 typedef enum {
 141   SILC_SFTP_FXF_READ           = 0x00000001, /* Reading */
 142   SILC_SFTP_FXF_WRITE          = 0x00000002, /* Writing */
 143   SILC_SFTP_FXF_APPEND         = 0x00000004, /* Appending to end of file */
 144   SILC_SFTP_FXF_CREAT          = 0x00000008, /* Create if doesn't exist */
 145   SILC_SFTP_FXF_TRUNC          = 0x00000010, /* Truncate if exists */
 146   SILC_SFTP_FXF_EXCL           = 0x00000020, /* Don't create if exists */
 147 } SilcSFTPFileOperation;
 148 /***/
 149
 150 /****s* silcsftp/SilcSFTPAPI/SilcSFTPAttributes
 151  *
 152  * NAME
 153  *
 154  *    typedef struct { ... } *SilcSFTPAttributes, SilcSFTPAttributesStruct;
 155  *
 156  * DESCRIPTION
 157  *
 158  *    SFTP File attributes structure represents the attributes for a file.
 159  *    This structure can be used by the client to send attributes to the
 160  *    server, and by server to return file attributes to the client.
 161  *
 162  ***/
 163 typedef struct {
 164   SilcUInt32 flags;             /* Flags to indicate present attributes */
 165   SilcUInt64 size;              /* Sife of the file in bytes */
 166   SilcUInt32 uid;               /* Unix user ID */
 167   SilcUInt32 gid;               /* Unix group ID */
 168   SilcUInt32 permissions;       /* POSIX file permission bitmask */
 169   SilcUInt32 atime;             /* Access time of file */
 170   SilcUInt32 mtime;             /* Modification time of file */
 171
 172   SilcUInt32 extended_count;    /* Extended type and data count */
 173   SilcBuffer *extended_type;
 174   SilcBuffer *extended_data;
 175 } *SilcSFTPAttributes, SilcSFTPAttributesStruct;
 176
 177 /****s* silcsftp/SilcSFTPAPI/SilcSFTPName
 178  *
 179  * NAME
 180  *
 181  *    typedef struct { ... } *SilcSFTPName, SilcSFTPNameStruct
 182  *
 183  * DESCRIPTION
 184  *
 185  *    SFTP Name structure represents the name reply received from the server.
 186  *    It includes the returned file(s) short and long file names and
 187  *    attributes for the file(s).  This is returned by the server for
 188  *    example when reading the contents of a directory.
 189  *
 190  ***/
 191 typedef struct {
 192   char **filename;
 193   char **long_filename;
 194   SilcSFTPAttributes *attrs;
 195   SilcUInt32 count;                     /* Number of files */
 196 } *SilcSFTPName, SilcSFTPNameStruct;
 197
 198 /****s* silcsftp/SilcSFTPAPI/SilcSFTPHandle
 199  *
 200  * NAME
 201  *
 202  *    typedef struct SilcSFTPHandleStruct *SilcSFTPHandle;
 203  *
 204  * DESCRIPTION
 205  *
 206  *    This context represents an open file handle and is allocated by
 207  *    the library.  The application receives this context in the
 208  *    SilcSFTPHandleCallback function.
 209  *
 210  ***/
 211 typedef struct SilcSFTPHandleStruct *SilcSFTPHandle;
 212
 213 /****f* silcsftp/SilcSFTPAPI/SilcSFTPVersionCallback
 214  *
 215  * SYNOPSIS
 216  *
 217  *    typedef void (*SilcSFTPVersionCallback)(SilcSFTP sftp,
 218  *                                            SilcSFTPStatus status,
 219  *                                            SilcSFTPVersion version,
 220  *                                            void *context);
 221  *
 222  * DESCRIPTION
 223  *
 224  *    Version callback is called at the protocol initialization phase when
 225  *    the server returns the version of the protocol. The `version' indicates
 226  *    the version of the protocol.
 227  *
 228  ***/
 229 typedef void (*SilcSFTPVersionCallback)(SilcSFTP sftp,
 230                                         SilcSFTPStatus status,
 231                                         SilcSFTPVersion version,
 232                                         void *context);
 233
 234 /****f* silcsftp/SilcSFTPAPI/SilcSFTPErrorCallback
 235  *
 236  * SYNOPSIS
 237  *
 238  *    typedef void (*SilcSFTPErrorCallback)(SilcSFTP sftp,
 239  *                                          SilcSFTPStatus status,
 240  *                                          void *context);
 241  *
 242  * DESCRIPTION
 243  *
 244  *    Error callback is called if a connection error occurs during SFTP
 245  *    session.  If the connection or stream is closed this callback is
 246  *    called.  Other errors are delivered in other callbacks.
 247  *
 248  ***/
 249 typedef void (*SilcSFTPErrorCallback)(SilcSFTP sftp,
 250                                       SilcSFTPStatus status,
 251                                       void *context);
 252
 253 /****f* silcsftp/SilcSFTPAPI/SilcSFTPStatusCallback
 254  *
 255  * SYNOPSIS
 256  *
 257  *    typedef void (*SilcSFTPStatusCallback)(SilcSFTP sftp,
 258  *                                           SilcSFTPStatus status,
 259  *                                           const char *message,
 260  *                                           const char *language_tag,
 261  *                                           void *context);
 262  *
 263  * DESCRIPTION
 264  *
 265  *    Status callback is called every time server returns a status packet
 266  *    for a request the client has made. The `status' indicates the type
 267  *    of the status.  The `message' is optional error message received from
 268  *    the server, in language indicated by the `language_tag'.  Both of
 269  *    these pointers may be NULL.
 270  *
 271  ***/
 272 typedef void (*SilcSFTPStatusCallback)(SilcSFTP sftp,
 273                                        SilcSFTPStatus status,
 274                                        const char *message,
 275                                        const char *language_tag,
 276                                        void *context);
 277
 278 /****f* silcsftp/SilcSFTPAPI/SilcSFTPHandleCallback
 279  *
 280  * SYNOPSIS
 281  *
 282  *    typedef void (*SilcSFTPHandleCallback)(SilcSFTP sftp,
 283  *                                           SilcSFTPStatus status,
 284  *                                           SilcSFTPHandle handle,
 285  *                                           void *context);
 286  *
 287  * DESCRIPTION
 288  *
 289  *    Handle callback is called when the server returns a handle to the
 290  *    client as a result of some request client has made.  The `handle'
 291  *    is the file handle and the application can use it to perform file
 292  *    operations for the handle. Each of the returned handle must be
 293  *    also closed at some point with silc_sftp_close.
 294  *
 295  ***/
 296 typedef void (*SilcSFTPHandleCallback)(SilcSFTP sftp,
 297                                        SilcSFTPStatus status,
 298                                        SilcSFTPHandle handle,
 299                                        void *context);
 300
 301 /****f* silcsftp/SilcSFTPAPI/SilcSFTPDataCallback
 302  *
 303  * SYNOPSIS
 304  *
 305  *    typedef void (*SilcSFTPDataCallback)(SilcSFTP sftp,
 306  *                                         SilcSFTPStatus status,
 307  *                                         const unsigned char *data,
 308  *                                         SilcUInt32 data_len,
 309  *                                         void *context);
 310  *
 311  * DESCRIPTION
 312  *
 313  *    Data callback is called when data packet is received from the server.
 314  *    This is called for example when application is reading a file from
 315  *    the server.  The `data' is the raw data of length of `data_len'.
 316  *
 317  ***/
 318 typedef void (*SilcSFTPDataCallback)(SilcSFTP sftp,
 319                                      SilcSFTPStatus status,
 320                                      const unsigned char *data,
 321                                      SilcUInt32 data_len,
 322                                      void *context);
 323
 324 /****f* silcsftp/SilcSFTPAPI/SilcSFTPNameCallback
 325  *
 326  * SYNOPSIS
 327  *
 328  *    typedef void (*SilcSFTPNameCallback)(SilcSFTP sftp,
 329  *                                         SilcSFTPStatus status,
 330  *                                         const SilcSFTPName name,
 331  *                                         void *context);
 332  *
 333  * DESCRIPTION
 334  *
 335  *    Name callback is called when directory is being read by the client.
 336  *    The server returns one or more file names in one reply.  These file
 337  *    names are saved in the `filename' structures with their short and
 338  *    long name format, and with file attributes.
 339  *
 340  ***/
 341 typedef void (*SilcSFTPNameCallback)(SilcSFTP sftp,
 342                                      SilcSFTPStatus status,
 343                                      const SilcSFTPName name,
 344                                      void *context);
 345
 346 /****f* silcsftp/SilcSFTPAPI/SilcSFTPAttrCallback
 347  *
 348  * SYNOPSIS
 349  *
 350  *    typedef void (*SilcSFTPAttrCallback)(SilcSFTP sftp,
 351  *                                         SilcSFTPStatus status,
 352  *                                         const SilcSFTPAttributes attrs,
 353  *                                         void *context);
 354  *
 355  * DESCRIPTION
 356  *
 357  *    Attributes callback is called when the server returns the attributes
 358  *    for a file the client has requested.  The attributes are saved in
 359  *    the `attrs' structure.
 360  *
 361  ***/
 362 typedef void (*SilcSFTPAttrCallback)(SilcSFTP sftp,
 363                                      SilcSFTPStatus status,
 364                                      const SilcSFTPAttributes attrs,
 365                                      void *context);
 366
 367 /****f* silcsftp/SilcSFTPAPI/SilcSFTPExtendedCallback
 368  *
 369  * SYNOPSIS
 370  *
 371  *    typedef void (*SilcSFTPExtendedCallback)(SilcSFTP sftp,
 372  *                                             SilcSFTPStatus status,
 373  *                                             const unsigned char *data,
 374  *                                             SilcUInt32 data_len,
 375  *                                             void *context);
 376  *
 377  * DESCRIPTION
 378  *
 379  *    Extended request callback is called when client sends extended
 380  *    request to the server. The `data' is arbitrary data returned by the
 381  *    server and its encoding is the extended request specific.
 382  *
 383  ***/
 384 typedef void (*SilcSFTPExtendedCallback)(SilcSFTP sftp,
 385                                          SilcSFTPStatus status,
 386                                          const unsigned char *data,
 387                                          SilcUInt32 data_len,
 388                                          void *context);
 389
 390
 391 /* SFTP Client Interface */
 392
 393 /****f* silcsftp/SilcSFTPAPI/silc_sftp_client_start
 394  *
 395  * SYNOPSIS
 396  *
 397  *    SilcSFTP silc_sftp_client_start(SilcStream stream,
 398  *                                    SilcSchedule schedule,
 399  *                                    SilcSFTPVersionCallback version_cb,
 400  *                                    SilcSFTPErrorCallback error_cb,
 401  *                                    void *context);
 402  *
 403  * DESCRIPTION
 404  *
 405  *    Starts SFTP client and returns context to it.  The version callback
 406  *    indicated by the `callback' will be called after the SFTP session has
 407  *    been started and server has returned the version of the protocol.  The
 408  *    SFTP client context is returned in the callback too.  This returns the
 409  *    allocated SFTP client context or NULL on error.  The `stream' will be
 410  *    used to read and write the SFTP packets.
 411  *
 412  ***/
 413 SilcSFTP silc_sftp_client_start(SilcStream stream,
 414                                 SilcSchedule schedule,
 415                                 SilcSFTPVersionCallback version_cb,
 416                                 SilcSFTPErrorCallback error_cb,
 417                                 void *context);
 418
 419 /****f* silcsftp/SilcSFTPAPI/silc_sftp_client_shutdown
 420  *
 421  * SYNOPSIS
 422  *
 423  *    void silc_sftp_client_shutdown(SilcSFTP sftp);
 424  *
 425  * DESCRIPTION
 426  *
 427  *    Shutdown's the SFTP client.  The caller is responsible of closing
 428  *    the associated socket connection.  The SFTP context is freed and is
 429  *    invalid after this function returns.
 430  *
 431  ***/
 432 void silc_sftp_client_shutdown(SilcSFTP sftp);
 433
 434 /****f* silcsftp/SilcSFTPAPI/silc_sftp_open
 435  *
 436  * SYNOPSIS
 437  *
 438  *    void silc_sftp_open(SilcSFTP sftp,
 439  *                        const char *filename,
 440  *                        SilcSFTPFileOperation pflags,
 441  *                        SilcSFTPAttributes attrs,
 442  *                        SilcSFTPHandleCallback callback,
 443  *                        void *context);
 444  *
 445  * DESCRIPTION
 446  *
 447  *    Open a file indicated by the `filename' with flags indicated by the
 448  *    `pflags', and with attributes indicated by the `attsr'.  Calls the
 449  *    `callback' to return the opened file handle.
 450  *
 451  ***/
 452 void silc_sftp_open(SilcSFTP sftp,
 453                     const char *filename,
 454                     SilcSFTPFileOperation pflags,
 455                     SilcSFTPAttributes attrs,
 456                     SilcSFTPHandleCallback callback,
 457                     void *context);
 458
 459 /****f* silcsftp/SilcSFTPAPI/silc_sftp_close
 460  *
 461  * SYNOPSIS
 462  *
 463  *    void silc_sftp_close(SilcSFTP sftp,
 464  *                         SilcSFTPHandle handle,
 465  *                         SilcSFTPStatusCallback callback,
 466  *                         void *context);
 467  *
 468  * DESCRIPTION
 469  *
 470  *    Closes the file indicated by the file handle `handle'.  Calls the
 471  *    `callback' to indicate the status of the closing.
 472  *
 473  ***/
 474 void silc_sftp_close(SilcSFTP sftp,
 475                      SilcSFTPHandle handle,
 476                      SilcSFTPStatusCallback callback,
 477                      void *context);
 478
 479 /****f* silcsftp/SilcSFTPAPI/silc_sftp_read
 480  *
 481  * SYNOPSIS
 482  *
 483  *    void silc_sftp_read(SilcSFTP sftp,
 484  *                        SilcSFTPHandle handle,
 485  *                        SilcUInt64 offset,
 486  *                        SilcUInt32 len,
 487  *                        SilcSFTPDataCallback callback,
 488  *                        void *context);
 489  *
 490  * DESCRIPTION
 491  *
 492  *    Reads data from the file indicated by the file handle `handle' starting
 493  *    from the offset of `offset' at most `len' bytes.  The `callback' is
 494  *    called to return the read data.
 495  *
 496  ***/
 497 void silc_sftp_read(SilcSFTP sftp,
 498                     SilcSFTPHandle handle,
 499                     SilcUInt64 offset,
 500                     SilcUInt32 len,
 501                     SilcSFTPDataCallback callback,
 502                     void *context);
 503
 504 /****f* silcsftp/SilcSFTPAPI/silc_sftp_write
 505  *
 506  * SYNOPSIS
 507  *
 508  *    void silc_sftp_write(SilcSFTP sftp,
 509  *                         SilcSFTPHandle handle,
 510  *                         SilcUInt64 offset,
 511  *                         const unsigned char *data,
 512  *                         SilcUInt32 data_len,
 513  *                         SilcSFTPStatusCallback callback,
 514  *                         void *context);
 515  *
 516  * DESCRIPTION
 517  *
 518  *    Writes to a file indicated by the file handle `handle' starting from
 519  *    offset of `offset' at most `data_len' bytes of `data'.  The `callback'
 520  *    is called to indicate the status of the writing.
 521  *
 522  ***/
 523 void silc_sftp_write(SilcSFTP sftp,
 524                      SilcSFTPHandle handle,
 525                      SilcUInt64 offset,
 526                      const unsigned char *data,
 527                      SilcUInt32 data_len,
 528                      SilcSFTPStatusCallback callback,
 529                      void *context);
 530
 531 /****f* silcsftp/SilcSFTPAPI/silc_sftp_remove
 532  *
 533  * SYNOPSIS
 534  *
 535  *    void silc_sftp_remove(SilcSFTP sftp,
 536  *                          const char *filename,
 537  *                          SilcSFTPStatusCallback callback,
 538  *                          void *context);
 539  *
 540  * DESCRIPTION
 541  *
 542  *    Removes a file indicated by the `filename'.  Calls the `callback'
 543  *    to indicate the status of the removing.
 544  *
 545  ***/
 546 void silc_sftp_remove(SilcSFTP sftp,
 547                       const char *filename,
 548                       SilcSFTPStatusCallback callback,
 549                       void *context);
 550
 551 /****f* silcsftp/SilcSFTPAPI/silc_sftp_rename
 552  *
 553  * SYNOPSIS
 554  *
 555  *    void silc_sftp_rename(SilcSFTP sftp,
 556  *                          const char *oldname,
 557  *                          const char *newname,
 558  *                          SilcSFTPStatusCallback callback,
 559  *                          void *context);
 560  *
 561  * DESCRIPTION
 562  *
 563  *    Renames a file indicated by the `oldname' to the name `newname'.  The
 564  *    `callback' is called to indicate the status of the renaming.
 565  *
 566  ***/
 567 void silc_sftp_rename(SilcSFTP sftp,
 568                       const char *oldname,
 569                       const char *newname,
 570                       SilcSFTPStatusCallback callback,
 571                       void *context);
 572
 573 /****f* silcsftp/SilcSFTPAPI/silc_sftp_mkdir
 574  *
 575  * SYNOPSIS
 576  *
 577  *    void silc_sftp_mkdir(SilcSFTP sftp,
 578  *                         const char *path,
 579  *                         SilcSFTPAttributes attrs,
 580  *                         SilcSFTPStatusCallback callback,
 581  *                         void *context);
 582  *
 583  * DESCRIPTION
 584  *
 585  *    Creates a new directory indicated by the `path' with attributes indicated
 586  *    by the `attrs'. The `callback' is called to indicate the status of the
 587  *    creation.
 588  *
 589  ***/
 590 void silc_sftp_mkdir(SilcSFTP sftp,
 591                      const char *path,
 592                      SilcSFTPAttributes attrs,
 593                      SilcSFTPStatusCallback callback,
 594                      void *context);
 595
 596 /****f* silcsftp/SilcSFTPAPI/silc_sftp_rmdir
 597  *
 598  * SYNOPSIS
 599  *
 600  *    void silc_sftp_rmdir(SilcSFTP sftp,
 601  *                         const char *path,
 602  *                         SilcSFTPStatusCallback callback,
 603  *                         void *context);
 604  *
 605  * DESCRIPTION
 606  *
 607  *    Removes a directory indicated by the `path' and calls the `callback'
 608  *    to indicate the status of the removal.
 609  *
 610  ***/
 611 void silc_sftp_rmdir(SilcSFTP sftp,
 612                      const char *path,
 613                      SilcSFTPStatusCallback callback,
 614                      void *context);
 615
 616 /****f* silcsftp/SilcSFTPAPI/silc_sftp_opendir
 617  *
 618  * SYNOPSIS
 619  *
 620  *    void silc_sftp_opendir(SilcSFTP sftp,
 621  *                           const char *path,
 622  *                           SilcSFTPHandleCallback callback,
 623  *                           void *context);
 624  *
 625  * DESCRIPTION
 626  *
 627  *    Opens a directory indicated by the `path'.  The `callback' is called
 628  *    to return the opened file handle.
 629  *
 630  ***/
 631 void silc_sftp_opendir(SilcSFTP sftp,
 632                        const char *path,
 633                        SilcSFTPHandleCallback callback,
 634                        void *context);
 635
 636 /****f* silcsftp/SilcSFTPAPI/silc_sftp_readdir
 637  *
 638  * SYNOPSIS
 639  *
 640  *    void silc_sftp_readdir(SilcSFTP sftp,
 641  *                           SilcSFTPHandle handle,
 642  *                           SilcSFTPNameCallback callback,
 643  *                           void *context);
 644  *
 645  * DESCRIPTION
 646  *
 647  *    Reads the contents of the directory indicated by the `handle' and
 648  *    calls the `callback' to return the read file(s) from the directory.
 649  *
 650  ***/
 651 void silc_sftp_readdir(SilcSFTP sftp,
 652                        SilcSFTPHandle handle,
 653                        SilcSFTPNameCallback callback,
 654                        void *context);
 655
 656 /****f* silcsftp/SilcSFTPAPI/silc_sftp_stat
 657  *
 658  * SYNOPSIS
 659  *
 660  *    void silc_sftp_stat(SilcSFTP sftp,
 661  *                        const char *path,
 662  *                        SilcSFTPAttrCallback callback,
 663  *                        void *context);
 664  *
 665  * DESCRIPTION
 666  *
 667  *    Gets the file attributes for a file indicated by the `path'. This
 668  *    will follow symbolic links also. Calls the `callback' to return the
 669  *    file attributes.
 670  *
 671  ***/
 672 void silc_sftp_stat(SilcSFTP sftp,
 673                     const char *path,
 674                     SilcSFTPAttrCallback callback,
 675                     void *context);
 676
 677 /****f* silcsftp/SilcSFTPAPI/silc_sftp_lstat
 678  *
 679  * SYNOPSIS
 680  *
 681  *    void silc_sftp_lstat(SilcSFTP sftp,
 682  *                         const char *path,
 683  *                         SilcSFTPAttrCallback callback,
 684  *                         void *context);
 685  *
 686  * DESCRIPTION
 687  *
 688  *    Gets the file attributes for a file indicated by the `path'. This
 689  *    will not follow symbolic links. Calls the `callback' to return the
 690  *    file attributes
 691  *
 692  ***/
 693 void silc_sftp_lstat(SilcSFTP sftp,
 694                      const char *path,
 695                      SilcSFTPAttrCallback callback,
 696                      void *context);
 697
 698 /****f* silcsftp/SilcSFTPAPI/silc_sftp_fstat
 699  *
 700  * SYNOPSIS
 701  *
 702  *    void silc_sftp_fstat(SilcSFTP fstp,
 703  *                         SilcSFTPHandle handle,
 704  *                         SilcSFTPAttrCallback callback,
 705  *                         void *context);
 706  *
 707  * DESCRIPTION
 708  *
 709  *    Gets a file attributes for a opened file indicated by the `handle'.
 710  *    Calls the `callback' to return the file attributes.
 711  *
 712  ***/
 713 void silc_sftp_fstat(SilcSFTP fstp,
 714                      SilcSFTPHandle handle,
 715                      SilcSFTPAttrCallback callback,
 716                      void *context);
 717
 718 /****f* silcsftp/SilcSFTPAPI/silc_sftp_setstat
 719  *
 720  * SYNOPSIS
 721  *
 722  *    void silc_sftp_setstat(SilcSFTP sftp,
 723  *                           const char *path,
 724  *                           SilcSFTPAttributes attrs,
 725  *                           SilcSFTPStatusCallback callback,
 726  *                           void *context);
 727  *
 728  * DESCRIPTION
 729  *
 730  *    Sets a file attributes to a file indicated by the `path' with the
 731  *    attributes indicated by the `attrs'.  Calls the `callback' to indicate
 732  *    the status of the setting.
 733  *
 734  ***/
 735 void silc_sftp_setstat(SilcSFTP sftp,
 736                        const char *path,
 737                        SilcSFTPAttributes attrs,
 738                        SilcSFTPStatusCallback callback,
 739                        void *context);
 740
 741 /****f* silcsftp/SilcSFTPAPI/silc_sftp_fsetstat
 742  *
 743  * SYNOPSIS
 744  *
 745  *    void silc_sftp_fsetstat(SilcSFTP sftp,
 746  *                            SilcSFTPHandle handle,
 747  *                            SilcSFTPAttributes attrs,
 748  *                            SilcSFTPStatusCallback callback,
 749  *                            void *context);
 750  *
 751  * DESCRIPTION
 752  *
 753  *    Sets a file attributes to a opened file indicated by the `handle' with
 754  *    the attributes indicated by the `attrs'.  Calls the `callback' to
 755  *    indicate the status of the setting.
 756  *
 757  ***/
 758 void silc_sftp_fsetstat(SilcSFTP sftp,
 759                         SilcSFTPHandle handle,
 760                         SilcSFTPAttributes attrs,
 761                         SilcSFTPStatusCallback callback,
 762                         void *context);
 763
 764 /****f* silcsftp/SilcSFTPAPI/silc_sftp_readlink
 765  *
 766  * SYNOPSIS
 767  *
 768  *    void silc_sftp_readlink(SilcSFTP sftp,
 769  *                            const char *path,
 770  *                            SilcSFTPNameCallback callback,
 771  *                            void *context);
 772  *
 773  * DESCRIPTION
 774  *
 775  *    Reads the target of a symbolic link indicated by the `path'.  The
 776  *    `callback' is called to return the target of the symbolic link.
 777  *
 778  ***/
 779 void silc_sftp_readlink(SilcSFTP sftp,
 780                         const char *path,
 781                         SilcSFTPNameCallback callback,
 782                         void *context);
 783
 784 /****f* silcsftp/SilcSFTPAPI/silc_sftp_symlink
 785  *
 786  * SYNOPSIS
 787  *
 788  *    void silc_sftp_symlink(SilcSFTP sftp,
 789  *                           const char *linkpath,
 790  *                           const char *targetpath,
 791  *                           SilcSFTPStatusCallback callback,
 792  *                           void *context);
 793  *
 794  * DESCRIPTION
 795  *
 796  *    Creates a new symbolic link indicated by the `linkpath' to the target
 797  *    indicated by the `targetpath'.  The `callback' is called to indicate
 798  *    the status of creation.
 799  *
 800  ***/
 801 void silc_sftp_symlink(SilcSFTP sftp,
 802                        const char *linkpath,
 803                        const char *targetpath,
 804                        SilcSFTPStatusCallback callback,
 805                        void *context);
 806
 807 /****f* silcsftp/SilcSFTPAPI/silc_sftp_realpath
 808  *
 809  * SYNOPSIS
 810  *
 811  *    void silc_sftp_realpath(SilcSFTP sftp,
 812  *                            const char *path,
 813  *                            SilcSFTPNameCallback callback,
 814  *                            void *context);
 815  *
 816  * DESCRIPTION
 817  *
 818  *    Canonicalizes the path indicated by the `path' to a absolute path.
 819  *    The `callback' is called to return the absolute path.
 820  *
 821  ***/
 822 void silc_sftp_realpath(SilcSFTP sftp,
 823                         const char *path,
 824                         SilcSFTPNameCallback callback,
 825                         void *context);
 826
 827 /****f* silcsftp/SilcSFTPAPI/silc_sftp_extended
 828  *
 829  * SYNOPSIS
 830  *
 831  *    void silc_sftp_extended(SilcSFTP sftp,
 832  *                            const char *request,
 833  *                            const unsigned char *data,
 834  *                            SilcUInt32 data_len,
 835  *                            SilcSFTPExtendedCallback callback,
 836  *                            void *context);
 837  *
 838  * DESCRIPTION
 839  *
 840  *    Performs an extended operation indicated by the `request' with
 841  *    optional extended operation data indicated by the `data'.  The callback
 842  *    is called to return any data associated with the extended request.
 843  *
 844  ***/
 845 void silc_sftp_extended(SilcSFTP sftp,
 846                         const char *request,
 847                         const unsigned char *data,
 848                         SilcUInt32 data_len,
 849                         SilcSFTPExtendedCallback callback,
 850                         void *context);
 851
 852
 853 /* SFTP Server Interface */
 854
 855 #include "silcsftp_fs.h"
 856
 857 /****f* silcsftp/SilcSFTPAPI/silc_sftp_server_start
 858  *
 859  * SYNOPSIS
 860  *
 861  *    SilcSFTP silc_sftp_server_start(SilcStream stream,
 862  *                                    SilcSchedule schedule,
 863  *                                    SilcSFTPErrorCallback error_cb,
 864  *                                    void *context,
 865  *                                    SilcSFTPFilesystem fs);
 866  *
 867  * DESCRIPTION
 868  *
 869  *    Starts SFTP server and returns a context to it.  This function returns
 870  *    the allocated SFTP server context or NULL on error. The `send_packet'
 871  *    is called by the library when it needs to send a packet. The `fs' is the
 872  *    filesystem context allocated by the application.  Each socket connection
 873  *    should start its own server by calling this function.
 874  *
 875  ***/
 876 SilcSFTP silc_sftp_server_start(SilcStream stream,
 877                                 SilcSchedule schedule,
 878                                 SilcSFTPErrorCallback error_cb,
 879                                 void *context,
 880                                 SilcSFTPFilesystem fs);
 881
 882 /****f* silcsftp/SilcSFTPAPI/silc_sftp_server_shutdown
 883  *
 884  * SYNOPSIS
 885  *
 886  *    void silc_sftp_server_shutdown(SilcSFTP sftp);
 887  *
 888  * DESCRIPTION
 889  *
 890  *    Shutdown's the SFTP server.  The caller is responsible of closing
 891  *    the associated socket connection.  The SFTP context is freed and is
 892  *    invalid after this function returns.
 893  *
 894  ***/
 895 void silc_sftp_server_shutdown(SilcSFTP sftp);
 896
 897 /****d* silcsftp/SilcSFTPAPI/SilcSFTPMonitors
 898  *
 899  * NAME
 900  *
 901  *    typedef enum { ... } SilcSFTPMonitors;
 902  *
 903  * DESCRIPTION
 904  *
 905  *    SFTP server monitor types. These can be masked together to monitor
 906  *    various client requests.
 907  *
 908  * SOURCE
 909  */
 910 typedef enum {
 911   SILC_SFTP_MONITOR_INIT        = 0x0001,
 912   SILC_SFTP_MONITOR_OPEN        = 0x0002,
 913   SILC_SFTP_MONITOR_CLOSE       = 0x0004,
 914   SILC_SFTP_MONITOR_READ        = 0x0008,
 915   SILC_SFTP_MONITOR_WRITE       = 0x0010,
 916   SILC_SFTP_MONITOR_REMOVE      = 0x0020,
 917   SILC_SFTP_MONITOR_RENAME      = 0x0040,
 918   SILC_SFTP_MONITOR_MKDIR       = 0x0080,
 919   SILC_SFTP_MONITOR_RMDIR       = 0x0100,
 920   SILC_SFTP_MONITOR_OPENDIR     = 0x0200,
 921   SILC_SFTP_MONITOR_READDIR     = 0x0400,
 922   SILC_SFTP_MONITOR_STAT        = 0x0800,
 923   SILC_SFTP_MONITOR_LSTAT       = 0x1000,
 924   SILC_SFTP_MONITOR_FSTAT       = 0x2000,
 925   SILC_SFTP_MONITOR_SETSTAT     = 0x4000,
 926   SILC_SFTP_MONITOR_FSETSTAT    = 0x8000,
 927   SILC_SFTP_MONITOR_READLINK    = 0x10000,
 928   SILC_SFTP_MONITOR_SYMLINK     = 0x20000,
 929   SILC_SFTP_MONITOR_REALPATH    = 0x40000,
 930   SILC_SFTP_MONITOR_EXTENDED    = 0x80000,
 931 } SilcSFTPMonitors;
 932 /***/
 933
 934 /****s* silcsftp/SilcSFTPAPI/SilcSFTPMonitorData
 935  *
 936  * NAME
 937  *
 938  *    typedef struct { ... } *SilcSFTPMonitorData, SilcSFTPMonitorDataStruct;
 939  *
 940  * DESCRIPTION
 941  *
 942  *    This structure includes the monitor type specific data.  The
 943  *    application can check what the client has requested from this
 944  *    structure.
 945  *
 946  * SOURCE
 947  */
 948 typedef struct {
 949   SilcSFTPVersion version;      /* _INIT */
 950   char *name;                   /* _OPEN, _REMOVE, _RENAME, _MKDIR,
 951                                    _RMDIR, _OPENDIR, _STAT, _LSTAT,
 952                                    _SETSTAT, _READLINK, _SYMLINK, _REALPATH */
 953   char *name2;                  /* _RENAME, _SYMLINK */
 954   SilcSFTPFileOperation pflags; /* _OPEN */
 955   SilcUInt64 offset;            /* _READ, _WRITE */
 956   SilcUInt32 data_len;          /* _READ, _WRITE */
 957   SilcSFTPName names;           /* _READDIR, _READLINK, _REALPATH */
 958 } *SilcSFTPMonitorData, SilcSFTPMonitorDataStruct;
 959 /***/
 960
 961 /****f* silcsftp/SilcSFTPAPI/SilcSFTPMonitor
 962  *
 963  * SYNOPSIS
 964  *
 965  *    typedef void (*SilcSFTPMonitor)(SilcSFTP sftp
 966  *                                    SilcSFTPMonitors type,
 967  *                                    const SilcSFTPMonitorData data,
 968  *                                    void *context);
 969  *
 970  * DESCRIPTION
 971  *
 972  *    Monitor callback that is called when an specified request is
 973  *    received from client.  The `type' is the requested type that
 974  *    was being monitored.
 975  *
 976  ***/
 977 typedef void (*SilcSFTPMonitor)(SilcSFTP sftp,
 978                                 SilcSFTPMonitors type,
 979                                 const SilcSFTPMonitorData data,
 980                                 void *context);
 981
 982 /****f* silcsftp/SilcSFTPAPI/silc_sftp_server_set_monitor
 983  *
 984  * SYNOPSIS
 985  *
 986  *    void silc_sftp_server_set_monitor(SilcSFTP sftp,
 987  *                                      SilcSFTPMonitors monitors,
 988  *                                      SilcSFTPMonitor monitor,
 989  *                                      void *context);
 990  *
 991  * DESCRIPTION
 992  *
 993  *    Sets monitor callback to monitor various request sent by a client.
 994  *    When request that has been set in the `monitors' is received the
 995  *    monitor callback will be called to notify the caller.
 996  *
 997  ***/
 998 void silc_sftp_server_set_monitor(SilcSFTP sftp,
 999                                   SilcSFTPMonitors monitors,
1000                                   SilcSFTPMonitor monitor,
1001                                   void *context);
1002
1003 #endif /* SILCSFTP_H */