lib/silcsftp/silcsftp.h

   1 /*
   2
   3   silcsftp.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 2001 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/SilcSFTPAPI
  24  *
  25  * DESCRIPTION
  26  *
  27  *    SILC SFTP Interface is the implementation of the SSH 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 uint32 SilcSFTPVersion;
  61  *
  62  * DESCRIPTION
  63  *
  64  *    SFTP Version type.
  65  *
  66  * SOURCE
  67  */
  68 typedef uint32 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 } SilcSFTPStatus;
  99 /***/
 100
 101 /****d* silcsftp/SilcSFTPAPI/SilcSFTPFileOperation
 102  *
 103  * NAME
 104  *
 105  *    typedef enum { ... } SilcSFTPFileOperation
 106  *
 107  * DESCRIPTION
 108  *
 109  *    SFTP protocol file operation flags.  These enumerations can be used
 110  *    by the client when client is opening an file, to indicate how it
 111  *    would like to open the file.
 112  *
 113  * SOURCE
 114  */
 115 typedef enum {
 116   SILC_SFTP_FXF_READ           = 0x00000001, /* Reading */
 117   SILC_SFTP_FXF_WRITE          = 0x00000002, /* Writing */
 118   SILC_SFTP_FXF_APPEND         = 0x00000004, /* Appending to end of file */
 119   SILC_SFTP_FXF_CREAT          = 0x00000008, /* Create if doesn't exist */
 120   SILC_SFTP_FXF_TRUNC          = 0x00000010, /* Truncate if exists */
 121   SILC_SFTP_FXF_EXCL           = 0x00000020, /* Don't create if exists */
 122 } SilcSFTPFileOperation;
 123 /***/
 124
 125 /****s* silcsftp/SilcSFTPAPI/SilcSFTPAttributes
 126  *
 127  * NAME
 128  *
 129  *    typedef struct { ... } *SilcSFTPAttributes, SilcSFTPAttributesStruct;
 130  *
 131  * DESCRIPTION
 132  *
 133  *    SFTP File attributes structure represents the attributes for a file.
 134  *    This structure can be used by the client to send attributes to the
 135  *    server, and by server to return file attributes to the client.
 136  *
 137  ***/
 138 typedef struct {
 139   uint32 flags;                 /* Flags to indicate present attributes */
 140   uint64 size;                  /* Sife of the file in bytes */
 141   uint32 uid;                   /* Unix user ID */
 142   uint32 gid;                   /* Unix group ID */
 143   uint32 permissions;           /* POSIX file permission bitmask */
 144   uint32 atime;                 /* Access time of file */
 145   uint32 mtime;                 /* Modification time of file */
 146
 147   uint32 extended_count;        /* Extended type and data count */
 148   SilcBuffer *extended_type;
 149   SilcBuffer *extended_data;
 150 } *SilcSFTPAttributes, SilcSFTPAttributesStruct;
 151
 152 /****s* silcsftp/SilcSFTPAPI/SilcSFTPName
 153  *
 154  * NAME
 155  *
 156  *    typedef struct { ... } *SilcSFTPName, SilcSFTPNameStruct
 157  *
 158  * DESCRIPTION
 159  *
 160  *    SFTP Name structure represents the name reply received from the server.
 161  *    It includes the returned file(s) short and long file names and
 162  *    attributes for the file(s).  This is returned by the server for
 163  *    example when reading the contents of a directory.
 164  *
 165  ***/
 166 typedef struct  {
 167   char **filename;
 168   char **long_filename;
 169   SilcSFTPAttributes *attrs;
 170   uint32 count;                 /* Number of files */
 171 } *SilcSFTPName, SilcSFTPNameStruct;
 172
 173 /****s* silcsftp/SilcSFTPAPI/SilcSFTPHandle
 174  *
 175  * NAME
 176  *
 177  *    typedef struct SilcSFTPHandleStruct *SilcSFTPHandle;
 178  *
 179  * DESCRIPTION
 180  *
 181  *    This context represents an open file handle and is allocated by
 182  *    the library.  The application receives this context in the
 183  *    SilcSFTPHandleCallback function.
 184  *
 185  ***/
 186 typedef struct SilcSFTPHandleStruct *SilcSFTPHandle;
 187
 188 /****f* silcsftp/SilcSFTPAPI/SilcSFTPSendPacketCallback
 189  *
 190  * SYNOPSIS
 191  *
 192  *    typedef void (*SilcSFTPSendPacketCallback)(SilcSocketConnection sock,
 193  *                                               SilcBuffer packet,
 194  *                                               void *context);
 195  *
 196  * DESCRIPTION
 197  *
 198  *    Packet sending callback. The caller of this interface will provide this
 199  *    function for the library. The libary will call this function everytime
 200  *    it needs to send a packet to the socket connection indicated by the
 201  *    `sock'.
 202  *
 203  ***/
 204 typedef void (*SilcSFTPSendPacketCallback)(SilcSocketConnection sock,
 205                                            SilcBuffer packet, void *context);
 206
 207 /****f* silcsftp/SilcSFTPAPI/SilcSFTPVersionCallback
 208  *
 209  * SYNOPSIS
 210  *
 211  *    typedef void (*SilcSFTPVersionCallback)(SilcSFTP sftp,
 212  *                                            SilcSFTPStatus status,
 213  *                                            SilcSFTPVersion version,
 214  *                                            void *context);
 215  *
 216  * DESCRIPTION
 217  *
 218  *    Version callback is called at the protocol initialization phase when
 219  *    the server returns the version of the protocol. The `version' indicates
 220  *    the version of the protocol.
 221  *
 222  ***/
 223 typedef void (*SilcSFTPVersionCallback)(SilcSFTP sftp,
 224                                         SilcSFTPStatus status,
 225                                         SilcSFTPVersion version,
 226                                         void *context);
 227
 228 /****f* silcsftp/SilcSFTPAPI/SilcSFTPStatusCallback
 229  *
 230  * SYNOPSIS
 231  *
 232  *    typedef void (*SilcSFTPStatusCallback)(SilcSFTP sftp,
 233  *                                           SilcSFTPStatus status,
 234  *                                           const char *message,
 235  *                                           const char *language_tag,
 236  *                                           void *context);
 237  *
 238  * DESCRIPTION
 239  *
 240  *    Status callback is called every time server returns a status packet
 241  *    for a request the client has made. The `status' indicates the type
 242  *    of the status.  The `message' is optional error message received from
 243  *    the server, in language indicated by the `language_tag'.  Both of
 244  *    these pointers may be NULL.
 245  *
 246  ***/
 247 typedef void (*SilcSFTPStatusCallback)(SilcSFTP sftp,
 248                                        SilcSFTPStatus status,
 249                                        const char *message,
 250                                        const char *language_tag,
 251                                        void *context);
 252
 253 /****f* silcsftp/SilcSFTPAPI/SilcSFTPHandleCallback
 254  *
 255  * SYNOPSIS
 256  *
 257  *    typedef void (*SilcSFTPHandleCallback)(SilcSFTP sftp,
 258  *                                           SilcSFTPStatus status,
 259  *                                           SilcSFTPHandle handle,
 260  *                                           void *context);
 261  *
 262  * DESCRIPTION
 263  *
 264  *    Handle callback is called when the server returns a handle to the
 265  *    client as a result of some request client has made.  The `handle'
 266  *    is the file handle and the application can use it to perform file
 267  *    operations for the handle. Each of the returned handle must be
 268  *    also closed at some point with silc_sftp_close.
 269  *
 270  ***/
 271 typedef void (*SilcSFTPHandleCallback)(SilcSFTP sftp,
 272                                        SilcSFTPStatus status,
 273                                        SilcSFTPHandle handle,
 274                                        void *context);
 275
 276 /****f* silcsftp/SilcSFTPAPI/SilcSFTPDataCallback
 277  *
 278  * SYNOPSIS
 279  *
 280  *    typedef void (*SilcSFTPDataCallback)(SilcSFTP sftp,
 281  *                                         SilcSFTPStatus status,
 282  *                                         const unsigned char *data,
 283  *                                         uint32 data_len,
 284  *                                         void *context);
 285  *
 286  * DESCRIPTION
 287  *
 288  *    Data callback is called when data packet is received from the server.
 289  *    This is called for example when application is reading a file from
 290  *    the server.  The `data' is the raw data of length of `data_len'.
 291  *
 292  ***/
 293 typedef void (*SilcSFTPDataCallback)(SilcSFTP sftp,
 294                                      SilcSFTPStatus status,
 295                                      const unsigned char *data,
 296                                      uint32 data_len,
 297                                      void *context);
 298
 299 /****f* silcsftp/SilcSFTPAPI/SilcSFTPNameCallback
 300  *
 301  * SYNOPSIS
 302  *
 303  *    typedef void (*SilcSFTPNameCallback)(SilcSFTP sftp,
 304  *                                         SilcSFTPStatus status,
 305  *                                         const SilcSFTPName name,
 306  *                                         void *context);
 307  *
 308  * DESCRIPTION
 309  *
 310  *    Name callback is called when directory is being read by the client.
 311  *    The server returns one or more file names in one reply.  These file
 312  *    names are saved in the `filename' structures with their short and
 313  *    long name format, and with file attributes.
 314  *
 315  ***/
 316 typedef void (*SilcSFTPNameCallback)(SilcSFTP sftp,
 317                                      SilcSFTPStatus status,
 318                                      const SilcSFTPName name,
 319                                      void *context);
 320
 321 /****f* silcsftp/SilcSFTPAPI/SilcSFTPAttrCallback
 322  *
 323  * SYNOPSIS
 324  *
 325  *    typedef void (*SilcSFTPAttrCallback)(SilcSFTP sftp,
 326  *                                         SilcSFTPStatus status,
 327  *                                         const SilcSFTPAttributes attrs,
 328  *                                         void *context);
 329  *
 330  * DESCRIPTION
 331  *
 332  *    Attributes callback is called when the server returns the attributes
 333  *    for a file the client has requested.  The attributes are saved in
 334  *    the `attrs' structure.
 335  *
 336  ***/
 337 typedef void (*SilcSFTPAttrCallback)(SilcSFTP sftp,
 338                                      SilcSFTPStatus status,
 339                                      const SilcSFTPAttributes attrs,
 340                                      void *context);
 341
 342 /****f* silcsftp/SilcSFTPAPI/SilcSFTPExtendedCallback
 343  *
 344  * SYNOPSIS
 345  *
 346  *    typedef void (*SilcSFTPExtendedCallback)(SilcSFTP sftp,
 347  *                                             SilcSFTPStatus status,
 348  *                                             const unsigned char *data,
 349  *                                             uint32 data_len,
 350  *                                             void *context);
 351  *
 352  * DESCRIPTION
 353  *
 354  *    Extended request callback is called when client sends extended
 355  *    request to the server. The `data' is arbitrary data returned by the
 356  *    server and its encoding is the extended request specific.
 357  *
 358  ***/
 359 typedef void (*SilcSFTPExtendedCallback)(SilcSFTP sftp,
 360                                          SilcSFTPStatus status,
 361                                          const unsigned char *data,
 362                                          uint32 data_len,
 363                                          void *context);
 364
 365
 366 /* SFTP Client Interface */
 367
 368 /****f* silcsftp/SilcSFTPAPI/silc_sftp_client_start
 369  *
 370  * SYNOPSIS
 371  *
 372  *    SilcSFTP silc_sftp_client_start(SilcSocketConnection sock,
 373  *                                    SilcSFTPSendPacketCallback send_packet,
 374  *                                    void *send_context,
 375  *                                    SilcSFTPVersionCallback callback,
 376  *                                    void *context);
 377  *
 378  * DESCRIPTION
 379  *
 380  *    Starts SFTP client by associating the socket connection `sock' to the
 381  *    created SFTP client context.  The version callback indicated by the
 382  *    `callback' will be called after the SFTP session has been started
 383  *    and server has returned the version of the protocol.  The SFTP client
 384  *    context is returned in the callback too.  This returns the allocated
 385  *    SFTP client context or NULL on error.
 386  *
 387  ***/
 388 SilcSFTP silc_sftp_client_start(SilcSocketConnection sock,
 389                                 SilcSFTPSendPacketCallback send_packet,
 390                                 void *send_context,
 391                                 SilcSFTPVersionCallback callback,
 392                                 void *context);
 393
 394 /****f* silcsftp/SilcSFTPAPI/silc_sftp_client_shutdown
 395  *
 396  * SYNOPSIS
 397  *
 398  *    void silc_sftp_client_shutdown(SilcSFTP sftp);
 399  *
 400  * DESCRIPTION
 401  *
 402  *    Shutdown's the SFTP client.  The caller is responsible of closing
 403  *    the associated socket connection.  The SFTP context is freed and is
 404  *    invalid after this function returns.
 405  *
 406  ***/
 407 void silc_sftp_client_shutdown(SilcSFTP sftp);
 408
 409 /* Function that is called to process the incmoing SFTP packet. */
 410 /* XXX Some day this will go away and we have automatic receive callbacks
 411    for SilcSocketConnection API or SilcPacketContext API. */
 412 void silc_sftp_client_receive_process(SilcSFTP sftp,
 413                                       SilcSocketConnection sock,
 414                                       SilcPacketContext *packet);
 415
 416 /****f* silcsftp/SilcSFTPAPI/silc_sftp_open
 417  *
 418  * SYNOPSIS
 419  *
 420  *    void silc_sftp_open(SilcSFTP sftp,
 421  *                        const char *filename,
 422  *                        SilcSFTPFileOperation pflags,
 423  *                        SilcSFTPAttributes attrs,
 424  *                        SilcSFTPHandleCallback callback,
 425  *                        void *context);
 426  *
 427  * DESCRIPTION
 428  *
 429  *    Open a file indicated by the `filename' with flags indicated by the
 430  *    `pflags', and with attributes indicated by the `attsr'.  Calls the
 431  *    `callback' to return the opened file handle.
 432  *
 433  ***/
 434 void silc_sftp_open(SilcSFTP sftp,
 435                     const char *filename,
 436                     SilcSFTPFileOperation pflags,
 437                     SilcSFTPAttributes attrs,
 438                     SilcSFTPHandleCallback callback,
 439                     void *context);
 440
 441 /****f* silcsftp/SilcSFTPAPI/silc_sftp_close
 442  *
 443  * SYNOPSIS
 444  *
 445  *    void silc_sftp_close(SilcSFTP sftp,
 446  *                         SilcSFTPHandle handle,
 447  *                         SilcSFTPStatusCallback callback,
 448  *                         void *context);
 449  *
 450  * DESCRIPTION
 451  *
 452  *    Closes the file indicated by the file handle `handle'.  Calls the
 453  *    `callback' to indicate the status of the closing.
 454  *
 455  ***/
 456 void silc_sftp_close(SilcSFTP sftp,
 457                      SilcSFTPHandle handle,
 458                      SilcSFTPStatusCallback callback,
 459                      void *context);
 460
 461 /****f* silcsftp/SilcSFTPAPI/silc_sftp_read
 462  *
 463  * SYNOPSIS
 464  *
 465  *    void silc_sftp_read(SilcSFTP sftp,
 466  *                        SilcSFTPHandle handle,
 467  *                        uint64 offset,
 468  *                        uint32 len,
 469  *                        SilcSFTPDataCallback callback,
 470  *                        void *context);
 471  *
 472  * DESCRIPTION
 473  *
 474  *    Reads data from the file indicated by the file handle `handle' starting
 475  *    from the offset of `offset' at most `len' bytes.  The `callback' is
 476  *    called to return the read data.
 477  *
 478  ***/
 479 void silc_sftp_read(SilcSFTP sftp,
 480                     SilcSFTPHandle handle,
 481                     uint64 offset,
 482                     uint32 len,
 483                     SilcSFTPDataCallback callback,
 484                     void *context);
 485
 486 /****f* silcsftp/SilcSFTPAPI/silc_sftp_write
 487  *
 488  * SYNOPSIS
 489  *
 490  *    void silc_sftp_write(SilcSFTP sftp,
 491  *                         SilcSFTPHandle handle,
 492  *                         uint64 offset,
 493  *                         const unsigned char *data,
 494  *                         uint32 data_len,
 495  *                         SilcSFTPStatusCallback callback,
 496  *                         void *context);
 497  *
 498  * DESCRIPTION
 499  *
 500  *    Writes to a file indicated by the file handle `handle' starting from
 501  *    offset of `offset' at most `data_len' bytes of `data'.  The `callback'
 502  *    is called to indicate the status of the writing.
 503  *
 504  ***/
 505 void silc_sftp_write(SilcSFTP sftp,
 506                      SilcSFTPHandle handle,
 507                      uint64 offset,
 508                      const unsigned char *data,
 509                      uint32 data_len,
 510                      SilcSFTPStatusCallback callback,
 511                      void *context);
 512
 513 /****f* silcsftp/SilcSFTPAPI/silc_sftp_remove
 514  *
 515  * SYNOPSIS
 516  *
 517  *    void silc_sftp_remove(SilcSFTP sftp,
 518  *                          const char *filename,
 519  *                          SilcSFTPStatusCallback callback,
 520  *                          void *context);
 521  *
 522  * DESCRIPTION
 523  *
 524  *    Removes a file indicated by the `filename'.  Calls the `callback'
 525  *    to indicate the status of the removing.
 526  *
 527  ***/
 528 void silc_sftp_remove(SilcSFTP sftp,
 529                       const char *filename,
 530                       SilcSFTPStatusCallback callback,
 531                       void *context);
 532
 533 /****f* silcsftp/SilcSFTPAPI/silc_sftp_rename
 534  *
 535  * SYNOPSIS
 536  *
 537  *    void silc_sftp_rename(SilcSFTP sftp,
 538  *                          const char *oldname,
 539  *                          const char *newname,
 540  *                          SilcSFTPStatusCallback callback,
 541  *                          void *context);
 542  *
 543  * DESCRIPTION
 544  *
 545  *    Renames a file indicated by the `oldname' to the name `newname'.  The
 546  *    `callback' is called to indicate the status of the renaming.
 547  *
 548  ***/
 549 void silc_sftp_rename(SilcSFTP sftp,
 550                       const char *oldname,
 551                       const char *newname,
 552                       SilcSFTPStatusCallback callback,
 553                       void *context);
 554
 555 /****f* silcsftp/SilcSFTPAPI/silc_sftp_mkdir
 556  *
 557  * SYNOPSIS
 558  *
 559  *    void silc_sftp_mkdir(SilcSFTP sftp,
 560  *                         const char *path,
 561  *                         SilcSFTPAttributes attrs,
 562  *                         SilcSFTPStatusCallback callback,
 563  *                         void *context);
 564  *
 565  * DESCRIPTION
 566  *
 567  *    Creates a new directory indicated by the `path' with attributes indicated
 568  *    by the `attrs'. The `callback' is called to indicate the status of the
 569  *    creation.
 570  *
 571  ***/
 572 void silc_sftp_mkdir(SilcSFTP sftp,
 573                      const char *path,
 574                      SilcSFTPAttributes attrs,
 575                      SilcSFTPStatusCallback callback,
 576                      void *context);
 577
 578 /****f* silcsftp/SilcSFTPAPI/silc_sftp_rmdir
 579  *
 580  * SYNOPSIS
 581  *
 582  *    void silc_sftp_rmdir(SilcSFTP sftp,
 583  *                         const char *path,
 584  *                         SilcSFTPStatusCallback callback,
 585  *                         void *context);
 586  *
 587  * DESCRIPTION
 588  *
 589  *    Removes a directory indicated by the `path' and calls the `callback'
 590  *    to indicate the status of the removal.
 591  *
 592  ***/
 593 void silc_sftp_rmdir(SilcSFTP sftp,
 594                      const char *path,
 595                      SilcSFTPStatusCallback callback,
 596                      void *context);
 597
 598 /****f* silcsftp/SilcSFTPAPI/silc_sftp_opendir
 599  *
 600  * SYNOPSIS
 601  *
 602  *    void silc_sftp_opendir(SilcSFTP sftp,
 603  *                           const char *path,
 604  *                           SilcSFTPHandleCallback callback,
 605  *                           void *context);
 606  *
 607  * DESCRIPTION
 608  *
 609  *    Opens a directory indicated by the `path'.  The `callback' is called
 610  *    to return the opened file handle.
 611  *
 612  ***/
 613 void silc_sftp_opendir(SilcSFTP sftp,
 614                        const char *path,
 615                        SilcSFTPHandleCallback callback,
 616                        void *context);
 617
 618 /****f* silcsftp/SilcSFTPAPI/silc_sftp_readdir
 619  *
 620  * SYNOPSIS
 621  *
 622  *    void silc_sftp_readdir(SilcSFTP sftp,
 623  *                           SilcSFTPHandle handle,
 624  *                           SilcSFTPNameCallback callback,
 625  *                           void *context);
 626  *
 627  * DESCRIPTION
 628  *
 629  *    Reads the contents of the directory indicated by the `handle' and
 630  *    calls the `callback' to return the read file(s) from the directory.
 631  *
 632  ***/
 633 void silc_sftp_readdir(SilcSFTP sftp,
 634                        SilcSFTPHandle handle,
 635                        SilcSFTPNameCallback callback,
 636                        void *context);
 637
 638 /****f* silcsftp/SilcSFTPAPI/silc_sftp_stat
 639  *
 640  * SYNOPSIS
 641  *
 642  *    void silc_sftp_stat(SilcSFTP sftp,
 643  *                        const char *path,
 644  *                        SilcSFTPAttrCallback callback,
 645  *                        void *context);
 646  *
 647  * DESCRIPTION
 648  *
 649  *    Gets the file attributes for a file indicated by the `path'. This
 650  *    will follow symbolic links also. Calls the `callback' to return the
 651  *    file attributes.
 652  *
 653  ***/
 654 void silc_sftp_stat(SilcSFTP sftp,
 655                     const char *path,
 656                     SilcSFTPAttrCallback callback,
 657                     void *context);
 658
 659 /****f* silcsftp/SilcSFTPAPI/silc_sftp_lstat
 660  *
 661  * SYNOPSIS
 662  *
 663  *    void silc_sftp_lstat(SilcSFTP sftp,
 664  *                         const char *path,
 665  *                         SilcSFTPAttrCallback callback,
 666  *                         void *context);
 667  *
 668  * DESCRIPTION
 669  *
 670  *    Gets the file attributes for a file indicated by the `path'. This
 671  *    will not follow symbolic links. Calls the `callback' to return the
 672  *    file attributes
 673  *
 674  ***/
 675 void silc_sftp_lstat(SilcSFTP sftp,
 676                      const char *path,
 677                      SilcSFTPAttrCallback callback,
 678                      void *context);
 679
 680 /****f* silcsftp/SilcSFTPAPI/silc_sftp_fstat
 681  *
 682  * SYNOPSIS
 683  *
 684  *    void silc_sftp_fstat(SilcSFTP fstp,
 685  *                         SilcSFTPHandle handle,
 686  *                         SilcSFTPAttrCallback callback,
 687  *                         void *context);
 688  *
 689  * DESCRIPTION
 690  *
 691  *    Gets a file attributes for a opened file indicated by the `handle'.
 692  *    Calls the `callback' to return the file attributes.
 693  *
 694  ***/
 695 void silc_sftp_fstat(SilcSFTP fstp,
 696                      SilcSFTPHandle handle,
 697                      SilcSFTPAttrCallback callback,
 698                      void *context);
 699
 700 /****f* silcsftp/SilcSFTPAPI/silc_sftp_setstat
 701  *
 702  * SYNOPSIS
 703  *
 704  *    void silc_sftp_setstat(SilcSFTP sftp,
 705  *                           const char *path,
 706  *                           SilcSFTPAttributes attrs,
 707  *                           SilcSFTPStatusCallback callback,
 708  *                           void *context);
 709  *
 710  * DESCRIPTION
 711  *
 712  *    Sets a file attributes to a file indicated by the `path' with the
 713  *    attributes indicated by the `attrs'.  Calls the `callback' to indicate
 714  *    the status of the setting.
 715  *
 716  ***/
 717 void silc_sftp_setstat(SilcSFTP sftp,
 718                        const char *path,
 719                        SilcSFTPAttributes attrs,
 720                        SilcSFTPStatusCallback callback,
 721                        void *context);
 722
 723 /****f* silcsftp/SilcSFTPAPI/silc_sftp_fsetstat
 724  *
 725  * SYNOPSIS
 726  *
 727  *    void silc_sftp_fsetstat(SilcSFTP sftp,
 728  *                            SilcSFTPHandle handle,
 729  *                            SilcSFTPAttributes attrs,
 730  *                            SilcSFTPStatusCallback callback,
 731  *                            void *context);
 732  *
 733  * DESCRIPTION
 734  *
 735  *    Sets a file attributes to a opened file indicated by the `handle' with
 736  *    the attributes indicated by the `attrs'.  Calls the `callback' to
 737  *    indicate the status of the setting.
 738  *
 739  ***/
 740 void silc_sftp_fsetstat(SilcSFTP sftp,
 741                         SilcSFTPHandle handle,
 742                         SilcSFTPAttributes attrs,
 743                         SilcSFTPStatusCallback callback,
 744                         void *context);
 745
 746 /****f* silcsftp/SilcSFTPAPI/silc_sftp_readlink
 747  *
 748  * SYNOPSIS
 749  *
 750  *    void silc_sftp_readlink(SilcSFTP sftp,
 751  *                            const char *path,
 752  *                            SilcSFTPNameCallback callback,
 753  *                            void *context);
 754  *
 755  * DESCRIPTION
 756  *
 757  *    Reads the target of a symbolic link indicated by the `path'.  The
 758  *    `callback' is called to return the target of the symbolic link.
 759  *
 760  ***/
 761 void silc_sftp_readlink(SilcSFTP sftp,
 762                         const char *path,
 763                         SilcSFTPNameCallback callback,
 764                         void *context);
 765
 766 /****f* silcsftp/SilcSFTPAPI/silc_sftp_symlink
 767  *
 768  * SYNOPSIS
 769  *
 770  *    void silc_sftp_symlink(SilcSFTP sftp,
 771  *                           const char *linkpath,
 772  *                           const char *targetpath,
 773  *                           SilcSFTPStatusCallback callback,
 774  *                           void *context);
 775  *
 776  * DESCRIPTION
 777  *
 778  *    Creates a new symbolic link indicated by the `linkpath' to the target
 779  *    indicated by the `targetpath'.  The `callback' is called to indicate
 780  *    the status of creation.
 781  *
 782  ***/
 783 void silc_sftp_symlink(SilcSFTP sftp,
 784                        const char *linkpath,
 785                        const char *targetpath,
 786                        SilcSFTPStatusCallback callback,
 787                        void *context);
 788
 789 /****f* silcsftp/SilcSFTPAPI/silc_sftp_realpath
 790  *
 791  * SYNOPSIS
 792  *
 793  *    void silc_sftp_realpath(SilcSFTP sftp,
 794  *                            const char *path,
 795  *                            SilcSFTPNameCallback callback,
 796  *                            void *context);
 797  *
 798  * DESCRIPTION
 799  *
 800  *    Canonicalizes the path indicated by the `path' to a absolute path.
 801  *    The `callback' is called to return the absolute path.
 802  *
 803  ***/
 804 void silc_sftp_realpath(SilcSFTP sftp,
 805                         const char *path,
 806                         SilcSFTPNameCallback callback,
 807                         void *context);
 808
 809 /****f* silcsftp/SilcSFTPAPI/silc_sftp_extended
 810  *
 811  * SYNOPSIS
 812  *
 813  *    void silc_sftp_extended(SilcSFTP sftp,
 814  *                            const char *request,
 815  *                            const unsigned char *data,
 816  *                            uint32 data_len,
 817  *                            SilcSFTPExtendedCallback callback,
 818  *                            void *context);
 819  *
 820  * DESCRIPTION
 821  *
 822  *    Performs an extended operation indicated by the `request' with
 823  *    optional extended operation data indicated by the `data'.  The callback
 824  *    is called to return any data associated with the extended request.
 825  *
 826  ***/
 827 void silc_sftp_extended(SilcSFTP sftp,
 828                         const char *request,
 829                         const unsigned char *data,
 830                         uint32 data_len,
 831                         SilcSFTPExtendedCallback callback,
 832                         void *context);
 833
 834
 835 /* SFTP Server Interface */
 836
 837 /****s* silcsftp/SilcSFTPAPI/SilcSFTPFilesystem
 838  *
 839  * NAME
 840  *
 841  *    typedef struct SilcSFTPFilesystemStruct { ... } *SilcSFTPFilesystem;
 842  *
 843  * DESCRIPTION
 844  *
 845  *    This structure defines the generic filesystem access.  When the
 846  *    filesystem is accessed these functions are called to do the requested
 847  *    filesystem operation.  The level that implements the actual filesystem
 848  *    must fill this structure with the callback functions providing the
 849  *    access to the filesystem.  The structure is will be given as
 850  *    argument to the silc_sftp_server_start function.
 851  *
 852  * SOURCE
 853  */
 854 typedef struct SilcSFTPFilesystemStruct {
 855   /* Find a file handle by the file handle data indicated by the `data'.
 856      If the handle is not found this returns NULL. */
 857   SilcSFTPHandle (*sftp_get_handle)(void *context, SilcSFTP sftp,
 858                                     const unsigned char *data,
 859                                     uint32 data_len);
 860
 861   /* Return encoded handle of `handle' or NULL on error. The caller
 862      must free the returned buffer. */
 863   unsigned char *(*sftp_encode_handle)(void *context, SilcSFTP sftp,
 864                                        SilcSFTPHandle handle,
 865                                        uint32 *handle_len);
 866
 867   /* Open a file indicated by the `filename' with flags indicated by the
 868      `pflags', and with attributes indicated by the `attr'.  Calls the
 869      `callback' to return the opened file handle. */
 870   void (*sftp_open)(void *context, SilcSFTP sftp,
 871                     const char *filename,
 872                     SilcSFTPFileOperation pflags,
 873                     SilcSFTPAttributes attr,
 874                     SilcSFTPHandleCallback callback,
 875                     void *callback_context);
 876
 877   /* Closes the file indicated by the file handle `handle'.  Calls the
 878      `callback' to indicate the status of the closing. */
 879   void (*sftp_close)(void *context, SilcSFTP sftp,
 880                      SilcSFTPHandle handle,
 881                      SilcSFTPStatusCallback callback,
 882                      void *callback_context);
 883
 884   /* Reads data from the file indicated by the file handle `handle' starting
 885      from the offset of `offset' at most `len' bytes.  The `callback' is
 886      called to return the read data. */
 887   void (*sftp_read)(void *context, SilcSFTP sftp,
 888                     SilcSFTPHandle handle,
 889                     uint64 offset,
 890                     uint32 len,
 891                     SilcSFTPDataCallback callback,
 892                     void *callback_context);
 893
 894   /* Writes to a file indicated by the file handle `handle' starting from
 895      offset of `offset' at most `data_len' bytes of `data'.  The `callback'
 896      is called to indicate the status of the writing. */
 897   void (*sftp_write)(void *context, SilcSFTP sftp,
 898                      SilcSFTPHandle handle,
 899                      uint64 offset,
 900                      const unsigned char *data,
 901                      uint32 data_len,
 902                      SilcSFTPStatusCallback callback,
 903                      void *callback_context);
 904
 905   /* Removes a file indicated by the `filename'.  Calls the `callback'
 906      to indicate the status of the removing. */
 907   void (*sftp_remove)(void *context, SilcSFTP sftp,
 908                       const char *filename,
 909                       SilcSFTPStatusCallback callback,
 910                       void *callback_context);
 911
 912   /* Renames a file indicated by the `oldname' to the name `newname'.  The
 913      `callback' is called to indicate the status of the renaming. */
 914   void (*sftp_rename)(void *context, SilcSFTP sftp,
 915                       const char *oldname,
 916                       const char *newname,
 917                       SilcSFTPStatusCallback callback,
 918                       void *callback_context);
 919
 920   /* Creates a new directory indicated by the `path' with attributes indicated
 921      by the `attrs'. The `callback' is called to indicate the status of the
 922      creation. */
 923   void (*sftp_mkdir)(void *context, SilcSFTP sftp,
 924                      const char *path,
 925                      SilcSFTPAttributes attrs,
 926                      SilcSFTPStatusCallback callback,
 927                      void *callback_context);
 928
 929   /* Removes a directory indicated by the `path' and calls the `callback'
 930      to indicate the status of the removal. */
 931   void (*sftp_rmdir)(void *context, SilcSFTP sftp,
 932                      const char *path,
 933                      SilcSFTPStatusCallback callback,
 934                      void *callback_context);
 935
 936   /* Opens a directory indicated by the `path'.  The `callback' is called
 937      to return the opened file handle. */
 938   void (*sftp_opendir)(void *context, SilcSFTP sftp,
 939                        const char *path,
 940                        SilcSFTPHandleCallback callback,
 941                        void *callback_context);
 942
 943   /* Reads the contents of the directory indicated by the `handle' and
 944      calls the `callback' to return the read file(s) from the directory. */
 945   void (*sftp_readdir)(void *context, SilcSFTP sftp,
 946                        SilcSFTPHandle handle,
 947                        SilcSFTPNameCallback callback,
 948                        void *callback_context);
 949
 950   /* Gets the file attributes for a file indicated by the `path'. This
 951      will follow symbolic links also. Calls the `callback' to return the
 952      file attributes. */
 953   void (*sftp_stat)(void *context, SilcSFTP sftp,
 954                     const char *path,
 955                     SilcSFTPAttrCallback callback,
 956                     void *callback_context);
 957
 958   /* Gets the file attributes for a file indicated by the `path'. This
 959      will not follow symbolic links. Calls the `callback' to return the
 960      file attributes. */
 961   void (*sftp_lstat)(void *context, SilcSFTP sftp,
 962                      const char *path,
 963                      SilcSFTPAttrCallback callback,
 964                      void *callback_context);
 965
 966   /* Gets a file attributes for a opened file indicated by the `handle'.
 967      Calls the `callback' to return the file attributes. */
 968   void (*sftp_fstat)(void *context, SilcSFTP sftp,
 969                      SilcSFTPHandle handle,
 970                      SilcSFTPAttrCallback callback,
 971                      void *callback_context);
 972
 973   /* Sets a file attributes to a file indicated by the `path' with the
 974      attributes indicated by the `attrs'.  Calls the `callback' to indicate
 975      the status of the setting. */
 976   void (*sftp_setstat)(void *context, SilcSFTP sftp,
 977                        const char *path,
 978                        SilcSFTPAttributes attrs,
 979                        SilcSFTPStatusCallback callback,
 980                        void *callback_context);
 981
 982   /* Sets a file attributes to a opened file indicated by the `handle' with
 983      the attributes indicated by the `attrs'.  Calls the `callback' to
 984      indicate the status of the setting. */
 985   void (*sftp_fsetstat)(void *context, SilcSFTP sftp,
 986                         SilcSFTPHandle handle,
 987                         SilcSFTPAttributes attrs,
 988                         SilcSFTPStatusCallback callback,
 989                         void *callback_context);
 990
 991   /* Reads the target of a symbolic link indicated by the `path'.  The
 992      `callback' is called to return the target of the symbolic link. */
 993   void (*sftp_readlink)(void *context, SilcSFTP sftp,
 994                         const char *path,
 995                         SilcSFTPNameCallback callback,
 996                         void *callback_context);
 997
 998   /* Creates a new symbolic link indicated by the `linkpath' to the target
 999      indicated by the `targetpath'.  The `callback' is called to indicate
1000      the status of creation. */
1001   void (*sftp_symlink)(void *context, SilcSFTP sftp,
1002                        const char *linkpath,
1003                        const char *targetpath,
1004                        SilcSFTPStatusCallback callback,
1005                        void *callback_context);
1006
1007   /* Canonicalizes the path indicated by the `path' to a absolute path.
1008      The `callback' is called to return the absolute path. */
1009   void (*sftp_realpath)(void *context, SilcSFTP sftp,
1010                         const char *path,
1011                         SilcSFTPNameCallback callback,
1012                         void *callback_context);
1013
1014   /* Performs an extended operation indicated by the `request' with
1015      optional extended operation data indicated by the `data'.  The callback
1016      is called to return any data associated with the extended request. */
1017   void (*sftp_extended)(void *context, SilcSFTP sftp,
1018                         const char *request,
1019                         const unsigned char *data,
1020                         uint32 data_len,
1021                         SilcSFTPExtendedCallback callback,
1022                         void *callback_context);
1023 } *SilcSFTPFilesystem;
1024 /****/
1025
1026 /****f* silcsftp/SilcSFTPAPI/silc_sftp_server_start
1027  *
1028  * SYNOPSIS
1029  *
1030  *    SilcSFTP silc_sftp_server_start(SilcSocketConnection sock,
1031  *                                    SilcSFTPSendPacketCallback send_packet,
1032  *                                    void *send_context, SilcSFTP sftp,
1033  *                                    SilcSFTPFilesystem fs,
1034  *                                    void *fs_context);
1035  *
1036  * DESCRIPTION
1037  *
1038  *    Starts SFTP server by associating the socket connection `sock' to the
1039  *    created SFTP server context.  This function returns the allocated
1040  *    SFTP client context or NULL on error. The `send_packet' is called
1041  *    by the library when it needs to send a packet. The `fs' is the
1042  *    structure containing filesystem access callbacks.
1043  *
1044  ***/
1045 SilcSFTP silc_sftp_server_start(SilcSocketConnection sock,
1046                                 SilcSFTPSendPacketCallback send_packet,
1047                                 void *send_context,
1048                                 SilcSFTPFilesystem fs,
1049                                 void *fs_context);
1050
1051 /****f* silcsftp/SilcSFTPAPI/silc_sftp_server_shutdown
1052  *
1053  * SYNOPSIS
1054  *
1055  *    void silc_sftp_server_shutdown(SilcSFTP sftp);
1056  *
1057  * DESCRIPTION
1058  *
1059  *    Shutdown's the SFTP server.  The caller is responsible of closing
1060  *    the associated socket connection.  The SFTP context is freed and is
1061  *    invalid after this function returns.
1062  *
1063  ***/
1064 void silc_sftp_server_shutdown(SilcSFTP sftp);
1065
1066 /* Function that is called to process the incmoing SFTP packet. */
1067 /* XXX Some day this will go away and we have automatic receive callbacks
1068    for SilcSocketConnection API or SilcPacketContext API. */
1069 void silc_sftp_server_receive_process(SilcSFTP sftp,
1070                                       SilcSocketConnection sock,
1071                                       SilcPacketContext *packet);
1072
1073 #endif /* SILCSFTP_H */