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  ***/
  72 typedef SilcUInt32 SilcSFTPVersion;
  73
  74 /* SFTP protocol version */
  75 #define SILC_SFTP_PROTOCOL_VERSION       3
  76
  77 /****d* silcsftp/SilcSFTPAPI/SilcSFTPStatus
  78  *
  79  * NAME
  80  *
  81  *    typedef enum { ... } SilcSFTPStatus
  82  *
  83  * DESCRIPTION
  84  *
  85  *    SFTP protocol status types.  These enumerations is used to indicate
  86  *    the status of request.  The server can send these to the client when
  87  *    client has requested an operation.
  88  *
  89  * SOURCE
  90  */
  91 typedef enum {
  92   SILC_SFTP_STATUS_OK                  = 0,  /* Operation successful */
  93   SILC_SFTP_STATUS_EOF                 = 1,  /* No more data available */
  94   SILC_SFTP_STATUS_NO_SUCH_FILE        = 2,  /* File does not exist */
  95   SILC_SFTP_STATUS_PERMISSION_DENIED   = 3,  /* No sufficient permissions */
  96   SILC_SFTP_STATUS_FAILURE             = 4,  /* Operation failed */
  97   SILC_SFTP_STATUS_BAD_MESSAGE         = 5,  /* Bad message received */
  98   SILC_SFTP_STATUS_NO_CONNECTION       = 6,  /* No connection to remote */
  99   SILC_SFTP_STATUS_CONNECTION_LOST     = 7,  /* Connection lost to server */
 100   SILC_SFTP_STATUS_OP_UNSUPPORTED      = 8,  /* Operation unsupported */
 101   SILC_SFTP_STATUS_INVALID_HANDLE      = 9,  /* Invalid file handle */
 102   SILC_SFTP_STATUS_NO_SUCH_PATH        = 10, /* Path does not exist */
 103   SILC_SFTP_STATUS_FILE_ALREADY_EXIST  = 11, /* File already exists */
 104   SILC_SFTP_STATUS_WRITE_PROTECT       = 12, /* Read-only or protected */
 105   SILC_SFTP_STATUS_NO_MEDIA            = 13, /* No media available */
 106   SILC_SFTP_STATUS_NO_SPACE_ON_DEVICE  = 14, /* No space on device */
 107   SILC_SFTP_STATUS_QUOTA_EXCEEDED      = 15, /* Quota limit reached */
 108   SILC_SFTP_STATUS_UNKNOWN_PRINCIBLE   = 16, /* Unknown princible */
 109   SILC_SFTP_STATUS_LOCK_CONFLICT       = 17, /* File already locked */
 110   SILC_SFTP_STATUS_NOT_EMPTY           = 18, /* Directory not empty */
 111   SILC_SFTP_STATUS_NOT_A_DIRECTORY     = 19, /* Not a directory */
 112   SILC_SFTP_STATUS_INVALID_FILENAME    = 20, /* Invalid filename */
 113   SILC_SFTP_STATUS_LINK_LOOP           = 21, /* Too many symlinks */
 114   SILC_SFTP_STATUS_CANNOT_DELETE       = 22, /* Could not delete file */
 115   SILC_SFTP_STATUS_INVALID_PARAMETER   = 23, /* Invalid parameter */
 116   SILC_SFTP_STATUS_FILE_IS_A_DIRECTORY = 24, /* File is a directory file */
 117   SILC_SFTP_STATUS_BR_LOCK_CONFLICT    = 25, /* Byte range lock conflict */
 118   SILC_SFTP_STATUS_BR_LOCK_REFUSED     = 26, /* Byte range lock refused */
 119   SILC_SFTP_STATUS_DELETE_PENDING      = 27, /* File is being deleted */
 120   SILC_SFTP_STATUS_FILE_CORRUPT        = 28, /* File is corrupted */
 121 } SilcSFTPStatus;
 122 /***/
 123
 124 /****d* silcsftp/SilcSFTPAPI/SilcSFTPFileOperation
 125  *
 126  * NAME
 127  *
 128  *    typedef enum { ... } SilcSFTPFileOperation
 129  *
 130  * DESCRIPTION
 131  *
 132  *    SFTP protocol file operation flags.  These enumerations can be used
 133  *    by the client when client is opening an file, to indicate how it
 134  *    would like to open the file.
 135  *
 136  * SOURCE
 137  */
 138 typedef enum {
 139   SILC_SFTP_FXF_READ           = 0x00000001, /* Reading */
 140   SILC_SFTP_FXF_WRITE          = 0x00000002, /* Writing */
 141   SILC_SFTP_FXF_APPEND         = 0x00000004, /* Appending to end of file */
 142   SILC_SFTP_FXF_CREAT          = 0x00000008, /* Create if doesn't exist */
 143   SILC_SFTP_FXF_TRUNC          = 0x00000010, /* Truncate if exists */
 144   SILC_SFTP_FXF_EXCL           = 0x00000020, /* Don't create if exists */
 145 } SilcSFTPFileOperation;
 146 /***/
 147
 148 /****s* silcsftp/SilcSFTPAPI/SilcSFTPAttributes
 149  *
 150  * NAME
 151  *
 152  *    typedef struct { ... } *SilcSFTPAttributes, SilcSFTPAttributesStruct;
 153  *
 154  * DESCRIPTION
 155  *
 156  *    SFTP File attributes structure represents the attributes for a file.
 157  *    This structure can be used by the client to send attributes to the
 158  *    server, and by server to return file attributes to the client.
 159  *
 160  ***/
 161 typedef struct SilcSFTPAttributesObject {
 162   SilcUInt32 flags;             /* Flags to indicate present attributes */
 163   SilcUInt64 size;              /* Sife of the file in bytes */
 164   SilcUInt32 uid;               /* Unix user ID */
 165   SilcUInt32 gid;               /* Unix group ID */
 166   SilcUInt32 permissions;       /* POSIX file permission bitmask */
 167   SilcUInt32 atime;             /* Access time of file */
 168   SilcUInt32 mtime;             /* Modification time of file */
 169
 170   SilcUInt32 extended_count;    /* Extended type and data count */
 171   SilcBuffer *extended_type;
 172   SilcBuffer *extended_data;
 173 } *SilcSFTPAttributes, SilcSFTPAttributesStruct;
 174
 175 /****s* silcsftp/SilcSFTPAPI/SilcSFTPName
 176  *
 177  * NAME
 178  *
 179  *    typedef struct { ... } *SilcSFTPName, SilcSFTPNameStruct
 180  *
 181  * DESCRIPTION
 182  *
 183  *    SFTP Name structure represents the name reply received from the server.
 184  *    It includes the returned file(s) short and long file names and
 185  *    attributes for the file(s).  This is returned by the server for
 186  *    example when reading the contents of a directory.
 187  *
 188  ***/
 189 typedef struct SilcSFTPNameObject {
 190   char **filename;
 191   char **long_filename;
 192   SilcSFTPAttributes *attrs;
 193   SilcUInt32 count;                     /* Number of files */
 194 } *SilcSFTPName, SilcSFTPNameStruct;
 195
 196 /****s* silcsftp/SilcSFTPAPI/SilcSFTPHandle
 197  *
 198  * NAME
 199  *
 200  *    typedef struct SilcSFTPHandleStruct *SilcSFTPHandle;
 201  *
 202  * DESCRIPTION
 203  *
 204  *    This context represents an open file handle and is allocated by
 205  *    the library.  The application receives this context in the
 206  *    SilcSFTPHandleCallback function.
 207  *
 208  ***/
 209 typedef struct SilcSFTPHandleStruct *SilcSFTPHandle;
 210
 211 /****f* silcsftp/SilcSFTPAPI/SilcSFTPVersionCallback
 212  *
 213  * SYNOPSIS
 214  *
 215  *    typedef void (*SilcSFTPVersionCallback)(SilcSFTP sftp,
 216  *                                            SilcSFTPStatus status,
 217  *                                            SilcSFTPVersion version,
 218  *                                            void *context);
 219  *
 220  * DESCRIPTION
 221  *
 222  *    Version callback is called at the protocol initialization phase when
 223  *    the server returns the version of the protocol. The `version' indicates
 224  *    the version of the protocol.
 225  *
 226  ***/
 227 typedef void (*SilcSFTPVersionCallback)(SilcSFTP sftp,
 228                                         SilcSFTPStatus status,
 229                                         SilcSFTPVersion version,
 230                                         void *context);
 231
 232 /****f* silcsftp/SilcSFTPAPI/SilcSFTPErrorCallback
 233  *
 234  * SYNOPSIS
 235  *
 236  *    typedef void (*SilcSFTPErrorCallback)(SilcSFTP sftp,
 237  *                                          SilcSFTPStatus status,
 238  *                                          void *context);
 239  *
 240  * DESCRIPTION
 241  *
 242  *    Error callback is called if a connection error occurs during SFTP
 243  *    session.  If the connection or stream is closed this callback is
 244  *    called.  Other errors are delivered in other callbacks.  Only the
 245  *    SILC_SFTP_STATUS_EOF or SILC_SFTP_STATUS_NO_CONNECTION is delivered
 246  *    in this callback.
 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 `version_cb' 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.  The `error_cb' will be called
 411  *    in case a stream error occurs, such as end of stream.
 412  *
 413  ***/
 414 SilcSFTP silc_sftp_client_start(SilcStream stream,
 415                                 SilcSchedule schedule,
 416                                 SilcSFTPVersionCallback version_cb,
 417                                 SilcSFTPErrorCallback error_cb,
 418                                 void *context);
 419
 420 /****f* silcsftp/SilcSFTPAPI/silc_sftp_client_shutdown
 421  *
 422  * SYNOPSIS
 423  *
 424  *    void silc_sftp_client_shutdown(SilcSFTP sftp);
 425  *
 426  * DESCRIPTION
 427  *
 428  *    Shutdown's the SFTP client.  The caller is responsible of closing
 429  *    the associated stream.  The SFTP context is freed and is invalid after
 430  *    this function returns.
 431  *
 432  ***/
 433 void silc_sftp_client_shutdown(SilcSFTP sftp);
 434
 435 /****f* silcsftp/SilcSFTPAPI/silc_sftp_open
 436  *
 437  * SYNOPSIS
 438  *
 439  *    void silc_sftp_open(SilcSFTP sftp,
 440  *                        const char *filename,
 441  *                        SilcSFTPFileOperation pflags,
 442  *                        SilcSFTPAttributes attrs,
 443  *                        SilcSFTPHandleCallback callback,
 444  *                        void *context);
 445  *
 446  * DESCRIPTION
 447  *
 448  *    Open a file indicated by the `filename' with flags indicated by the
 449  *    `pflags', and with attributes indicated by the `attsr'.  Calls the
 450  *    `callback' to return the opened file handle.
 451  *
 452  ***/
 453 void silc_sftp_open(SilcSFTP sftp,
 454                     const char *filename,
 455                     SilcSFTPFileOperation pflags,
 456                     SilcSFTPAttributes attrs,
 457                     SilcSFTPHandleCallback callback,
 458                     void *context);
 459
 460 /****f* silcsftp/SilcSFTPAPI/silc_sftp_close
 461  *
 462  * SYNOPSIS
 463  *
 464  *    void silc_sftp_close(SilcSFTP sftp,
 465  *                         SilcSFTPHandle handle,
 466  *                         SilcSFTPStatusCallback callback,
 467  *                         void *context);
 468  *
 469  * DESCRIPTION
 470  *
 471  *    Closes the file indicated by the file handle `handle'.  Calls the
 472  *    `callback' to indicate the status of the closing.
 473  *
 474  ***/
 475 void silc_sftp_close(SilcSFTP sftp,
 476                      SilcSFTPHandle handle,
 477                      SilcSFTPStatusCallback callback,
 478                      void *context);
 479
 480 /****f* silcsftp/SilcSFTPAPI/silc_sftp_read
 481  *
 482  * SYNOPSIS
 483  *
 484  *    void silc_sftp_read(SilcSFTP sftp,
 485  *                        SilcSFTPHandle handle,
 486  *                        SilcUInt64 offset,
 487  *                        SilcUInt32 len,
 488  *                        SilcSFTPDataCallback callback,
 489  *                        void *context);
 490  *
 491  * DESCRIPTION
 492  *
 493  *    Reads data from the file indicated by the file handle `handle' starting
 494  *    from the offset of `offset' at most `len' bytes.  The `callback' is
 495  *    called to return the read data.
 496  *
 497  ***/
 498 void silc_sftp_read(SilcSFTP sftp,
 499                     SilcSFTPHandle handle,
 500                     SilcUInt64 offset,
 501                     SilcUInt32 len,
 502                     SilcSFTPDataCallback callback,
 503                     void *context);
 504
 505 /****f* silcsftp/SilcSFTPAPI/silc_sftp_write
 506  *
 507  * SYNOPSIS
 508  *
 509  *    void silc_sftp_write(SilcSFTP sftp,
 510  *                         SilcSFTPHandle handle,
 511  *                         SilcUInt64 offset,
 512  *                         const unsigned char *data,
 513  *                         SilcUInt32 data_len,
 514  *                         SilcSFTPStatusCallback callback,
 515  *                         void *context);
 516  *
 517  * DESCRIPTION
 518  *
 519  *    Writes to a file indicated by the file handle `handle' starting from
 520  *    offset of `offset' at most `data_len' bytes of `data'.  The `callback'
 521  *    is called to indicate the status of the writing.
 522  *
 523  ***/
 524 void silc_sftp_write(SilcSFTP sftp,
 525                      SilcSFTPHandle handle,
 526                      SilcUInt64 offset,
 527                      const unsigned char *data,
 528                      SilcUInt32 data_len,
 529                      SilcSFTPStatusCallback callback,
 530                      void *context);
 531
 532 /****f* silcsftp/SilcSFTPAPI/silc_sftp_remove
 533  *
 534  * SYNOPSIS
 535  *
 536  *    void silc_sftp_remove(SilcSFTP sftp,
 537  *                          const char *filename,
 538  *                          SilcSFTPStatusCallback callback,
 539  *                          void *context);
 540  *
 541  * DESCRIPTION
 542  *
 543  *    Removes a file indicated by the `filename'.  Calls the `callback'
 544  *    to indicate the status of the removing.
 545  *
 546  ***/
 547 void silc_sftp_remove(SilcSFTP sftp,
 548                       const char *filename,
 549                       SilcSFTPStatusCallback callback,
 550                       void *context);
 551
 552 /****f* silcsftp/SilcSFTPAPI/silc_sftp_rename
 553  *
 554  * SYNOPSIS
 555  *
 556  *    void silc_sftp_rename(SilcSFTP sftp,
 557  *                          const char *oldname,
 558  *                          const char *newname,
 559  *                          SilcSFTPStatusCallback callback,
 560  *                          void *context);
 561  *
 562  * DESCRIPTION
 563  *
 564  *    Renames a file indicated by the `oldname' to the name `newname'.  The
 565  *    `callback' is called to indicate the status of the renaming.
 566  *
 567  ***/
 568 void silc_sftp_rename(SilcSFTP sftp,
 569                       const char *oldname,
 570                       const char *newname,
 571                       SilcSFTPStatusCallback callback,
 572                       void *context);
 573
 574 /****f* silcsftp/SilcSFTPAPI/silc_sftp_mkdir
 575  *
 576  * SYNOPSIS
 577  *
 578  *    void silc_sftp_mkdir(SilcSFTP sftp,
 579  *                         const char *path,
 580  *                         SilcSFTPAttributes attrs,
 581  *                         SilcSFTPStatusCallback callback,
 582  *                         void *context);
 583  *
 584  * DESCRIPTION
 585  *
 586  *    Creates a new directory indicated by the `path' with attributes indicated
 587  *    by the `attrs'. The `callback' is called to indicate the status of the
 588  *    creation.
 589  *
 590  ***/
 591 void silc_sftp_mkdir(SilcSFTP sftp,
 592                      const char *path,
 593                      SilcSFTPAttributes attrs,
 594                      SilcSFTPStatusCallback callback,
 595                      void *context);
 596
 597 /****f* silcsftp/SilcSFTPAPI/silc_sftp_rmdir
 598  *
 599  * SYNOPSIS
 600  *
 601  *    void silc_sftp_rmdir(SilcSFTP sftp,
 602  *                         const char *path,
 603  *                         SilcSFTPStatusCallback callback,
 604  *                         void *context);
 605  *
 606  * DESCRIPTION
 607  *
 608  *    Removes a directory indicated by the `path' and calls the `callback'
 609  *    to indicate the status of the removal.
 610  *
 611  ***/
 612 void silc_sftp_rmdir(SilcSFTP sftp,
 613                      const char *path,
 614                      SilcSFTPStatusCallback callback,
 615                      void *context);
 616
 617 /****f* silcsftp/SilcSFTPAPI/silc_sftp_opendir
 618  *
 619  * SYNOPSIS
 620  *
 621  *    void silc_sftp_opendir(SilcSFTP sftp,
 622  *                           const char *path,
 623  *                           SilcSFTPHandleCallback callback,
 624  *                           void *context);
 625  *
 626  * DESCRIPTION
 627  *
 628  *    Opens a directory indicated by the `path'.  The `callback' is called
 629  *    to return the opened file handle.
 630  *
 631  ***/
 632 void silc_sftp_opendir(SilcSFTP sftp,
 633                        const char *path,
 634                        SilcSFTPHandleCallback callback,
 635                        void *context);
 636
 637 /****f* silcsftp/SilcSFTPAPI/silc_sftp_readdir
 638  *
 639  * SYNOPSIS
 640  *
 641  *    void silc_sftp_readdir(SilcSFTP sftp,
 642  *                           SilcSFTPHandle handle,
 643  *                           SilcSFTPNameCallback callback,
 644  *                           void *context);
 645  *
 646  * DESCRIPTION
 647  *
 648  *    Reads the contents of the directory indicated by the `handle' and
 649  *    calls the `callback' to return the read file(s) from the directory.
 650  *
 651  ***/
 652 void silc_sftp_readdir(SilcSFTP sftp,
 653                        SilcSFTPHandle handle,
 654                        SilcSFTPNameCallback callback,
 655                        void *context);
 656
 657 /****f* silcsftp/SilcSFTPAPI/silc_sftp_stat
 658  *
 659  * SYNOPSIS
 660  *
 661  *    void silc_sftp_stat(SilcSFTP sftp,
 662  *                        const char *path,
 663  *                        SilcSFTPAttrCallback callback,
 664  *                        void *context);
 665  *
 666  * DESCRIPTION
 667  *
 668  *    Gets the file attributes for a file indicated by the `path'. This
 669  *    will follow symbolic links also. Calls the `callback' to return the
 670  *    file attributes.
 671  *
 672  ***/
 673 void silc_sftp_stat(SilcSFTP sftp,
 674                     const char *path,
 675                     SilcSFTPAttrCallback callback,
 676                     void *context);
 677
 678 /****f* silcsftp/SilcSFTPAPI/silc_sftp_lstat
 679  *
 680  * SYNOPSIS
 681  *
 682  *    void silc_sftp_lstat(SilcSFTP sftp,
 683  *                         const char *path,
 684  *                         SilcSFTPAttrCallback callback,
 685  *                         void *context);
 686  *
 687  * DESCRIPTION
 688  *
 689  *    Gets the file attributes for a file indicated by the `path'. This
 690  *    will not follow symbolic links. Calls the `callback' to return the
 691  *    file attributes
 692  *
 693  ***/
 694 void silc_sftp_lstat(SilcSFTP sftp,
 695                      const char *path,
 696                      SilcSFTPAttrCallback callback,
 697                      void *context);
 698
 699 /****f* silcsftp/SilcSFTPAPI/silc_sftp_fstat
 700  *
 701  * SYNOPSIS
 702  *
 703  *    void silc_sftp_fstat(SilcSFTP fstp,
 704  *                         SilcSFTPHandle handle,
 705  *                         SilcSFTPAttrCallback callback,
 706  *                         void *context);
 707  *
 708  * DESCRIPTION
 709  *
 710  *    Gets a file attributes for a opened file indicated by the `handle'.
 711  *    Calls the `callback' to return the file attributes.
 712  *
 713  ***/
 714 void silc_sftp_fstat(SilcSFTP fstp,
 715                      SilcSFTPHandle handle,
 716                      SilcSFTPAttrCallback callback,
 717                      void *context);
 718
 719 /****f* silcsftp/SilcSFTPAPI/silc_sftp_setstat
 720  *
 721  * SYNOPSIS
 722  *
 723  *    void silc_sftp_setstat(SilcSFTP sftp,
 724  *                           const char *path,
 725  *                           SilcSFTPAttributes attrs,
 726  *                           SilcSFTPStatusCallback callback,
 727  *                           void *context);
 728  *
 729  * DESCRIPTION
 730  *
 731  *    Sets a file attributes to a file indicated by the `path' with the
 732  *    attributes indicated by the `attrs'.  Calls the `callback' to indicate
 733  *    the status of the setting.
 734  *
 735  ***/
 736 void silc_sftp_setstat(SilcSFTP sftp,
 737                        const char *path,
 738                        SilcSFTPAttributes attrs,
 739                        SilcSFTPStatusCallback callback,
 740                        void *context);
 741
 742 /****f* silcsftp/SilcSFTPAPI/silc_sftp_fsetstat
 743  *
 744  * SYNOPSIS
 745  *
 746  *    void silc_sftp_fsetstat(SilcSFTP sftp,
 747  *                            SilcSFTPHandle handle,
 748  *                            SilcSFTPAttributes attrs,
 749  *                            SilcSFTPStatusCallback callback,
 750  *                            void *context);
 751  *
 752  * DESCRIPTION
 753  *
 754  *    Sets a file attributes to a opened file indicated by the `handle' with
 755  *    the attributes indicated by the `attrs'.  Calls the `callback' to
 756  *    indicate the status of the setting.
 757  *
 758  ***/
 759 void silc_sftp_fsetstat(SilcSFTP sftp,
 760                         SilcSFTPHandle handle,
 761                         SilcSFTPAttributes attrs,
 762                         SilcSFTPStatusCallback callback,
 763                         void *context);
 764
 765 /****f* silcsftp/SilcSFTPAPI/silc_sftp_readlink
 766  *
 767  * SYNOPSIS
 768  *
 769  *    void silc_sftp_readlink(SilcSFTP sftp,
 770  *                            const char *path,
 771  *                            SilcSFTPNameCallback callback,
 772  *                            void *context);
 773  *
 774  * DESCRIPTION
 775  *
 776  *    Reads the target of a symbolic link indicated by the `path'.  The
 777  *    `callback' is called to return the target of the symbolic link.
 778  *
 779  ***/
 780 void silc_sftp_readlink(SilcSFTP sftp,
 781                         const char *path,
 782                         SilcSFTPNameCallback callback,
 783                         void *context);
 784
 785 /****f* silcsftp/SilcSFTPAPI/silc_sftp_symlink
 786  *
 787  * SYNOPSIS
 788  *
 789  *    void silc_sftp_symlink(SilcSFTP sftp,
 790  *                           const char *linkpath,
 791  *                           const char *targetpath,
 792  *                           SilcSFTPStatusCallback callback,
 793  *                           void *context);
 794  *
 795  * DESCRIPTION
 796  *
 797  *    Creates a new symbolic link indicated by the `linkpath' to the target
 798  *    indicated by the `targetpath'.  The `callback' is called to indicate
 799  *    the status of creation.
 800  *
 801  ***/
 802 void silc_sftp_symlink(SilcSFTP sftp,
 803                        const char *linkpath,
 804                        const char *targetpath,
 805                        SilcSFTPStatusCallback callback,
 806                        void *context);
 807
 808 /****f* silcsftp/SilcSFTPAPI/silc_sftp_realpath
 809  *
 810  * SYNOPSIS
 811  *
 812  *    void silc_sftp_realpath(SilcSFTP sftp,
 813  *                            const char *path,
 814  *                            SilcSFTPNameCallback callback,
 815  *                            void *context);
 816  *
 817  * DESCRIPTION
 818  *
 819  *    Canonicalizes the path indicated by the `path' to a absolute path.
 820  *    The `callback' is called to return the absolute path.
 821  *
 822  ***/
 823 void silc_sftp_realpath(SilcSFTP sftp,
 824                         const char *path,
 825                         SilcSFTPNameCallback callback,
 826                         void *context);
 827
 828 /****f* silcsftp/SilcSFTPAPI/silc_sftp_extended
 829  *
 830  * SYNOPSIS
 831  *
 832  *    void silc_sftp_extended(SilcSFTP sftp,
 833  *                            const char *request,
 834  *                            const unsigned char *data,
 835  *                            SilcUInt32 data_len,
 836  *                            SilcSFTPExtendedCallback callback,
 837  *                            void *context);
 838  *
 839  * DESCRIPTION
 840  *
 841  *    Performs an extended operation indicated by the `request' with
 842  *    optional extended operation data indicated by the `data'.  The callback
 843  *    is called to return any data associated with the extended request.
 844  *
 845  ***/
 846 void silc_sftp_extended(SilcSFTP sftp,
 847                         const char *request,
 848                         const unsigned char *data,
 849                         SilcUInt32 data_len,
 850                         SilcSFTPExtendedCallback callback,
 851                         void *context);
 852
 853
 854 /* SFTP Server Interface */
 855
 856 #include "silcsftp_fs.h"
 857
 858 /****f* silcsftp/SilcSFTPAPI/silc_sftp_server_start
 859  *
 860  * SYNOPSIS
 861  *
 862  *    SilcSFTP silc_sftp_server_start(SilcStream stream,
 863  *                                    SilcSchedule schedule,
 864  *                                    SilcSFTPErrorCallback error_cb,
 865  *                                    void *context,
 866  *                                    SilcSFTPFilesystem fs);
 867  *
 868  * DESCRIPTION
 869  *
 870  *    Starts SFTP server and returns a context to it.  This function returns
 871  *    the allocated SFTP server context or NULL on error.  The `stream' is
 872  *    the stream (connection) to the client.  The `error_cb' will be called
 873  *    when the `stream' is ended (SILC_SFTP_STATUS_EOF).  The caller is
 874  *    responsible of closing and destroying the `stream'.  The `fs' is the
 875  *    filesystem context allocated by the application.
 876  *
 877  ***/
 878 SilcSFTP silc_sftp_server_start(SilcStream stream,
 879                                 SilcSchedule schedule,
 880                                 SilcSFTPErrorCallback error_cb,
 881                                 void *context,
 882                                 SilcSFTPFilesystem fs);
 883
 884 /****f* silcsftp/SilcSFTPAPI/silc_sftp_server_shutdown
 885  *
 886  * SYNOPSIS
 887  *
 888  *    void silc_sftp_server_shutdown(SilcSFTP sftp);
 889  *
 890  * DESCRIPTION
 891  *
 892  *    Shutdown the SFTP server.  The caller is responsible of closing the
 893  *    associated stream.  The SFTP context is freed and is invalid after
 894  *    this function returns.
 895  *
 896  ***/
 897 void silc_sftp_server_shutdown(SilcSFTP sftp);
 898
 899 /****d* silcsftp/SilcSFTPAPI/SilcSFTPMonitors
 900  *
 901  * NAME
 902  *
 903  *    typedef enum { ... } SilcSFTPMonitors;
 904  *
 905  * DESCRIPTION
 906  *
 907  *    SFTP server monitor types. These can be masked together to monitor
 908  *    various client requests.
 909  *
 910  * SOURCE
 911  */
 912 typedef enum {
 913   SILC_SFTP_MONITOR_INIT        = 0x0001,
 914   SILC_SFTP_MONITOR_OPEN        = 0x0002,
 915   SILC_SFTP_MONITOR_CLOSE       = 0x0004,
 916   SILC_SFTP_MONITOR_READ        = 0x0008,
 917   SILC_SFTP_MONITOR_WRITE       = 0x0010,
 918   SILC_SFTP_MONITOR_REMOVE      = 0x0020,
 919   SILC_SFTP_MONITOR_RENAME      = 0x0040,
 920   SILC_SFTP_MONITOR_MKDIR       = 0x0080,
 921   SILC_SFTP_MONITOR_RMDIR       = 0x0100,
 922   SILC_SFTP_MONITOR_OPENDIR     = 0x0200,
 923   SILC_SFTP_MONITOR_READDIR     = 0x0400,
 924   SILC_SFTP_MONITOR_STAT        = 0x0800,
 925   SILC_SFTP_MONITOR_LSTAT       = 0x1000,
 926   SILC_SFTP_MONITOR_FSTAT       = 0x2000,
 927   SILC_SFTP_MONITOR_SETSTAT     = 0x4000,
 928   SILC_SFTP_MONITOR_FSETSTAT    = 0x8000,
 929   SILC_SFTP_MONITOR_READLINK    = 0x10000,
 930   SILC_SFTP_MONITOR_SYMLINK     = 0x20000,
 931   SILC_SFTP_MONITOR_REALPATH    = 0x40000,
 932   SILC_SFTP_MONITOR_EXTENDED    = 0x80000,
 933 } SilcSFTPMonitors;
 934 /***/
 935
 936 /****s* silcsftp/SilcSFTPAPI/SilcSFTPMonitorData
 937  *
 938  * NAME
 939  *
 940  *    typedef struct { ... } *SilcSFTPMonitorData, SilcSFTPMonitorDataStruct;
 941  *
 942  * DESCRIPTION
 943  *
 944  *    This structure includes the monitor type specific data.  The
 945  *    application can check what the client has requested from this
 946  *    structure.  See the comments below what data is available for what
 947  *    monitor type.
 948  *
 949  * SOURCE
 950  */
 951 typedef struct SilcSFTPMonitorDataObject {
 952   SilcSFTPVersion version;      /* _INIT */
 953   char *name;                   /* _OPEN, _REMOVE, _RENAME, _MKDIR,
 954                                    _RMDIR, _OPENDIR, _STAT, _LSTAT,
 955                                    _SETSTAT, _READLINK, _SYMLINK, _REALPATH */
 956   char *name2;                  /* _RENAME, _SYMLINK */
 957   SilcSFTPFileOperation pflags; /* _OPEN */
 958   SilcUInt64 offset;            /* _READ, _WRITE */
 959   SilcUInt32 data_len;          /* _READ, _WRITE */
 960   SilcSFTPName names;           /* _READDIR, _READLINK, _REALPATH */
 961 } *SilcSFTPMonitorData, SilcSFTPMonitorDataStruct;
 962 /***/
 963
 964 /****f* silcsftp/SilcSFTPAPI/SilcSFTPMonitor
 965  *
 966  * SYNOPSIS
 967  *
 968  *    typedef void (*SilcSFTPMonitor)(SilcSFTP sftp
 969  *                                    SilcSFTPMonitors type,
 970  *                                    const SilcSFTPMonitorData data,
 971  *                                    void *context);
 972  *
 973  * DESCRIPTION
 974  *
 975  *    Monitor callback that is called when an specified request is
 976  *    received from client.  The `type' is the requested type that
 977  *    was being monitored.
 978  *
 979  ***/
 980 typedef void (*SilcSFTPMonitor)(SilcSFTP sftp,
 981                                 SilcSFTPMonitors type,
 982                                 const SilcSFTPMonitorData data,
 983                                 void *context);
 984
 985 /****f* silcsftp/SilcSFTPAPI/silc_sftp_server_set_monitor
 986  *
 987  * SYNOPSIS
 988  *
 989  *    void silc_sftp_server_set_monitor(SilcSFTP sftp,
 990  *                                      SilcSFTPMonitors monitors,
 991  *                                      SilcSFTPMonitor monitor,
 992  *                                      void *context);
 993  *
 994  * DESCRIPTION
 995  *
 996  *    Sets monitor callback to monitor various request sent by a client.
 997  *    When request that has been set in the `monitors' is received the
 998  *    monitor callback will be called to notify the caller.
 999  *
1000  ***/
1001 void silc_sftp_server_set_monitor(SilcSFTP sftp,
1002                                   SilcSFTPMonitors monitors,
1003                                   SilcSFTPMonitor monitor,
1004                                   void *context);
1005
1006 #endif /* SILCSFTP_H */