lib/silcsftp/silcsftp.h

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