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 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)(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  *                                         SilcUInt32 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                                      SilcUInt32 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  *                                             SilcUInt32 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                                          SilcUInt32 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  *                        SilcUInt64 offset,
 468  *                        SilcUInt32 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                     SilcUInt64 offset,
 482                     SilcUInt32 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  *                         SilcUInt64 offset,
 493  *                         const unsigned char *data,
 494  *                         SilcUInt32 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                      SilcUInt64 offset,
 508                      const unsigned char *data,
 509                      SilcUInt32 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  *                            SilcUInt32 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                         SilcUInt32 data_len,
 831                         SilcSFTPExtendedCallback callback,
 832                         void *context);
 833
 834
 835 /* SFTP Server Interface */
 836
 837 #include "silcsftp_fs.h"
 838
 839 /****f* silcsftp/SilcSFTPAPI/silc_sftp_server_start
 840  *
 841  * SYNOPSIS
 842  *
 843  *    SilcSFTP silc_sftp_server_start(SilcSocketConnection sock,
 844  *                                    SilcSFTPSendPacketCallback send_packet,
 845  *                                    void *send_context,
 846  *                                    SilcSFTPFilesystem fs);
 847  *
 848  * DESCRIPTION
 849  *
 850  *    Starts SFTP server by associating the socket connection `sock' to the
 851  *    created SFTP server context.  This function returns the allocated
 852  *    SFTP client context or NULL on error. The `send_packet' is called
 853  *    by the library when it needs to send a packet. The `fs' is the
 854  *    filesystem context allocated by the application.
 855  *
 856  ***/
 857 SilcSFTP silc_sftp_server_start(SilcSocketConnection sock,
 858                                 SilcSFTPSendPacketCallback send_packet,
 859                                 void *send_context,
 860                                 SilcSFTPFilesystem fs);
 861
 862 /****f* silcsftp/SilcSFTPAPI/silc_sftp_server_shutdown
 863  *
 864  * SYNOPSIS
 865  *
 866  *    void silc_sftp_server_shutdown(SilcSFTP sftp);
 867  *
 868  * DESCRIPTION
 869  *
 870  *    Shutdown's the SFTP server.  The caller is responsible of closing
 871  *    the associated socket connection.  The SFTP context is freed and is
 872  *    invalid after this function returns.
 873  *
 874  ***/
 875 void silc_sftp_server_shutdown(SilcSFTP sftp);
 876
 877 /****d* silcsftp/SilcSFTPAPI/SilcSFTPMonitors
 878  *
 879  * NAME
 880  *
 881  *    typedef enum { ... } SilcSFTPMonitors;
 882  *
 883  * DESCRIPTION
 884  *
 885  *    SFTP server monitor types. These can be masked together to monitor
 886  *    various client requests.
 887  *
 888  * SOURCE
 889  */
 890 typedef enum {
 891   SILC_SFTP_MONITOR_INIT        = 0x0001,
 892   SILC_SFTP_MONITOR_OPEN        = 0x0002,
 893   SILC_SFTP_MONITOR_CLOSE       = 0x0004,
 894   SILC_SFTP_MONITOR_READ        = 0x0008,
 895   SILC_SFTP_MONITOR_WRITE       = 0x0010,
 896   SILC_SFTP_MONITOR_REMOVE      = 0x0020,
 897   SILC_SFTP_MONITOR_RENAME      = 0x0040,
 898   SILC_SFTP_MONITOR_MKDIR       = 0x0080,
 899   SILC_SFTP_MONITOR_RMDIR       = 0x0100,
 900   SILC_SFTP_MONITOR_OPENDIR     = 0x0200,
 901   SILC_SFTP_MONITOR_READDIR     = 0x0400,
 902   SILC_SFTP_MONITOR_STAT        = 0x0800,
 903   SILC_SFTP_MONITOR_LSTAT       = 0x1000,
 904   SILC_SFTP_MONITOR_FSTAT       = 0x2000,
 905   SILC_SFTP_MONITOR_SETSTAT     = 0x4000,
 906   SILC_SFTP_MONITOR_FSETSTAT    = 0x8000,
 907   SILC_SFTP_MONITOR_READLINK    = 0x10000,
 908   SILC_SFTP_MONITOR_SYMLINK     = 0x20000,
 909   SILC_SFTP_MONITOR_REALPATH    = 0x40000,
 910   SILC_SFTP_MONITOR_EXTENDED    = 0x80000,
 911 } SilcSFTPMonitors;
 912 /***/
 913
 914 /****s* silcsftp/SilcSFTPAPI/SilcSFTPMonitorData
 915  *
 916  * NAME
 917  *
 918  *    typedef struct { ... } *SilcSFTPMonitorData, SilcSFTPMonitorDataStruct;
 919  *
 920  * DESCRIPTION
 921  *
 922  *    This structure includes the monitor type specific data.  The
 923  *    application can check what the client has requested from this
 924  *    structure.
 925  *
 926  * SOURCE
 927  */
 928 typedef struct {
 929   SilcSFTPVersion version;      /* _INIT */
 930   char *name;                   /* _OPEN, _REMOVE, _RENAME, _MKDIR,
 931                                    _RMDIR, _OPENDIR, _STAT, _LSTAT,
 932                                    _SETSTAT, _READLINK, _SYMLINK, _REALPATH */
 933   char *name2;                  /* _RENAME, _SYMLINK */
 934   SilcSFTPFileOperation pflags; /* _OPEN */
 935   SilcUInt64 offset;            /* _READ, _WRITE */
 936   SilcUInt32 data_len;          /* _READ, _WRITE */
 937   SilcSFTPName names;           /* _READDIR, _READLINK, _REALPATH */
 938 } *SilcSFTPMonitorData, SilcSFTPMonitorDataStruct;
 939 /***/
 940
 941 /****f* silcsftp/SilcSFTPAPI/SilcSFTPMonitor
 942  *
 943  * SYNOPSIS
 944  *
 945  *    typedef void (*SilcSFTPMonitor)(SilcSFTP sftp
 946  *                                    SilcSFTPMonitors type,
 947  *                                    const SilcSFTPMonitorData data,
 948  *                                    void *context);
 949  *
 950  * DESCRIPTION
 951  *
 952  *    Monitor callback that is called when an specified request is
 953  *    received from client.  The `type' is the requested type that
 954  *    was being monitored.
 955  *
 956  ***/
 957 typedef void (*SilcSFTPMonitor)(SilcSFTP sftp,
 958                                 SilcSFTPMonitors type,
 959                                 const SilcSFTPMonitorData data,
 960                                 void *context);
 961
 962 /****f* silcsftp/SilcSFTPAPI/silc_sftp_server_set_monitor
 963  *
 964  * SYNOPSIS
 965  *
 966  *    void silc_sftp_server_set_monitor(SilcSFTP sftp,
 967  *                                      SilcSFTPMonitors monitors,
 968  *                                      SilcSFTPMonitor monitor,
 969  *                                      void *context);
 970  *
 971  * DESCRIPTION
 972  *
 973  *    Sets monitor callback to monitor various request sent by an client.
 974  *    When request that has been set in the `monitors' is received the
 975  *    monitor callback will be called to notify the caller.
 976  *
 977  ***/
 978 void silc_sftp_server_set_monitor(SilcSFTP sftp,
 979                                   SilcSFTPMonitors monitors,
 980                                   SilcSFTPMonitor monitor,
 981                                   void *context);
 982
 983 /* Function that is called to process the incmoing SFTP packet. */
 984 /* XXX Some day this will go away and we have automatic receive callbacks
 985    for SilcSocketConnection API or SilcPacketContext API. */
 986 void silc_sftp_server_receive_process(SilcSFTP sftp,
 987                                       SilcSocketConnection sock,
 988                                       SilcPacketContext *packet);
 989
 990 #endif /* SILCSFTP_H */