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(SilcStream stream,
 390  *                                    SilcSFTPVersionCallback callback,
 391  *                                    void *context);
 392  *
 393  * DESCRIPTION
 394  *
 395  *    Starts SFTP client and returns context to it.  The version callback
 396  *    indicated by the `callback' will be called after the SFTP session has
 397  *    been started and server has returned the version of the protocol.  The
 398  *    SFTP client context is returned in the callback too.  This returns the
 399  *    allocated SFTP client context or NULL on error.  The `stream' will be
 400  *    used to read from and write to the SFTP packets.
 401  *
 402  ***/
 403 SilcSFTP silc_sftp_client_start(SilcStream stream,
 404                                 SilcSFTPVersionCallback callback,
 405                                 void *context);
 406
 407 /****f* silcsftp/SilcSFTPAPI/silc_sftp_client_shutdown
 408  *
 409  * SYNOPSIS
 410  *
 411  *    void silc_sftp_client_shutdown(SilcSFTP sftp);
 412  *
 413  * DESCRIPTION
 414  *
 415  *    Shutdown's the SFTP client.  The caller is responsible of closing
 416  *    the associated socket connection.  The SFTP context is freed and is
 417  *    invalid after this function returns.
 418  *
 419  ***/
 420 void silc_sftp_client_shutdown(SilcSFTP sftp);
 421
 422 /****f* silcsftp/SilcSFTPAPI/silc_sftp_open
 423  *
 424  * SYNOPSIS
 425  *
 426  *    void silc_sftp_open(SilcSFTP sftp,
 427  *                        const char *filename,
 428  *                        SilcSFTPFileOperation pflags,
 429  *                        SilcSFTPAttributes attrs,
 430  *                        SilcSFTPHandleCallback callback,
 431  *                        void *context);
 432  *
 433  * DESCRIPTION
 434  *
 435  *    Open a file indicated by the `filename' with flags indicated by the
 436  *    `pflags', and with attributes indicated by the `attsr'.  Calls the
 437  *    `callback' to return the opened file handle.
 438  *
 439  ***/
 440 void silc_sftp_open(SilcSFTP sftp,
 441                     const char *filename,
 442                     SilcSFTPFileOperation pflags,
 443                     SilcSFTPAttributes attrs,
 444                     SilcSFTPHandleCallback callback,
 445                     void *context);
 446
 447 /****f* silcsftp/SilcSFTPAPI/silc_sftp_close
 448  *
 449  * SYNOPSIS
 450  *
 451  *    void silc_sftp_close(SilcSFTP sftp,
 452  *                         SilcSFTPHandle handle,
 453  *                         SilcSFTPStatusCallback callback,
 454  *                         void *context);
 455  *
 456  * DESCRIPTION
 457  *
 458  *    Closes the file indicated by the file handle `handle'.  Calls the
 459  *    `callback' to indicate the status of the closing.
 460  *
 461  ***/
 462 void silc_sftp_close(SilcSFTP sftp,
 463                      SilcSFTPHandle handle,
 464                      SilcSFTPStatusCallback callback,
 465                      void *context);
 466
 467 /****f* silcsftp/SilcSFTPAPI/silc_sftp_read
 468  *
 469  * SYNOPSIS
 470  *
 471  *    void silc_sftp_read(SilcSFTP sftp,
 472  *                        SilcSFTPHandle handle,
 473  *                        SilcUInt64 offset,
 474  *                        SilcUInt32 len,
 475  *                        SilcSFTPDataCallback callback,
 476  *                        void *context);
 477  *
 478  * DESCRIPTION
 479  *
 480  *    Reads data from the file indicated by the file handle `handle' starting
 481  *    from the offset of `offset' at most `len' bytes.  The `callback' is
 482  *    called to return the read data.
 483  *
 484  ***/
 485 void silc_sftp_read(SilcSFTP sftp,
 486                     SilcSFTPHandle handle,
 487                     SilcUInt64 offset,
 488                     SilcUInt32 len,
 489                     SilcSFTPDataCallback callback,
 490                     void *context);
 491
 492 /****f* silcsftp/SilcSFTPAPI/silc_sftp_write
 493  *
 494  * SYNOPSIS
 495  *
 496  *    void silc_sftp_write(SilcSFTP sftp,
 497  *                         SilcSFTPHandle handle,
 498  *                         SilcUInt64 offset,
 499  *                         const unsigned char *data,
 500  *                         SilcUInt32 data_len,
 501  *                         SilcSFTPStatusCallback callback,
 502  *                         void *context);
 503  *
 504  * DESCRIPTION
 505  *
 506  *    Writes to a file indicated by the file handle `handle' starting from
 507  *    offset of `offset' at most `data_len' bytes of `data'.  The `callback'
 508  *    is called to indicate the status of the writing.
 509  *
 510  ***/
 511 void silc_sftp_write(SilcSFTP sftp,
 512                      SilcSFTPHandle handle,
 513                      SilcUInt64 offset,
 514                      const unsigned char *data,
 515                      SilcUInt32 data_len,
 516                      SilcSFTPStatusCallback callback,
 517                      void *context);
 518
 519 /****f* silcsftp/SilcSFTPAPI/silc_sftp_remove
 520  *
 521  * SYNOPSIS
 522  *
 523  *    void silc_sftp_remove(SilcSFTP sftp,
 524  *                          const char *filename,
 525  *                          SilcSFTPStatusCallback callback,
 526  *                          void *context);
 527  *
 528  * DESCRIPTION
 529  *
 530  *    Removes a file indicated by the `filename'.  Calls the `callback'
 531  *    to indicate the status of the removing.
 532  *
 533  ***/
 534 void silc_sftp_remove(SilcSFTP sftp,
 535                       const char *filename,
 536                       SilcSFTPStatusCallback callback,
 537                       void *context);
 538
 539 /****f* silcsftp/SilcSFTPAPI/silc_sftp_rename
 540  *
 541  * SYNOPSIS
 542  *
 543  *    void silc_sftp_rename(SilcSFTP sftp,
 544  *                          const char *oldname,
 545  *                          const char *newname,
 546  *                          SilcSFTPStatusCallback callback,
 547  *                          void *context);
 548  *
 549  * DESCRIPTION
 550  *
 551  *    Renames a file indicated by the `oldname' to the name `newname'.  The
 552  *    `callback' is called to indicate the status of the renaming.
 553  *
 554  ***/
 555 void silc_sftp_rename(SilcSFTP sftp,
 556                       const char *oldname,
 557                       const char *newname,
 558                       SilcSFTPStatusCallback callback,
 559                       void *context);
 560
 561 /****f* silcsftp/SilcSFTPAPI/silc_sftp_mkdir
 562  *
 563  * SYNOPSIS
 564  *
 565  *    void silc_sftp_mkdir(SilcSFTP sftp,
 566  *                         const char *path,
 567  *                         SilcSFTPAttributes attrs,
 568  *                         SilcSFTPStatusCallback callback,
 569  *                         void *context);
 570  *
 571  * DESCRIPTION
 572  *
 573  *    Creates a new directory indicated by the `path' with attributes indicated
 574  *    by the `attrs'. The `callback' is called to indicate the status of the
 575  *    creation.
 576  *
 577  ***/
 578 void silc_sftp_mkdir(SilcSFTP sftp,
 579                      const char *path,
 580                      SilcSFTPAttributes attrs,
 581                      SilcSFTPStatusCallback callback,
 582                      void *context);
 583
 584 /****f* silcsftp/SilcSFTPAPI/silc_sftp_rmdir
 585  *
 586  * SYNOPSIS
 587  *
 588  *    void silc_sftp_rmdir(SilcSFTP sftp,
 589  *                         const char *path,
 590  *                         SilcSFTPStatusCallback callback,
 591  *                         void *context);
 592  *
 593  * DESCRIPTION
 594  *
 595  *    Removes a directory indicated by the `path' and calls the `callback'
 596  *    to indicate the status of the removal.
 597  *
 598  ***/
 599 void silc_sftp_rmdir(SilcSFTP sftp,
 600                      const char *path,
 601                      SilcSFTPStatusCallback callback,
 602                      void *context);
 603
 604 /****f* silcsftp/SilcSFTPAPI/silc_sftp_opendir
 605  *
 606  * SYNOPSIS
 607  *
 608  *    void silc_sftp_opendir(SilcSFTP sftp,
 609  *                           const char *path,
 610  *                           SilcSFTPHandleCallback callback,
 611  *                           void *context);
 612  *
 613  * DESCRIPTION
 614  *
 615  *    Opens a directory indicated by the `path'.  The `callback' is called
 616  *    to return the opened file handle.
 617  *
 618  ***/
 619 void silc_sftp_opendir(SilcSFTP sftp,
 620                        const char *path,
 621                        SilcSFTPHandleCallback callback,
 622                        void *context);
 623
 624 /****f* silcsftp/SilcSFTPAPI/silc_sftp_readdir
 625  *
 626  * SYNOPSIS
 627  *
 628  *    void silc_sftp_readdir(SilcSFTP sftp,
 629  *                           SilcSFTPHandle handle,
 630  *                           SilcSFTPNameCallback callback,
 631  *                           void *context);
 632  *
 633  * DESCRIPTION
 634  *
 635  *    Reads the contents of the directory indicated by the `handle' and
 636  *    calls the `callback' to return the read file(s) from the directory.
 637  *
 638  ***/
 639 void silc_sftp_readdir(SilcSFTP sftp,
 640                        SilcSFTPHandle handle,
 641                        SilcSFTPNameCallback callback,
 642                        void *context);
 643
 644 /****f* silcsftp/SilcSFTPAPI/silc_sftp_stat
 645  *
 646  * SYNOPSIS
 647  *
 648  *    void silc_sftp_stat(SilcSFTP sftp,
 649  *                        const char *path,
 650  *                        SilcSFTPAttrCallback callback,
 651  *                        void *context);
 652  *
 653  * DESCRIPTION
 654  *
 655  *    Gets the file attributes for a file indicated by the `path'. This
 656  *    will follow symbolic links also. Calls the `callback' to return the
 657  *    file attributes.
 658  *
 659  ***/
 660 void silc_sftp_stat(SilcSFTP sftp,
 661                     const char *path,
 662                     SilcSFTPAttrCallback callback,
 663                     void *context);
 664
 665 /****f* silcsftp/SilcSFTPAPI/silc_sftp_lstat
 666  *
 667  * SYNOPSIS
 668  *
 669  *    void silc_sftp_lstat(SilcSFTP sftp,
 670  *                         const char *path,
 671  *                         SilcSFTPAttrCallback callback,
 672  *                         void *context);
 673  *
 674  * DESCRIPTION
 675  *
 676  *    Gets the file attributes for a file indicated by the `path'. This
 677  *    will not follow symbolic links. Calls the `callback' to return the
 678  *    file attributes
 679  *
 680  ***/
 681 void silc_sftp_lstat(SilcSFTP sftp,
 682                      const char *path,
 683                      SilcSFTPAttrCallback callback,
 684                      void *context);
 685
 686 /****f* silcsftp/SilcSFTPAPI/silc_sftp_fstat
 687  *
 688  * SYNOPSIS
 689  *
 690  *    void silc_sftp_fstat(SilcSFTP fstp,
 691  *                         SilcSFTPHandle handle,
 692  *                         SilcSFTPAttrCallback callback,
 693  *                         void *context);
 694  *
 695  * DESCRIPTION
 696  *
 697  *    Gets a file attributes for a opened file indicated by the `handle'.
 698  *    Calls the `callback' to return the file attributes.
 699  *
 700  ***/
 701 void silc_sftp_fstat(SilcSFTP fstp,
 702                      SilcSFTPHandle handle,
 703                      SilcSFTPAttrCallback callback,
 704                      void *context);
 705
 706 /****f* silcsftp/SilcSFTPAPI/silc_sftp_setstat
 707  *
 708  * SYNOPSIS
 709  *
 710  *    void silc_sftp_setstat(SilcSFTP sftp,
 711  *                           const char *path,
 712  *                           SilcSFTPAttributes attrs,
 713  *                           SilcSFTPStatusCallback callback,
 714  *                           void *context);
 715  *
 716  * DESCRIPTION
 717  *
 718  *    Sets a file attributes to a file indicated by the `path' with the
 719  *    attributes indicated by the `attrs'.  Calls the `callback' to indicate
 720  *    the status of the setting.
 721  *
 722  ***/
 723 void silc_sftp_setstat(SilcSFTP sftp,
 724                        const char *path,
 725                        SilcSFTPAttributes attrs,
 726                        SilcSFTPStatusCallback callback,
 727                        void *context);
 728
 729 /****f* silcsftp/SilcSFTPAPI/silc_sftp_fsetstat
 730  *
 731  * SYNOPSIS
 732  *
 733  *    void silc_sftp_fsetstat(SilcSFTP sftp,
 734  *                            SilcSFTPHandle handle,
 735  *                            SilcSFTPAttributes attrs,
 736  *                            SilcSFTPStatusCallback callback,
 737  *                            void *context);
 738  *
 739  * DESCRIPTION
 740  *
 741  *    Sets a file attributes to a opened file indicated by the `handle' with
 742  *    the attributes indicated by the `attrs'.  Calls the `callback' to
 743  *    indicate the status of the setting.
 744  *
 745  ***/
 746 void silc_sftp_fsetstat(SilcSFTP sftp,
 747                         SilcSFTPHandle handle,
 748                         SilcSFTPAttributes attrs,
 749                         SilcSFTPStatusCallback callback,
 750                         void *context);
 751
 752 /****f* silcsftp/SilcSFTPAPI/silc_sftp_readlink
 753  *
 754  * SYNOPSIS
 755  *
 756  *    void silc_sftp_readlink(SilcSFTP sftp,
 757  *                            const char *path,
 758  *                            SilcSFTPNameCallback callback,
 759  *                            void *context);
 760  *
 761  * DESCRIPTION
 762  *
 763  *    Reads the target of a symbolic link indicated by the `path'.  The
 764  *    `callback' is called to return the target of the symbolic link.
 765  *
 766  ***/
 767 void silc_sftp_readlink(SilcSFTP sftp,
 768                         const char *path,
 769                         SilcSFTPNameCallback callback,
 770                         void *context);
 771
 772 /****f* silcsftp/SilcSFTPAPI/silc_sftp_symlink
 773  *
 774  * SYNOPSIS
 775  *
 776  *    void silc_sftp_symlink(SilcSFTP sftp,
 777  *                           const char *linkpath,
 778  *                           const char *targetpath,
 779  *                           SilcSFTPStatusCallback callback,
 780  *                           void *context);
 781  *
 782  * DESCRIPTION
 783  *
 784  *    Creates a new symbolic link indicated by the `linkpath' to the target
 785  *    indicated by the `targetpath'.  The `callback' is called to indicate
 786  *    the status of creation.
 787  *
 788  ***/
 789 void silc_sftp_symlink(SilcSFTP sftp,
 790                        const char *linkpath,
 791                        const char *targetpath,
 792                        SilcSFTPStatusCallback callback,
 793                        void *context);
 794
 795 /****f* silcsftp/SilcSFTPAPI/silc_sftp_realpath
 796  *
 797  * SYNOPSIS
 798  *
 799  *    void silc_sftp_realpath(SilcSFTP sftp,
 800  *                            const char *path,
 801  *                            SilcSFTPNameCallback callback,
 802  *                            void *context);
 803  *
 804  * DESCRIPTION
 805  *
 806  *    Canonicalizes the path indicated by the `path' to a absolute path.
 807  *    The `callback' is called to return the absolute path.
 808  *
 809  ***/
 810 void silc_sftp_realpath(SilcSFTP sftp,
 811                         const char *path,
 812                         SilcSFTPNameCallback callback,
 813                         void *context);
 814
 815 /****f* silcsftp/SilcSFTPAPI/silc_sftp_extended
 816  *
 817  * SYNOPSIS
 818  *
 819  *    void silc_sftp_extended(SilcSFTP sftp,
 820  *                            const char *request,
 821  *                            const unsigned char *data,
 822  *                            SilcUInt32 data_len,
 823  *                            SilcSFTPExtendedCallback callback,
 824  *                            void *context);
 825  *
 826  * DESCRIPTION
 827  *
 828  *    Performs an extended operation indicated by the `request' with
 829  *    optional extended operation data indicated by the `data'.  The callback
 830  *    is called to return any data associated with the extended request.
 831  *
 832  ***/
 833 void silc_sftp_extended(SilcSFTP sftp,
 834                         const char *request,
 835                         const unsigned char *data,
 836                         SilcUInt32 data_len,
 837                         SilcSFTPExtendedCallback callback,
 838                         void *context);
 839
 840
 841 /* SFTP Server Interface */
 842
 843 #include "silcsftp_fs.h"
 844
 845 /****f* silcsftp/SilcSFTPAPI/silc_sftp_server_start
 846  *
 847  * SYNOPSIS
 848  *
 849  *    SilcSFTP silc_sftp_server_start(SilcSFTPSendPacketCallback send_packet,
 850  *                                    void *send_context,
 851  *                                    SilcSFTPFilesystem fs);
 852  *
 853  * DESCRIPTION
 854  *
 855  *    Starts SFTP server and returns a context to it.  This function returns
 856  *    the allocated SFTP server context or NULL on error. The `send_packet'
 857  *    is called by the library when it needs to send a packet. The `fs' is the
 858  *    filesystem context allocated by the application.  Each socket connection
 859  *    should start its own server by calling this function.
 860  *
 861  ***/
 862 SilcSFTP silc_sftp_server_start(SilcSFTPSendPacketCallback send_packet,
 863                                 void *send_context,
 864                                 SilcSFTPFilesystem fs);
 865
 866 /****f* silcsftp/SilcSFTPAPI/silc_sftp_server_shutdown
 867  *
 868  * SYNOPSIS
 869  *
 870  *    void silc_sftp_server_shutdown(SilcSFTP sftp);
 871  *
 872  * DESCRIPTION
 873  *
 874  *    Shutdown's the SFTP server.  The caller is responsible of closing
 875  *    the associated socket connection.  The SFTP context is freed and is
 876  *    invalid after this function returns.
 877  *
 878  ***/
 879 void silc_sftp_server_shutdown(SilcSFTP sftp);
 880
 881 /****d* silcsftp/SilcSFTPAPI/SilcSFTPMonitors
 882  *
 883  * NAME
 884  *
 885  *    typedef enum { ... } SilcSFTPMonitors;
 886  *
 887  * DESCRIPTION
 888  *
 889  *    SFTP server monitor types. These can be masked together to monitor
 890  *    various client requests.
 891  *
 892  * SOURCE
 893  */
 894 typedef enum {
 895   SILC_SFTP_MONITOR_INIT        = 0x0001,
 896   SILC_SFTP_MONITOR_OPEN        = 0x0002,
 897   SILC_SFTP_MONITOR_CLOSE       = 0x0004,
 898   SILC_SFTP_MONITOR_READ        = 0x0008,
 899   SILC_SFTP_MONITOR_WRITE       = 0x0010,
 900   SILC_SFTP_MONITOR_REMOVE      = 0x0020,
 901   SILC_SFTP_MONITOR_RENAME      = 0x0040,
 902   SILC_SFTP_MONITOR_MKDIR       = 0x0080,
 903   SILC_SFTP_MONITOR_RMDIR       = 0x0100,
 904   SILC_SFTP_MONITOR_OPENDIR     = 0x0200,
 905   SILC_SFTP_MONITOR_READDIR     = 0x0400,
 906   SILC_SFTP_MONITOR_STAT        = 0x0800,
 907   SILC_SFTP_MONITOR_LSTAT       = 0x1000,
 908   SILC_SFTP_MONITOR_FSTAT       = 0x2000,
 909   SILC_SFTP_MONITOR_SETSTAT     = 0x4000,
 910   SILC_SFTP_MONITOR_FSETSTAT    = 0x8000,
 911   SILC_SFTP_MONITOR_READLINK    = 0x10000,
 912   SILC_SFTP_MONITOR_SYMLINK     = 0x20000,
 913   SILC_SFTP_MONITOR_REALPATH    = 0x40000,
 914   SILC_SFTP_MONITOR_EXTENDED    = 0x80000,
 915 } SilcSFTPMonitors;
 916 /***/
 917
 918 /****s* silcsftp/SilcSFTPAPI/SilcSFTPMonitorData
 919  *
 920  * NAME
 921  *
 922  *    typedef struct { ... } *SilcSFTPMonitorData, SilcSFTPMonitorDataStruct;
 923  *
 924  * DESCRIPTION
 925  *
 926  *    This structure includes the monitor type specific data.  The
 927  *    application can check what the client has requested from this
 928  *    structure.
 929  *
 930  * SOURCE
 931  */
 932 typedef struct {
 933   SilcSFTPVersion version;      /* _INIT */
 934   char *name;                   /* _OPEN, _REMOVE, _RENAME, _MKDIR,
 935                                    _RMDIR, _OPENDIR, _STAT, _LSTAT,
 936                                    _SETSTAT, _READLINK, _SYMLINK, _REALPATH */
 937   char *name2;                  /* _RENAME, _SYMLINK */
 938   SilcSFTPFileOperation pflags; /* _OPEN */
 939   SilcUInt64 offset;            /* _READ, _WRITE */
 940   SilcUInt32 data_len;          /* _READ, _WRITE */
 941   SilcSFTPName names;           /* _READDIR, _READLINK, _REALPATH */
 942 } *SilcSFTPMonitorData, SilcSFTPMonitorDataStruct;
 943 /***/
 944
 945 /****f* silcsftp/SilcSFTPAPI/SilcSFTPMonitor
 946  *
 947  * SYNOPSIS
 948  *
 949  *    typedef void (*SilcSFTPMonitor)(SilcSFTP sftp
 950  *                                    SilcSFTPMonitors type,
 951  *                                    const SilcSFTPMonitorData data,
 952  *                                    void *context);
 953  *
 954  * DESCRIPTION
 955  *
 956  *    Monitor callback that is called when an specified request is
 957  *    received from client.  The `type' is the requested type that
 958  *    was being monitored.
 959  *
 960  ***/
 961 typedef void (*SilcSFTPMonitor)(SilcSFTP sftp,
 962                                 SilcSFTPMonitors type,
 963                                 const SilcSFTPMonitorData data,
 964                                 void *context);
 965
 966 /****f* silcsftp/SilcSFTPAPI/silc_sftp_server_set_monitor
 967  *
 968  * SYNOPSIS
 969  *
 970  *    void silc_sftp_server_set_monitor(SilcSFTP sftp,
 971  *                                      SilcSFTPMonitors monitors,
 972  *                                      SilcSFTPMonitor monitor,
 973  *                                      void *context);
 974  *
 975  * DESCRIPTION
 976  *
 977  *    Sets monitor callback to monitor various request sent by a client.
 978  *    When request that has been set in the `monitors' is received the
 979  *    monitor callback will be called to notify the caller.
 980  *
 981  ***/
 982 void silc_sftp_server_set_monitor(SilcSFTP sftp,
 983                                   SilcSFTPMonitors monitors,
 984                                   SilcSFTPMonitor monitor,
 985                                   void *context);
 986
 987 #endif /* SILCSFTP_H */