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/SILC SFTP Interface
  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 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 } 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   SilcUInt32 flags;             /* Flags to indicate present attributes */
 140   SilcUInt64 size;              /* Sife of the file in bytes */
 141   SilcUInt32 uid;               /* Unix user ID */
 142   SilcUInt32 gid;               /* Unix group ID */
 143   SilcUInt32 permissions;       /* POSIX file permission bitmask */
 144   SilcUInt32 atime;             /* Access time of file */
 145   SilcUInt32 mtime;             /* Modification time of file */
 146
 147   SilcUInt32 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   SilcUInt32 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)(SilcBuffer packet,
 193  *                                               void *context);
 194  *
 195  * DESCRIPTION
 196  *
 197  *    Packet sending callback. The caller of this interface will provide this
 198  *    function for the library. The libary will call this function everytime
 199  *    it needs to send a packet to the remote host.
 200  *
 201  ***/
 202 typedef void (*SilcSFTPSendPacketCallback)(SilcBuffer packet, void *context);
 203
 204 /****f* silcsftp/SilcSFTPAPI/SilcSFTPVersionCallback
 205  *
 206  * SYNOPSIS
 207  *
 208  *    typedef void (*SilcSFTPVersionCallback)(SilcSFTP sftp,
 209  *                                            SilcSFTPStatus status,
 210  *                                            SilcSFTPVersion version,
 211  *                                            void *context);
 212  *
 213  * DESCRIPTION
 214  *
 215  *    Version callback is called at the protocol initialization phase when
 216  *    the server returns the version of the protocol. The `version' indicates
 217  *    the version of the protocol.
 218  *
 219  ***/
 220 typedef void (*SilcSFTPVersionCallback)(SilcSFTP sftp,
 221                                         SilcSFTPStatus status,
 222                                         SilcSFTPVersion version,
 223                                         void *context);
 224
 225 /****f* silcsftp/SilcSFTPAPI/SilcSFTPStatusCallback
 226  *
 227  * SYNOPSIS
 228  *
 229  *    typedef void (*SilcSFTPStatusCallback)(SilcSFTP sftp,
 230  *                                           SilcSFTPStatus status,
 231  *                                           const char *message,
 232  *                                           const char *language_tag,
 233  *                                           void *context);
 234  *
 235  * DESCRIPTION
 236  *
 237  *    Status callback is called every time server returns a status packet
 238  *    for a request the client has made. The `status' indicates the type
 239  *    of the status.  The `message' is optional error message received from
 240  *    the server, in language indicated by the `language_tag'.  Both of
 241  *    these pointers may be NULL.
 242  *
 243  ***/
 244 typedef void (*SilcSFTPStatusCallback)(SilcSFTP sftp,
 245                                        SilcSFTPStatus status,
 246                                        const char *message,
 247                                        const char *language_tag,
 248                                        void *context);
 249
 250 /****f* silcsftp/SilcSFTPAPI/SilcSFTPHandleCallback
 251  *
 252  * SYNOPSIS
 253  *
 254  *    typedef void (*SilcSFTPHandleCallback)(SilcSFTP sftp,
 255  *                                           SilcSFTPStatus status,
 256  *                                           SilcSFTPHandle handle,
 257  *                                           void *context);
 258  *
 259  * DESCRIPTION
 260  *
 261  *    Handle callback is called when the server returns a handle to the
 262  *    client as a result of some request client has made.  The `handle'
 263  *    is the file handle and the application can use it to perform file
 264  *    operations for the handle. Each of the returned handle must be
 265  *    also closed at some point with silc_sftp_close.
 266  *
 267  ***/
 268 typedef void (*SilcSFTPHandleCallback)(SilcSFTP sftp,
 269                                        SilcSFTPStatus status,
 270                                        SilcSFTPHandle handle,
 271                                        void *context);
 272
 273 /****f* silcsftp/SilcSFTPAPI/SilcSFTPDataCallback
 274  *
 275  * SYNOPSIS
 276  *
 277  *    typedef void (*SilcSFTPDataCallback)(SilcSFTP sftp,
 278  *                                         SilcSFTPStatus status,
 279  *                                         const unsigned char *data,
 280  *                                         SilcUInt32 data_len,
 281  *                                         void *context);
 282  *
 283  * DESCRIPTION
 284  *
 285  *    Data callback is called when data packet is received from the server.
 286  *    This is called for example when application is reading a file from
 287  *    the server.  The `data' is the raw data of length of `data_len'.
 288  *
 289  ***/
 290 typedef void (*SilcSFTPDataCallback)(SilcSFTP sftp,
 291                                      SilcSFTPStatus status,
 292                                      const unsigned char *data,
 293                                      SilcUInt32 data_len,
 294                                      void *context);
 295
 296 /****f* silcsftp/SilcSFTPAPI/SilcSFTPNameCallback
 297  *
 298  * SYNOPSIS
 299  *
 300  *    typedef void (*SilcSFTPNameCallback)(SilcSFTP sftp,
 301  *                                         SilcSFTPStatus status,
 302  *                                         const SilcSFTPName name,
 303  *                                         void *context);
 304  *
 305  * DESCRIPTION
 306  *
 307  *    Name callback is called when directory is being read by the client.
 308  *    The server returns one or more file names in one reply.  These file
 309  *    names are saved in the `filename' structures with their short and
 310  *    long name format, and with file attributes.
 311  *
 312  ***/
 313 typedef void (*SilcSFTPNameCallback)(SilcSFTP sftp,
 314                                      SilcSFTPStatus status,
 315                                      const SilcSFTPName name,
 316                                      void *context);
 317
 318 /****f* silcsftp/SilcSFTPAPI/SilcSFTPAttrCallback
 319  *
 320  * SYNOPSIS
 321  *
 322  *    typedef void (*SilcSFTPAttrCallback)(SilcSFTP sftp,
 323  *                                         SilcSFTPStatus status,
 324  *                                         const SilcSFTPAttributes attrs,
 325  *                                         void *context);
 326  *
 327  * DESCRIPTION
 328  *
 329  *    Attributes callback is called when the server returns the attributes
 330  *    for a file the client has requested.  The attributes are saved in
 331  *    the `attrs' structure.
 332  *
 333  ***/
 334 typedef void (*SilcSFTPAttrCallback)(SilcSFTP sftp,
 335                                      SilcSFTPStatus status,
 336                                      const SilcSFTPAttributes attrs,
 337                                      void *context);
 338
 339 /****f* silcsftp/SilcSFTPAPI/SilcSFTPExtendedCallback
 340  *
 341  * SYNOPSIS
 342  *
 343  *    typedef void (*SilcSFTPExtendedCallback)(SilcSFTP sftp,
 344  *                                             SilcSFTPStatus status,
 345  *                                             const unsigned char *data,
 346  *                                             SilcUInt32 data_len,
 347  *                                             void *context);
 348  *
 349  * DESCRIPTION
 350  *
 351  *    Extended request callback is called when client sends extended
 352  *    request to the server. The `data' is arbitrary data returned by the
 353  *    server and its encoding is the extended request specific.
 354  *
 355  ***/
 356 typedef void (*SilcSFTPExtendedCallback)(SilcSFTP sftp,
 357                                          SilcSFTPStatus status,
 358                                          const unsigned char *data,
 359                                          SilcUInt32 data_len,
 360                                          void *context);
 361
 362
 363 /* SFTP Client Interface */
 364
 365 /****f* silcsftp/SilcSFTPAPI/silc_sftp_client_start
 366  *
 367  * SYNOPSIS
 368  *
 369  *    SilcSFTP silc_sftp_client_start(SilcSFTPSendPacketCallback send_packet,
 370  *                                    void *send_context,
 371  *                                    SilcSFTPVersionCallback callback,
 372  *                                    void *context);
 373  *
 374  * DESCRIPTION
 375  *
 376  *    Starts SFTP client and returns context to it.  The version callback
 377  *    indicated by the `callback' will be called after the SFTP session has
 378  *    been started and server has returned the version of the protocol.  The
 379  *    SFTP client context is returned in the callback too.  This returns the
 380  *    allocated SFTP client context or NULL on error.  Each socket connection
 381  *    should allocate their own SFTP client by calling this function.
 382  *
 383  ***/
 384 SilcSFTP silc_sftp_client_start(SilcSFTPSendPacketCallback send_packet,
 385                                 void *send_context,
 386                                 SilcSFTPVersionCallback callback,
 387                                 void *context);
 388
 389 /****f* silcsftp/SilcSFTPAPI/silc_sftp_client_shutdown
 390  *
 391  * SYNOPSIS
 392  *
 393  *    void silc_sftp_client_shutdown(SilcSFTP sftp);
 394  *
 395  * DESCRIPTION
 396  *
 397  *    Shutdown's the SFTP client.  The caller is responsible of closing
 398  *    the associated socket connection.  The SFTP context is freed and is
 399  *    invalid after this function returns.
 400  *
 401  ***/
 402 void silc_sftp_client_shutdown(SilcSFTP sftp);
 403
 404 /* Function that is called to process the incmoing SFTP packet. */
 405 /* XXX Some day this will go away and we have automatic receive callbacks
 406    for SilcSocketConnection API or SilcPacketContext API. */
 407 void silc_sftp_client_receive_process(SilcSFTP sftp,
 408                                       SilcSocketConnection sock,
 409                                       SilcPacketContext *packet);
 410
 411 /****f* silcsftp/SilcSFTPAPI/silc_sftp_open
 412  *
 413  * SYNOPSIS
 414  *
 415  *    void silc_sftp_open(SilcSFTP sftp,
 416  *                        const char *filename,
 417  *                        SilcSFTPFileOperation pflags,
 418  *                        SilcSFTPAttributes attrs,
 419  *                        SilcSFTPHandleCallback callback,
 420  *                        void *context);
 421  *
 422  * DESCRIPTION
 423  *
 424  *    Open a file indicated by the `filename' with flags indicated by the
 425  *    `pflags', and with attributes indicated by the `attsr'.  Calls the
 426  *    `callback' to return the opened file handle.
 427  *
 428  ***/
 429 void silc_sftp_open(SilcSFTP sftp,
 430                     const char *filename,
 431                     SilcSFTPFileOperation pflags,
 432                     SilcSFTPAttributes attrs,
 433                     SilcSFTPHandleCallback callback,
 434                     void *context);
 435
 436 /****f* silcsftp/SilcSFTPAPI/silc_sftp_close
 437  *
 438  * SYNOPSIS
 439  *
 440  *    void silc_sftp_close(SilcSFTP sftp,
 441  *                         SilcSFTPHandle handle,
 442  *                         SilcSFTPStatusCallback callback,
 443  *                         void *context);
 444  *
 445  * DESCRIPTION
 446  *
 447  *    Closes the file indicated by the file handle `handle'.  Calls the
 448  *    `callback' to indicate the status of the closing.
 449  *
 450  ***/
 451 void silc_sftp_close(SilcSFTP sftp,
 452                      SilcSFTPHandle handle,
 453                      SilcSFTPStatusCallback callback,
 454                      void *context);
 455
 456 /****f* silcsftp/SilcSFTPAPI/silc_sftp_read
 457  *
 458  * SYNOPSIS
 459  *
 460  *    void silc_sftp_read(SilcSFTP sftp,
 461  *                        SilcSFTPHandle handle,
 462  *                        SilcUInt64 offset,
 463  *                        SilcUInt32 len,
 464  *                        SilcSFTPDataCallback callback,
 465  *                        void *context);
 466  *
 467  * DESCRIPTION
 468  *
 469  *    Reads data from the file indicated by the file handle `handle' starting
 470  *    from the offset of `offset' at most `len' bytes.  The `callback' is
 471  *    called to return the read data.
 472  *
 473  ***/
 474 void silc_sftp_read(SilcSFTP sftp,
 475                     SilcSFTPHandle handle,
 476                     SilcUInt64 offset,
 477                     SilcUInt32 len,
 478                     SilcSFTPDataCallback callback,
 479                     void *context);
 480
 481 /****f* silcsftp/SilcSFTPAPI/silc_sftp_write
 482  *
 483  * SYNOPSIS
 484  *
 485  *    void silc_sftp_write(SilcSFTP sftp,
 486  *                         SilcSFTPHandle handle,
 487  *                         SilcUInt64 offset,
 488  *                         const unsigned char *data,
 489  *                         SilcUInt32 data_len,
 490  *                         SilcSFTPStatusCallback callback,
 491  *                         void *context);
 492  *
 493  * DESCRIPTION
 494  *
 495  *    Writes to a file indicated by the file handle `handle' starting from
 496  *    offset of `offset' at most `data_len' bytes of `data'.  The `callback'
 497  *    is called to indicate the status of the writing.
 498  *
 499  ***/
 500 void silc_sftp_write(SilcSFTP sftp,
 501                      SilcSFTPHandle handle,
 502                      SilcUInt64 offset,
 503                      const unsigned char *data,
 504                      SilcUInt32 data_len,
 505                      SilcSFTPStatusCallback callback,
 506                      void *context);
 507
 508 /****f* silcsftp/SilcSFTPAPI/silc_sftp_remove
 509  *
 510  * SYNOPSIS
 511  *
 512  *    void silc_sftp_remove(SilcSFTP sftp,
 513  *                          const char *filename,
 514  *                          SilcSFTPStatusCallback callback,
 515  *                          void *context);
 516  *
 517  * DESCRIPTION
 518  *
 519  *    Removes a file indicated by the `filename'.  Calls the `callback'
 520  *    to indicate the status of the removing.
 521  *
 522  ***/
 523 void silc_sftp_remove(SilcSFTP sftp,
 524                       const char *filename,
 525                       SilcSFTPStatusCallback callback,
 526                       void *context);
 527
 528 /****f* silcsftp/SilcSFTPAPI/silc_sftp_rename
 529  *
 530  * SYNOPSIS
 531  *
 532  *    void silc_sftp_rename(SilcSFTP sftp,
 533  *                          const char *oldname,
 534  *                          const char *newname,
 535  *                          SilcSFTPStatusCallback callback,
 536  *                          void *context);
 537  *
 538  * DESCRIPTION
 539  *
 540  *    Renames a file indicated by the `oldname' to the name `newname'.  The
 541  *    `callback' is called to indicate the status of the renaming.
 542  *
 543  ***/
 544 void silc_sftp_rename(SilcSFTP sftp,
 545                       const char *oldname,
 546                       const char *newname,
 547                       SilcSFTPStatusCallback callback,
 548                       void *context);
 549
 550 /****f* silcsftp/SilcSFTPAPI/silc_sftp_mkdir
 551  *
 552  * SYNOPSIS
 553  *
 554  *    void silc_sftp_mkdir(SilcSFTP sftp,
 555  *                         const char *path,
 556  *                         SilcSFTPAttributes attrs,
 557  *                         SilcSFTPStatusCallback callback,
 558  *                         void *context);
 559  *
 560  * DESCRIPTION
 561  *
 562  *    Creates a new directory indicated by the `path' with attributes indicated
 563  *    by the `attrs'. The `callback' is called to indicate the status of the
 564  *    creation.
 565  *
 566  ***/
 567 void silc_sftp_mkdir(SilcSFTP sftp,
 568                      const char *path,
 569                      SilcSFTPAttributes attrs,
 570                      SilcSFTPStatusCallback callback,
 571                      void *context);
 572
 573 /****f* silcsftp/SilcSFTPAPI/silc_sftp_rmdir
 574  *
 575  * SYNOPSIS
 576  *
 577  *    void silc_sftp_rmdir(SilcSFTP sftp,
 578  *                         const char *path,
 579  *                         SilcSFTPStatusCallback callback,
 580  *                         void *context);
 581  *
 582  * DESCRIPTION
 583  *
 584  *    Removes a directory indicated by the `path' and calls the `callback'
 585  *    to indicate the status of the removal.
 586  *
 587  ***/
 588 void silc_sftp_rmdir(SilcSFTP sftp,
 589                      const char *path,
 590                      SilcSFTPStatusCallback callback,
 591                      void *context);
 592
 593 /****f* silcsftp/SilcSFTPAPI/silc_sftp_opendir
 594  *
 595  * SYNOPSIS
 596  *
 597  *    void silc_sftp_opendir(SilcSFTP sftp,
 598  *                           const char *path,
 599  *                           SilcSFTPHandleCallback callback,
 600  *                           void *context);
 601  *
 602  * DESCRIPTION
 603  *
 604  *    Opens a directory indicated by the `path'.  The `callback' is called
 605  *    to return the opened file handle.
 606  *
 607  ***/
 608 void silc_sftp_opendir(SilcSFTP sftp,
 609                        const char *path,
 610                        SilcSFTPHandleCallback callback,
 611                        void *context);
 612
 613 /****f* silcsftp/SilcSFTPAPI/silc_sftp_readdir
 614  *
 615  * SYNOPSIS
 616  *
 617  *    void silc_sftp_readdir(SilcSFTP sftp,
 618  *                           SilcSFTPHandle handle,
 619  *                           SilcSFTPNameCallback callback,
 620  *                           void *context);
 621  *
 622  * DESCRIPTION
 623  *
 624  *    Reads the contents of the directory indicated by the `handle' and
 625  *    calls the `callback' to return the read file(s) from the directory.
 626  *
 627  ***/
 628 void silc_sftp_readdir(SilcSFTP sftp,
 629                        SilcSFTPHandle handle,
 630                        SilcSFTPNameCallback callback,
 631                        void *context);
 632
 633 /****f* silcsftp/SilcSFTPAPI/silc_sftp_stat
 634  *
 635  * SYNOPSIS
 636  *
 637  *    void silc_sftp_stat(SilcSFTP sftp,
 638  *                        const char *path,
 639  *                        SilcSFTPAttrCallback callback,
 640  *                        void *context);
 641  *
 642  * DESCRIPTION
 643  *
 644  *    Gets the file attributes for a file indicated by the `path'. This
 645  *    will follow symbolic links also. Calls the `callback' to return the
 646  *    file attributes.
 647  *
 648  ***/
 649 void silc_sftp_stat(SilcSFTP sftp,
 650                     const char *path,
 651                     SilcSFTPAttrCallback callback,
 652                     void *context);
 653
 654 /****f* silcsftp/SilcSFTPAPI/silc_sftp_lstat
 655  *
 656  * SYNOPSIS
 657  *
 658  *    void silc_sftp_lstat(SilcSFTP sftp,
 659  *                         const char *path,
 660  *                         SilcSFTPAttrCallback callback,
 661  *                         void *context);
 662  *
 663  * DESCRIPTION
 664  *
 665  *    Gets the file attributes for a file indicated by the `path'. This
 666  *    will not follow symbolic links. Calls the `callback' to return the
 667  *    file attributes
 668  *
 669  ***/
 670 void silc_sftp_lstat(SilcSFTP sftp,
 671                      const char *path,
 672                      SilcSFTPAttrCallback callback,
 673                      void *context);
 674
 675 /****f* silcsftp/SilcSFTPAPI/silc_sftp_fstat
 676  *
 677  * SYNOPSIS
 678  *
 679  *    void silc_sftp_fstat(SilcSFTP fstp,
 680  *                         SilcSFTPHandle handle,
 681  *                         SilcSFTPAttrCallback callback,
 682  *                         void *context);
 683  *
 684  * DESCRIPTION
 685  *
 686  *    Gets a file attributes for a opened file indicated by the `handle'.
 687  *    Calls the `callback' to return the file attributes.
 688  *
 689  ***/
 690 void silc_sftp_fstat(SilcSFTP fstp,
 691                      SilcSFTPHandle handle,
 692                      SilcSFTPAttrCallback callback,
 693                      void *context);
 694
 695 /****f* silcsftp/SilcSFTPAPI/silc_sftp_setstat
 696  *
 697  * SYNOPSIS
 698  *
 699  *    void silc_sftp_setstat(SilcSFTP sftp,
 700  *                           const char *path,
 701  *                           SilcSFTPAttributes attrs,
 702  *                           SilcSFTPStatusCallback callback,
 703  *                           void *context);
 704  *
 705  * DESCRIPTION
 706  *
 707  *    Sets a file attributes to a file indicated by the `path' with the
 708  *    attributes indicated by the `attrs'.  Calls the `callback' to indicate
 709  *    the status of the setting.
 710  *
 711  ***/
 712 void silc_sftp_setstat(SilcSFTP sftp,
 713                        const char *path,
 714                        SilcSFTPAttributes attrs,
 715                        SilcSFTPStatusCallback callback,
 716                        void *context);
 717
 718 /****f* silcsftp/SilcSFTPAPI/silc_sftp_fsetstat
 719  *
 720  * SYNOPSIS
 721  *
 722  *    void silc_sftp_fsetstat(SilcSFTP sftp,
 723  *                            SilcSFTPHandle handle,
 724  *                            SilcSFTPAttributes attrs,
 725  *                            SilcSFTPStatusCallback callback,
 726  *                            void *context);
 727  *
 728  * DESCRIPTION
 729  *
 730  *    Sets a file attributes to a opened file indicated by the `handle' with
 731  *    the attributes indicated by the `attrs'.  Calls the `callback' to
 732  *    indicate the status of the setting.
 733  *
 734  ***/
 735 void silc_sftp_fsetstat(SilcSFTP sftp,
 736                         SilcSFTPHandle handle,
 737                         SilcSFTPAttributes attrs,
 738                         SilcSFTPStatusCallback callback,
 739                         void *context);
 740
 741 /****f* silcsftp/SilcSFTPAPI/silc_sftp_readlink
 742  *
 743  * SYNOPSIS
 744  *
 745  *    void silc_sftp_readlink(SilcSFTP sftp,
 746  *                            const char *path,
 747  *                            SilcSFTPNameCallback callback,
 748  *                            void *context);
 749  *
 750  * DESCRIPTION
 751  *
 752  *    Reads the target of a symbolic link indicated by the `path'.  The
 753  *    `callback' is called to return the target of the symbolic link.
 754  *
 755  ***/
 756 void silc_sftp_readlink(SilcSFTP sftp,
 757                         const char *path,
 758                         SilcSFTPNameCallback callback,
 759                         void *context);
 760
 761 /****f* silcsftp/SilcSFTPAPI/silc_sftp_symlink
 762  *
 763  * SYNOPSIS
 764  *
 765  *    void silc_sftp_symlink(SilcSFTP sftp,
 766  *                           const char *linkpath,
 767  *                           const char *targetpath,
 768  *                           SilcSFTPStatusCallback callback,
 769  *                           void *context);
 770  *
 771  * DESCRIPTION
 772  *
 773  *    Creates a new symbolic link indicated by the `linkpath' to the target
 774  *    indicated by the `targetpath'.  The `callback' is called to indicate
 775  *    the status of creation.
 776  *
 777  ***/
 778 void silc_sftp_symlink(SilcSFTP sftp,
 779                        const char *linkpath,
 780                        const char *targetpath,
 781                        SilcSFTPStatusCallback callback,
 782                        void *context);
 783
 784 /****f* silcsftp/SilcSFTPAPI/silc_sftp_realpath
 785  *
 786  * SYNOPSIS
 787  *
 788  *    void silc_sftp_realpath(SilcSFTP sftp,
 789  *                            const char *path,
 790  *                            SilcSFTPNameCallback callback,
 791  *                            void *context);
 792  *
 793  * DESCRIPTION
 794  *
 795  *    Canonicalizes the path indicated by the `path' to a absolute path.
 796  *    The `callback' is called to return the absolute path.
 797  *
 798  ***/
 799 void silc_sftp_realpath(SilcSFTP sftp,
 800                         const char *path,
 801                         SilcSFTPNameCallback callback,
 802                         void *context);
 803
 804 /****f* silcsftp/SilcSFTPAPI/silc_sftp_extended
 805  *
 806  * SYNOPSIS
 807  *
 808  *    void silc_sftp_extended(SilcSFTP sftp,
 809  *                            const char *request,
 810  *                            const unsigned char *data,
 811  *                            SilcUInt32 data_len,
 812  *                            SilcSFTPExtendedCallback callback,
 813  *                            void *context);
 814  *
 815  * DESCRIPTION
 816  *
 817  *    Performs an extended operation indicated by the `request' with
 818  *    optional extended operation data indicated by the `data'.  The callback
 819  *    is called to return any data associated with the extended request.
 820  *
 821  ***/
 822 void silc_sftp_extended(SilcSFTP sftp,
 823                         const char *request,
 824                         const unsigned char *data,
 825                         SilcUInt32 data_len,
 826                         SilcSFTPExtendedCallback callback,
 827                         void *context);
 828
 829
 830 /* SFTP Server Interface */
 831
 832 #include "silcsftp_fs.h"
 833
 834 /****f* silcsftp/SilcSFTPAPI/silc_sftp_server_start
 835  *
 836  * SYNOPSIS
 837  *
 838  *    SilcSFTP silc_sftp_server_start(SilcSFTPSendPacketCallback send_packet,
 839  *                                    void *send_context,
 840  *                                    SilcSFTPFilesystem fs);
 841  *
 842  * DESCRIPTION
 843  *
 844  *    Starts SFTP server and returns a context to it.  This function returns
 845  *    the allocated SFTP client context or NULL on error. The `send_packet'
 846  *    is called by the library when it needs to send a packet. The `fs' is the
 847  *    filesystem context allocated by the application.  Each socket connection
 848  *    should start its own server by calling this function.
 849  *
 850  ***/
 851 SilcSFTP silc_sftp_server_start(SilcSFTPSendPacketCallback send_packet,
 852                                 void *send_context,
 853                                 SilcSFTPFilesystem fs);
 854
 855 /****f* silcsftp/SilcSFTPAPI/silc_sftp_server_shutdown
 856  *
 857  * SYNOPSIS
 858  *
 859  *    void silc_sftp_server_shutdown(SilcSFTP sftp);
 860  *
 861  * DESCRIPTION
 862  *
 863  *    Shutdown's the SFTP server.  The caller is responsible of closing
 864  *    the associated socket connection.  The SFTP context is freed and is
 865  *    invalid after this function returns.
 866  *
 867  ***/
 868 void silc_sftp_server_shutdown(SilcSFTP sftp);
 869
 870 /****d* silcsftp/SilcSFTPAPI/SilcSFTPMonitors
 871  *
 872  * NAME
 873  *
 874  *    typedef enum { ... } SilcSFTPMonitors;
 875  *
 876  * DESCRIPTION
 877  *
 878  *    SFTP server monitor types. These can be masked together to monitor
 879  *    various client requests.
 880  *
 881  * SOURCE
 882  */
 883 typedef enum {
 884   SILC_SFTP_MONITOR_INIT        = 0x0001,
 885   SILC_SFTP_MONITOR_OPEN        = 0x0002,
 886   SILC_SFTP_MONITOR_CLOSE       = 0x0004,
 887   SILC_SFTP_MONITOR_READ        = 0x0008,
 888   SILC_SFTP_MONITOR_WRITE       = 0x0010,
 889   SILC_SFTP_MONITOR_REMOVE      = 0x0020,
 890   SILC_SFTP_MONITOR_RENAME      = 0x0040,
 891   SILC_SFTP_MONITOR_MKDIR       = 0x0080,
 892   SILC_SFTP_MONITOR_RMDIR       = 0x0100,
 893   SILC_SFTP_MONITOR_OPENDIR     = 0x0200,
 894   SILC_SFTP_MONITOR_READDIR     = 0x0400,
 895   SILC_SFTP_MONITOR_STAT        = 0x0800,
 896   SILC_SFTP_MONITOR_LSTAT       = 0x1000,
 897   SILC_SFTP_MONITOR_FSTAT       = 0x2000,
 898   SILC_SFTP_MONITOR_SETSTAT     = 0x4000,
 899   SILC_SFTP_MONITOR_FSETSTAT    = 0x8000,
 900   SILC_SFTP_MONITOR_READLINK    = 0x10000,
 901   SILC_SFTP_MONITOR_SYMLINK     = 0x20000,
 902   SILC_SFTP_MONITOR_REALPATH    = 0x40000,
 903   SILC_SFTP_MONITOR_EXTENDED    = 0x80000,
 904 } SilcSFTPMonitors;
 905 /***/
 906
 907 /****s* silcsftp/SilcSFTPAPI/SilcSFTPMonitorData
 908  *
 909  * NAME
 910  *
 911  *    typedef struct { ... } *SilcSFTPMonitorData, SilcSFTPMonitorDataStruct;
 912  *
 913  * DESCRIPTION
 914  *
 915  *    This structure includes the monitor type specific data.  The
 916  *    application can check what the client has requested from this
 917  *    structure.
 918  *
 919  * SOURCE
 920  */
 921 typedef struct {
 922   SilcSFTPVersion version;      /* _INIT */
 923   char *name;                   /* _OPEN, _REMOVE, _RENAME, _MKDIR,
 924                                    _RMDIR, _OPENDIR, _STAT, _LSTAT,
 925                                    _SETSTAT, _READLINK, _SYMLINK, _REALPATH */
 926   char *name2;                  /* _RENAME, _SYMLINK */
 927   SilcSFTPFileOperation pflags; /* _OPEN */
 928   SilcUInt64 offset;            /* _READ, _WRITE */
 929   SilcUInt32 data_len;          /* _READ, _WRITE */
 930   SilcSFTPName names;           /* _READDIR, _READLINK, _REALPATH */
 931 } *SilcSFTPMonitorData, SilcSFTPMonitorDataStruct;
 932 /***/
 933
 934 /****f* silcsftp/SilcSFTPAPI/SilcSFTPMonitor
 935  *
 936  * SYNOPSIS
 937  *
 938  *    typedef void (*SilcSFTPMonitor)(SilcSFTP sftp
 939  *                                    SilcSFTPMonitors type,
 940  *                                    const SilcSFTPMonitorData data,
 941  *                                    void *context);
 942  *
 943  * DESCRIPTION
 944  *
 945  *    Monitor callback that is called when an specified request is
 946  *    received from client.  The `type' is the requested type that
 947  *    was being monitored.
 948  *
 949  ***/
 950 typedef void (*SilcSFTPMonitor)(SilcSFTP sftp,
 951                                 SilcSFTPMonitors type,
 952                                 const SilcSFTPMonitorData data,
 953                                 void *context);
 954
 955 /****f* silcsftp/SilcSFTPAPI/silc_sftp_server_set_monitor
 956  *
 957  * SYNOPSIS
 958  *
 959  *    void silc_sftp_server_set_monitor(SilcSFTP sftp,
 960  *                                      SilcSFTPMonitors monitors,
 961  *                                      SilcSFTPMonitor monitor,
 962  *                                      void *context);
 963  *
 964  * DESCRIPTION
 965  *
 966  *    Sets monitor callback to monitor various request sent by an client.
 967  *    When request that has been set in the `monitors' is received the
 968  *    monitor callback will be called to notify the caller.
 969  *
 970  ***/
 971 void silc_sftp_server_set_monitor(SilcSFTP sftp,
 972                                   SilcSFTPMonitors monitors,
 973                                   SilcSFTPMonitor monitor,
 974                                   void *context);
 975
 976 /* Function that is called to process the incmoing SFTP packet. */
 977 /* XXX Some day this will go away and we have automatic receive callbacks
 978    for SilcSocketConnection API or SilcPacketContext API. */
 979 void silc_sftp_server_receive_process(SilcSFTP sftp,
 980                                       SilcSocketConnection sock,
 981                                       SilcPacketContext *packet);
 982
 983 #endif /* SILCSFTP_H */