lib/silcsftp/silcsftp.h

   1 /*
   2
   3   silcsftp.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 2001 - 2007 Pekka Riikonen
   8
   9   This program is free software; you can redistribute it and/or modify
  10   it under the terms of the GNU General Public License as published by
  11   the Free Software Foundation; version 2 of the License.
  12
  13   This program is distributed in the hope that it will be useful,
  14   but WITHOUT ANY WARRANTY; without even the implied warranty of
  15   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16   GNU General Public License for more details.
  17
  18 */
  19
  20 #ifndef SILCSFTP_H
  21 #define SILCSFTP_H
  22
  23 /****h* silcsftp/SILC SFTP Interface
  24  *
  25  * DESCRIPTION
  26  *
  27  * SILC SFTP Interface is the implementation of the Secure File Transfer
  28  * Protocol (or SSH File Transfer Protocol).  The interface defines the SFTP
  29  * client and the SFTP server.  The SFTP is the mandatory file transfer
  30  * protocol in the SILC protocol, and when used in SILC the SFTP packets are
  31  * encapsulated into SILC packets.  The SFTP server implementation is
  32  * filesystem independent and generic interface is defined to represent
  33  * filesystem access.
  34  *
  35  * The SilcSFTP context is the actual SFTP client or SFTP server, and each
  36  * SFTP session should create its own SFTP context.
  37  *
  38  * The SILC SFTP library is a generic SFTP implementation and not directly
  39  * related to either SILC or SSH.  It could be used for any general purpose
  40  * SFTP application.
  41  *
  42  ***/
  43
  44 /****s* silcsftp/SilcSFTPAPI/SilcSFTP
  45  *
  46  * NAME
  47  *
  48  *    typedef struct SilcSFTPStruct *SilcSFTP;
  49  *
  50  * DESCRIPTION
  51  *
  52  *    This context is the actual SFTP client and SFTP server, and is
  53  *    allocated by silc_sftp_client_start or silc_sftp_server_start and
  54  *    given as argument usually to all silc_sftp_* functions.  It is freed
  55  *    by the silc_sftp_client_shutdown or silc_sftp_server_shutdown
  56  *    functions.
  57  *
  58  ***/
  59 typedef struct SilcSFTPStruct *SilcSFTP;
  60
  61 /****d* silcsftp/SilcSFTPAPI/SilcSFTPVersion
  62  *
  63  * NAME
  64  *
  65  *    typedef SilcUInt32 SilcSFTPVersion;
  66  *
  67  * DESCRIPTION
  68  *
  69  *    SFTP Version type.
  70  *
  71  ***/
  72 typedef SilcUInt32 SilcSFTPVersion;
  73
  74 /* SFTP protocol version */
  75 #define SILC_SFTP_PROTOCOL_VERSION       3
  76
  77 /****d* silcsftp/SilcSFTPAPI/SilcSFTPStatus
  78  *
  79  * NAME
  80  *
  81  *    typedef enum { ... } SilcSFTPStatus
  82  *
  83  * DESCRIPTION
  84  *
  85  *    SFTP protocol status types.  These enumerations is used to indicate
  86  *    the status of request.  The server can send these to the client when
  87  *    client has requested an operation.
  88  *
  89  * SOURCE
  90  */
  91 typedef enum {
  92   SILC_SFTP_STATUS_OK                  = 0,  /* Operation successful */
  93   SILC_SFTP_STATUS_EOF                 = 1,  /* No more data available */
  94   SILC_SFTP_STATUS_NO_SUCH_FILE        = 2,  /* File does not exist */
  95   SILC_SFTP_STATUS_PERMISSION_DENIED   = 3,  /* No sufficient permissions */
  96   SILC_SFTP_STATUS_FAILURE             = 4,  /* Operation failed */
  97   SILC_SFTP_STATUS_BAD_MESSAGE         = 5,  /* Bad message received */
  98   SILC_SFTP_STATUS_NO_CONNECTION       = 6,  /* No connection to remote */
  99   SILC_SFTP_STATUS_CONNECTION_LOST     = 7,  /* Connection lost to server */
 100   SILC_SFTP_STATUS_OP_UNSUPPORTED      = 8,  /* Operation unsupported */
 101   SILC_SFTP_STATUS_INVALID_HANDLE      = 9,  /* Invalid file handle */
 102   SILC_SFTP_STATUS_NO_SUCH_PATH        = 10, /* Path does not exist */
 103   SILC_SFTP_STATUS_FILE_ALREADY_EXIST  = 11, /* File already exists */
 104   SILC_SFTP_STATUS_WRITE_PROTECT       = 12, /* Read-only or protected */
 105   SILC_SFTP_STATUS_NO_MEDIA            = 13, /* No media available */
 106   SILC_SFTP_STATUS_NO_SPACE_ON_DEVICE  = 14, /* No space on device */
 107   SILC_SFTP_STATUS_QUOTA_EXCEEDED      = 15, /* Quota limit reached */
 108   SILC_SFTP_STATUS_UNKNOWN_PRINCIBLE   = 16, /* Unknown princible */
 109   SILC_SFTP_STATUS_LOCK_CONFLICT       = 17, /* File already locked */
 110   SILC_SFTP_STATUS_NOT_EMPTY           = 18, /* Directory not empty */
 111   SILC_SFTP_STATUS_NOT_A_DIRECTORY     = 19, /* Not a directory */
 112   SILC_SFTP_STATUS_INVALID_FILENAME    = 20, /* Invalid filename */
 113   SILC_SFTP_STATUS_LINK_LOOP           = 21, /* Too many symlinks */
 114   SILC_SFTP_STATUS_CANNOT_DELETE       = 22, /* Could not delete file */
 115   SILC_SFTP_STATUS_INVALID_PARAMETER   = 23, /* Invalid parameter */
 116   SILC_SFTP_STATUS_FILE_IS_A_DIRECTORY = 24, /* File is a directory file */
 117   SILC_SFTP_STATUS_BR_LOCK_CONFLICT    = 25, /* Byte range lock conflict */
 118   SILC_SFTP_STATUS_BR_LOCK_REFUSED     = 26, /* Byte range lock refused */
 119   SILC_SFTP_STATUS_DELETE_PENDING      = 27, /* File is being deleted */
 120   SILC_SFTP_STATUS_FILE_CORRUPT        = 28, /* File is corrupted */
 121 } SilcSFTPStatus;
 122 /***/
 123
 124 /****d* silcsftp/SilcSFTPAPI/SilcSFTPFileOperation
 125  *
 126  * NAME
 127  *
 128  *    typedef enum { ... } SilcSFTPFileOperation
 129  *
 130  * DESCRIPTION
 131  *
 132  *    SFTP protocol file operation flags.  These enumerations can be used
 133  *    by the client when client is opening an file, to indicate how it
 134  *    would like to open the file.
 135  *
 136  * SOURCE
 137  */
 138 typedef enum {
 139   SILC_SFTP_FXF_READ           = 0x00000001, /* Reading */
 140   SILC_SFTP_FXF_WRITE          = 0x00000002, /* Writing */
 141   SILC_SFTP_FXF_APPEND         = 0x00000004, /* Appending to end of file */
 142   SILC_SFTP_FXF_CREAT          = 0x00000008, /* Create if doesn't exist */
 143   SILC_SFTP_FXF_TRUNC          = 0x00000010, /* Truncate if exists */
 144   SILC_SFTP_FXF_EXCL           = 0x00000020, /* Don't create if exists */
 145 } SilcSFTPFileOperation;
 146 /***/
 147
 148 /****s* silcsftp/SilcSFTPAPI/SilcSFTPAttributes
 149  *
 150  * NAME
 151  *
 152  *    typedef struct { ... } *SilcSFTPAttributes, SilcSFTPAttributesStruct;
 153  *
 154  * DESCRIPTION
 155  *
 156  *    SFTP File attributes structure represents the attributes for a file.
 157  *    This structure can be used by the client to send attributes to the
 158  *    server, and by server to return file attributes to the client.
 159  *
 160  ***/
 161 typedef struct SilcSFTPAttributesObject {
 162   SilcUInt32 flags;             /* Flags to indicate present attributes */
 163   SilcUInt64 size;              /* Sife of the file in bytes */
 164   SilcUInt32 uid;               /* Unix user ID */
 165   SilcUInt32 gid;               /* Unix group ID */
 166   SilcUInt32 permissions;       /* POSIX file permission bitmask */
 167   SilcUInt32 atime;             /* Access time of file */
 168   SilcUInt32 mtime;             /* Modification time of file */
 169
 170   SilcUInt32 extended_count;    /* Extended type and data count */
 171   SilcBuffer *extended_type;
 172   SilcBuffer *extended_data;
 173 } *SilcSFTPAttributes, SilcSFTPAttributesStruct;
 174
 175 /****s* silcsftp/SilcSFTPAPI/SilcSFTPName
 176  *
 177  * NAME
 178  *
 179  *    typedef struct { ... } *SilcSFTPName, SilcSFTPNameStruct
 180  *
 181  * DESCRIPTION
 182  *
 183  *    SFTP Name structure represents the name reply received from the server.
 184  *    It includes the returned file(s) short and long file names and
 185  *    attributes for the file(s).  This is returned by the server for
 186  *    example when reading the contents of a directory.
 187  *
 188  ***/
 189 typedef struct SilcSFTPNameObject {
 190   char **filename;
 191   char **long_filename;
 192   SilcSFTPAttributes *attrs;
 193   SilcUInt32 count;                     /* Number of files */
 194 } *SilcSFTPName, SilcSFTPNameStruct;
 195
 196 /****s* silcsftp/SilcSFTPAPI/SilcSFTPHandle
 197  *
 198  * NAME
 199  *
 200  *    typedef struct SilcSFTPHandleStruct *SilcSFTPHandle;
 201  *
 202  * DESCRIPTION
 203  *
 204  *    This context represents an open file handle and is allocated by
 205  *    the library.  The application receives this context in the
 206  *    SilcSFTPHandleCallback function.
 207  *
 208  ***/
 209 typedef struct SilcSFTPHandleStruct *SilcSFTPHandle;
 210
 211 /****f* silcsftp/SilcSFTPAPI/SilcSFTPVersionCallback
 212  *
 213  * SYNOPSIS
 214  *
 215  *    typedef void (*SilcSFTPVersionCallback)(SilcSFTP sftp,
 216  *                                            SilcSFTPStatus status,
 217  *                                            SilcSFTPVersion version,
 218  *                                            void *context);
 219  *
 220  * DESCRIPTION
 221  *
 222  *    Version callback is called at the protocol initialization phase when
 223  *    the server returns the version of the protocol. The `version' indicates
 224  *    the version of the protocol.
 225  *
 226  ***/
 227 typedef void (*SilcSFTPVersionCallback)(SilcSFTP sftp,
 228                                         SilcSFTPStatus status,
 229                                         SilcSFTPVersion version,
 230                                         void *context);
 231
 232 /****f* silcsftp/SilcSFTPAPI/SilcSFTPErrorCallback
 233  *
 234  * SYNOPSIS
 235  *
 236  *    typedef void (*SilcSFTPErrorCallback)(SilcSFTP sftp,
 237  *                                          SilcSFTPStatus status,
 238  *                                          void *context);
 239  *
 240  * DESCRIPTION
 241  *
 242  *    Error callback is called if a connection error occurs during SFTP
 243  *    session.  If the connection or stream is closed this callback is
 244  *    called.  Other errors are delivered in other callbacks.  Only the
 245  *    SILC_SFTP_STATUS_EOF or SILC_SFTP_STATUS_NO_CONNECTION is delivered
 246  *    in this callback.
 247  *
 248  ***/
 249 typedef void (*SilcSFTPErrorCallback)(SilcSFTP sftp,
 250                                       SilcSFTPStatus status,
 251                                       void *context);
 252
 253 /****f* silcsftp/SilcSFTPAPI/SilcSFTPStatusCallback
 254  *
 255  * SYNOPSIS
 256  *
 257  *    typedef void (*SilcSFTPStatusCallback)(SilcSFTP sftp,
 258  *                                           SilcSFTPStatus status,
 259  *                                           const char *message,
 260  *                                           const char *language_tag,
 261  *                                           void *context);
 262  *
 263  * DESCRIPTION
 264  *
 265  *    Status callback is called every time server returns a status packet
 266  *    for a request the client has made. The `status' indicates the type
 267  *    of the status.  The `message' is optional error message received from
 268  *    the server, in language indicated by the `language_tag'.  Both of
 269  *    these pointers may be NULL.
 270  *
 271  ***/
 272 typedef void (*SilcSFTPStatusCallback)(SilcSFTP sftp,
 273                                        SilcSFTPStatus status,
 274                                        const char *message,
 275                                        const char *language_tag,
 276                                        void *context);
 277
 278 /****f* silcsftp/SilcSFTPAPI/SilcSFTPHandleCallback
 279  *
 280  * SYNOPSIS
 281  *
 282  *    typedef void (*SilcSFTPHandleCallback)(SilcSFTP sftp,
 283  *                                           SilcSFTPStatus status,
 284  *                                           SilcSFTPHandle handle,
 285  *                                           void *context);
 286  *
 287  * DESCRIPTION
 288  *
 289  *    Handle callback is called when the server returns a handle to the
 290  *    client as a result of some request client has made.  The `handle'
 291  *    is the file handle and the application can use it to perform file
 292  *    operations for the handle. Each of the returned handle must be
 293  *    also closed at some point with silc_sftp_close.
 294  *
 295  ***/
 296 typedef void (*SilcSFTPHandleCallback)(SilcSFTP sftp,
 297                                        SilcSFTPStatus status,
 298                                        SilcSFTPHandle handle,
 299                                        void *context);
 300
 301 /****f* silcsftp/SilcSFTPAPI/SilcSFTPDataCallback
 302  *
 303  * SYNOPSIS
 304  *
 305  *    typedef void (*SilcSFTPDataCallback)(SilcSFTP sftp,
 306  *                                         SilcSFTPStatus status,
 307  *                                         const unsigned char *data,
 308  *                                         SilcUInt32 data_len,
 309  *                                         void *context);
 310  *
 311  * DESCRIPTION
 312  *
 313  *    Data callback is called when data packet is received from the server.
 314  *    This is called for example when application is reading a file from
 315  *    the server.  The `data' is the raw data of length of `data_len'.
 316  *
 317  ***/
 318 typedef void (*SilcSFTPDataCallback)(SilcSFTP sftp,
 319                                      SilcSFTPStatus status,
 320                                      const unsigned char *data,
 321                                      SilcUInt32 data_len,
 322                                      void *context);
 323
 324 /****f* silcsftp/SilcSFTPAPI/SilcSFTPNameCallback
 325  *
 326  * SYNOPSIS
 327  *
 328  *    typedef void (*SilcSFTPNameCallback)(SilcSFTP sftp,
 329  *                                         SilcSFTPStatus status,
 330  *                                         const SilcSFTPName name,
 331  *                                         void *context);
 332  *
 333  * DESCRIPTION
 334  *
 335  *    Name callback is called when directory is being read by the client.
 336  *    The server returns one or more file names in one reply.  These file
 337  *    names are saved in the `filename' structures with their short and
 338  *    long name format, and with file attributes.
 339  *
 340  ***/
 341 typedef void (*SilcSFTPNameCallback)(SilcSFTP sftp,
 342                                      SilcSFTPStatus status,
 343                                      const SilcSFTPName name,
 344                                      void *context);
 345
 346 /****f* silcsftp/SilcSFTPAPI/SilcSFTPAttrCallback
 347  *
 348  * SYNOPSIS
 349  *
 350  *    typedef void (*SilcSFTPAttrCallback)(SilcSFTP sftp,
 351  *                                         SilcSFTPStatus status,
 352  *                                         const SilcSFTPAttributes attrs,
 353  *                                         void *context);
 354  *
 355  * DESCRIPTION
 356  *
 357  *    Attributes callback is called when the server returns the attributes
 358  *    for a file the client has requested.  The attributes are saved in
 359  *    the `attrs' structure.
 360  *
 361  ***/
 362 typedef void (*SilcSFTPAttrCallback)(SilcSFTP sftp,
 363                                      SilcSFTPStatus status,
 364                                      const SilcSFTPAttributes attrs,
 365                                      void *context);
 366
 367 /****f* silcsftp/SilcSFTPAPI/SilcSFTPExtendedCallback
 368  *
 369  * SYNOPSIS
 370  *
 371  *    typedef void (*SilcSFTPExtendedCallback)(SilcSFTP sftp,
 372  *                                             SilcSFTPStatus status,
 373  *                                             const unsigned char *data,
 374  *                                             SilcUInt32 data_len,
 375  *                                             void *context);
 376  *
 377  * DESCRIPTION
 378  *
 379  *    Extended request callback is called when client sends extended
 380  *    request to the server. The `data' is arbitrary data returned by the
 381  *    server and its encoding is the extended request specific.
 382  *
 383  ***/
 384 typedef void (*SilcSFTPExtendedCallback)(SilcSFTP sftp,
 385                                          SilcSFTPStatus status,
 386                                          const unsigned char *data,
 387                                          SilcUInt32 data_len,
 388                                          void *context);
 389
 390
 391 /* SFTP Client Interface */
 392
 393 /****f* silcsftp/SilcSFTPAPI/silc_sftp_client_start
 394  *
 395  * SYNOPSIS
 396  *
 397  *    SilcSFTP silc_sftp_client_start(SilcStream stream,
 398  *                                    SilcSchedule schedule,
 399  *                                    SilcSFTPVersionCallback version_cb,
 400  *                                    SilcSFTPErrorCallback error_cb,
 401  *                                    void *context);
 402  *
 403  * DESCRIPTION
 404  *
 405  *    Starts SFTP client and returns context to it.  The version callback
 406  *    indicated by the `version_cb' will be called after the SFTP session has
 407  *    been started and server has returned the version of the protocol.  The
 408  *    SFTP client context is returned in the callback too.  This returns the
 409  *    allocated SFTP client context or NULL on error.  The `stream' will be
 410  *    used to read and write the SFTP packets.  The `error_cb' will be called
 411  *    in case a stream error occurs, such as end of stream.
 412  *
 413  *    If `schedule' is NULL this will call silc_schedule_get_global to try to
 414  *    get global scheduler.
 415  *
 416  ***/
 417 SilcSFTP silc_sftp_client_start(SilcStream stream,
 418                                 SilcSchedule schedule,
 419                                 SilcSFTPVersionCallback version_cb,
 420                                 SilcSFTPErrorCallback error_cb,
 421                                 void *context);
 422
 423 /****f* silcsftp/SilcSFTPAPI/silc_sftp_client_shutdown
 424  *
 425  * SYNOPSIS
 426  *
 427  *    void silc_sftp_client_shutdown(SilcSFTP sftp);
 428  *
 429  * DESCRIPTION
 430  *
 431  *    Shutdown's the SFTP client.  The caller is responsible of closing
 432  *    the associated stream.  The SFTP context is freed and is invalid after
 433  *    this function returns.
 434  *
 435  ***/
 436 void silc_sftp_client_shutdown(SilcSFTP sftp);
 437
 438 /****f* silcsftp/SilcSFTPAPI/silc_sftp_open
 439  *
 440  * SYNOPSIS
 441  *
 442  *    void silc_sftp_open(SilcSFTP sftp,
 443  *                        const char *filename,
 444  *                        SilcSFTPFileOperation pflags,
 445  *                        SilcSFTPAttributes attrs,
 446  *                        SilcSFTPHandleCallback callback,
 447  *                        void *context);
 448  *
 449  * DESCRIPTION
 450  *
 451  *    Open a file indicated by the `filename' with flags indicated by the
 452  *    `pflags', and with attributes indicated by the `attsr'.  Calls the
 453  *    `callback' to return the opened file handle.
 454  *
 455  ***/
 456 void silc_sftp_open(SilcSFTP sftp,
 457                     const char *filename,
 458                     SilcSFTPFileOperation pflags,
 459                     SilcSFTPAttributes attrs,
 460                     SilcSFTPHandleCallback callback,
 461                     void *context);
 462
 463 /****f* silcsftp/SilcSFTPAPI/silc_sftp_close
 464  *
 465  * SYNOPSIS
 466  *
 467  *    void silc_sftp_close(SilcSFTP sftp,
 468  *                         SilcSFTPHandle handle,
 469  *                         SilcSFTPStatusCallback callback,
 470  *                         void *context);
 471  *
 472  * DESCRIPTION
 473  *
 474  *    Closes the file indicated by the file handle `handle'.  Calls the
 475  *    `callback' to indicate the status of the closing.
 476  *
 477  ***/
 478 void silc_sftp_close(SilcSFTP sftp,
 479                      SilcSFTPHandle handle,
 480                      SilcSFTPStatusCallback callback,
 481                      void *context);
 482
 483 /****f* silcsftp/SilcSFTPAPI/silc_sftp_read
 484  *
 485  * SYNOPSIS
 486  *
 487  *    void silc_sftp_read(SilcSFTP sftp,
 488  *                        SilcSFTPHandle handle,
 489  *                        SilcUInt64 offset,
 490  *                        SilcUInt32 len,
 491  *                        SilcSFTPDataCallback callback,
 492  *                        void *context);
 493  *
 494  * DESCRIPTION
 495  *
 496  *    Reads data from the file indicated by the file handle `handle' starting
 497  *    from the offset of `offset' at most `len' bytes.  The `callback' is
 498  *    called to return the read data.
 499  *
 500  ***/
 501 void silc_sftp_read(SilcSFTP sftp,
 502                     SilcSFTPHandle handle,
 503                     SilcUInt64 offset,
 504                     SilcUInt32 len,
 505                     SilcSFTPDataCallback callback,
 506                     void *context);
 507
 508 /****f* silcsftp/SilcSFTPAPI/silc_sftp_write
 509  *
 510  * SYNOPSIS
 511  *
 512  *    void silc_sftp_write(SilcSFTP sftp,
 513  *                         SilcSFTPHandle handle,
 514  *                         SilcUInt64 offset,
 515  *                         const unsigned char *data,
 516  *                         SilcUInt32 data_len,
 517  *                         SilcSFTPStatusCallback callback,
 518  *                         void *context);
 519  *
 520  * DESCRIPTION
 521  *
 522  *    Writes to a file indicated by the file handle `handle' starting from
 523  *    offset of `offset' at most `data_len' bytes of `data'.  The `callback'
 524  *    is called to indicate the status of the writing.
 525  *
 526  ***/
 527 void silc_sftp_write(SilcSFTP sftp,
 528                      SilcSFTPHandle handle,
 529                      SilcUInt64 offset,
 530                      const unsigned char *data,
 531                      SilcUInt32 data_len,
 532                      SilcSFTPStatusCallback callback,
 533                      void *context);
 534
 535 /****f* silcsftp/SilcSFTPAPI/silc_sftp_remove
 536  *
 537  * SYNOPSIS
 538  *
 539  *    void silc_sftp_remove(SilcSFTP sftp,
 540  *                          const char *filename,
 541  *                          SilcSFTPStatusCallback callback,
 542  *                          void *context);
 543  *
 544  * DESCRIPTION
 545  *
 546  *    Removes a file indicated by the `filename'.  Calls the `callback'
 547  *    to indicate the status of the removing.
 548  *
 549  ***/
 550 void silc_sftp_remove(SilcSFTP sftp,
 551                       const char *filename,
 552                       SilcSFTPStatusCallback callback,
 553                       void *context);
 554
 555 /****f* silcsftp/SilcSFTPAPI/silc_sftp_rename
 556  *
 557  * SYNOPSIS
 558  *
 559  *    void silc_sftp_rename(SilcSFTP sftp,
 560  *                          const char *oldname,
 561  *                          const char *newname,
 562  *                          SilcSFTPStatusCallback callback,
 563  *                          void *context);
 564  *
 565  * DESCRIPTION
 566  *
 567  *    Renames a file indicated by the `oldname' to the name `newname'.  The
 568  *    `callback' is called to indicate the status of the renaming.
 569  *
 570  ***/
 571 void silc_sftp_rename(SilcSFTP sftp,
 572                       const char *oldname,
 573                       const char *newname,
 574                       SilcSFTPStatusCallback callback,
 575                       void *context);
 576
 577 /****f* silcsftp/SilcSFTPAPI/silc_sftp_mkdir
 578  *
 579  * SYNOPSIS
 580  *
 581  *    void silc_sftp_mkdir(SilcSFTP sftp,
 582  *                         const char *path,
 583  *                         SilcSFTPAttributes attrs,
 584  *                         SilcSFTPStatusCallback callback,
 585  *                         void *context);
 586  *
 587  * DESCRIPTION
 588  *
 589  *    Creates a new directory indicated by the `path' with attributes indicated
 590  *    by the `attrs'. The `callback' is called to indicate the status of the
 591  *    creation.
 592  *
 593  ***/
 594 void silc_sftp_mkdir(SilcSFTP sftp,
 595                      const char *path,
 596                      SilcSFTPAttributes attrs,
 597                      SilcSFTPStatusCallback callback,
 598                      void *context);
 599
 600 /****f* silcsftp/SilcSFTPAPI/silc_sftp_rmdir
 601  *
 602  * SYNOPSIS
 603  *
 604  *    void silc_sftp_rmdir(SilcSFTP sftp,
 605  *                         const char *path,
 606  *                         SilcSFTPStatusCallback callback,
 607  *                         void *context);
 608  *
 609  * DESCRIPTION
 610  *
 611  *    Removes a directory indicated by the `path' and calls the `callback'
 612  *    to indicate the status of the removal.
 613  *
 614  ***/
 615 void silc_sftp_rmdir(SilcSFTP sftp,
 616                      const char *path,
 617                      SilcSFTPStatusCallback callback,
 618                      void *context);
 619
 620 /****f* silcsftp/SilcSFTPAPI/silc_sftp_opendir
 621  *
 622  * SYNOPSIS
 623  *
 624  *    void silc_sftp_opendir(SilcSFTP sftp,
 625  *                           const char *path,
 626  *                           SilcSFTPHandleCallback callback,
 627  *                           void *context);
 628  *
 629  * DESCRIPTION
 630  *
 631  *    Opens a directory indicated by the `path'.  The `callback' is called
 632  *    to return the opened file handle.
 633  *
 634  ***/
 635 void silc_sftp_opendir(SilcSFTP sftp,
 636                        const char *path,
 637                        SilcSFTPHandleCallback callback,
 638                        void *context);
 639
 640 /****f* silcsftp/SilcSFTPAPI/silc_sftp_readdir
 641  *
 642  * SYNOPSIS
 643  *
 644  *    void silc_sftp_readdir(SilcSFTP sftp,
 645  *                           SilcSFTPHandle handle,
 646  *                           SilcSFTPNameCallback callback,
 647  *                           void *context);
 648  *
 649  * DESCRIPTION
 650  *
 651  *    Reads the contents of the directory indicated by the `handle' and
 652  *    calls the `callback' to return the read file(s) from the directory.
 653  *
 654  ***/
 655 void silc_sftp_readdir(SilcSFTP sftp,
 656                        SilcSFTPHandle handle,
 657                        SilcSFTPNameCallback callback,
 658                        void *context);
 659
 660 /****f* silcsftp/SilcSFTPAPI/silc_sftp_stat
 661  *
 662  * SYNOPSIS
 663  *
 664  *    void silc_sftp_stat(SilcSFTP sftp,
 665  *                        const char *path,
 666  *                        SilcSFTPAttrCallback callback,
 667  *                        void *context);
 668  *
 669  * DESCRIPTION
 670  *
 671  *    Gets the file attributes for a file indicated by the `path'. This
 672  *    will follow symbolic links also. Calls the `callback' to return the
 673  *    file attributes.
 674  *
 675  ***/
 676 void silc_sftp_stat(SilcSFTP sftp,
 677                     const char *path,
 678                     SilcSFTPAttrCallback callback,
 679                     void *context);
 680
 681 /****f* silcsftp/SilcSFTPAPI/silc_sftp_lstat
 682  *
 683  * SYNOPSIS
 684  *
 685  *    void silc_sftp_lstat(SilcSFTP sftp,
 686  *                         const char *path,
 687  *                         SilcSFTPAttrCallback callback,
 688  *                         void *context);
 689  *
 690  * DESCRIPTION
 691  *
 692  *    Gets the file attributes for a file indicated by the `path'. This
 693  *    will not follow symbolic links. Calls the `callback' to return the
 694  *    file attributes
 695  *
 696  ***/
 697 void silc_sftp_lstat(SilcSFTP sftp,
 698                      const char *path,
 699                      SilcSFTPAttrCallback callback,
 700                      void *context);
 701
 702 /****f* silcsftp/SilcSFTPAPI/silc_sftp_fstat
 703  *
 704  * SYNOPSIS
 705  *
 706  *    void silc_sftp_fstat(SilcSFTP fstp,
 707  *                         SilcSFTPHandle handle,
 708  *                         SilcSFTPAttrCallback callback,
 709  *                         void *context);
 710  *
 711  * DESCRIPTION
 712  *
 713  *    Gets a file attributes for a opened file indicated by the `handle'.
 714  *    Calls the `callback' to return the file attributes.
 715  *
 716  ***/
 717 void silc_sftp_fstat(SilcSFTP fstp,
 718                      SilcSFTPHandle handle,
 719                      SilcSFTPAttrCallback callback,
 720                      void *context);
 721
 722 /****f* silcsftp/SilcSFTPAPI/silc_sftp_setstat
 723  *
 724  * SYNOPSIS
 725  *
 726  *    void silc_sftp_setstat(SilcSFTP sftp,
 727  *                           const char *path,
 728  *                           SilcSFTPAttributes attrs,
 729  *                           SilcSFTPStatusCallback callback,
 730  *                           void *context);
 731  *
 732  * DESCRIPTION
 733  *
 734  *    Sets a file attributes to a file indicated by the `path' with the
 735  *    attributes indicated by the `attrs'.  Calls the `callback' to indicate
 736  *    the status of the setting.
 737  *
 738  ***/
 739 void silc_sftp_setstat(SilcSFTP sftp,
 740                        const char *path,
 741                        SilcSFTPAttributes attrs,
 742                        SilcSFTPStatusCallback callback,
 743                        void *context);
 744
 745 /****f* silcsftp/SilcSFTPAPI/silc_sftp_fsetstat
 746  *
 747  * SYNOPSIS
 748  *
 749  *    void silc_sftp_fsetstat(SilcSFTP sftp,
 750  *                            SilcSFTPHandle handle,
 751  *                            SilcSFTPAttributes attrs,
 752  *                            SilcSFTPStatusCallback callback,
 753  *                            void *context);
 754  *
 755  * DESCRIPTION
 756  *
 757  *    Sets a file attributes to a opened file indicated by the `handle' with
 758  *    the attributes indicated by the `attrs'.  Calls the `callback' to
 759  *    indicate the status of the setting.
 760  *
 761  ***/
 762 void silc_sftp_fsetstat(SilcSFTP sftp,
 763                         SilcSFTPHandle handle,
 764                         SilcSFTPAttributes attrs,
 765                         SilcSFTPStatusCallback callback,
 766                         void *context);
 767
 768 /****f* silcsftp/SilcSFTPAPI/silc_sftp_readlink
 769  *
 770  * SYNOPSIS
 771  *
 772  *    void silc_sftp_readlink(SilcSFTP sftp,
 773  *                            const char *path,
 774  *                            SilcSFTPNameCallback callback,
 775  *                            void *context);
 776  *
 777  * DESCRIPTION
 778  *
 779  *    Reads the target of a symbolic link indicated by the `path'.  The
 780  *    `callback' is called to return the target of the symbolic link.
 781  *
 782  ***/
 783 void silc_sftp_readlink(SilcSFTP sftp,
 784                         const char *path,
 785                         SilcSFTPNameCallback callback,
 786                         void *context);
 787
 788 /****f* silcsftp/SilcSFTPAPI/silc_sftp_symlink
 789  *
 790  * SYNOPSIS
 791  *
 792  *    void silc_sftp_symlink(SilcSFTP sftp,
 793  *                           const char *linkpath,
 794  *                           const char *targetpath,
 795  *                           SilcSFTPStatusCallback callback,
 796  *                           void *context);
 797  *
 798  * DESCRIPTION
 799  *
 800  *    Creates a new symbolic link indicated by the `linkpath' to the target
 801  *    indicated by the `targetpath'.  The `callback' is called to indicate
 802  *    the status of creation.
 803  *
 804  ***/
 805 void silc_sftp_symlink(SilcSFTP sftp,
 806                        const char *linkpath,
 807                        const char *targetpath,
 808                        SilcSFTPStatusCallback callback,
 809                        void *context);
 810
 811 /****f* silcsftp/SilcSFTPAPI/silc_sftp_realpath
 812  *
 813  * SYNOPSIS
 814  *
 815  *    void silc_sftp_realpath(SilcSFTP sftp,
 816  *                            const char *path,
 817  *                            SilcSFTPNameCallback callback,
 818  *                            void *context);
 819  *
 820  * DESCRIPTION
 821  *
 822  *    Canonicalizes the path indicated by the `path' to a absolute path.
 823  *    The `callback' is called to return the absolute path.
 824  *
 825  ***/
 826 void silc_sftp_realpath(SilcSFTP sftp,
 827                         const char *path,
 828                         SilcSFTPNameCallback callback,
 829                         void *context);
 830
 831 /****f* silcsftp/SilcSFTPAPI/silc_sftp_extended
 832  *
 833  * SYNOPSIS
 834  *
 835  *    void silc_sftp_extended(SilcSFTP sftp,
 836  *                            const char *request,
 837  *                            const unsigned char *data,
 838  *                            SilcUInt32 data_len,
 839  *                            SilcSFTPExtendedCallback callback,
 840  *                            void *context);
 841  *
 842  * DESCRIPTION
 843  *
 844  *    Performs an extended operation indicated by the `request' with
 845  *    optional extended operation data indicated by the `data'.  The callback
 846  *    is called to return any data associated with the extended request.
 847  *
 848  ***/
 849 void silc_sftp_extended(SilcSFTP sftp,
 850                         const char *request,
 851                         const unsigned char *data,
 852                         SilcUInt32 data_len,
 853                         SilcSFTPExtendedCallback callback,
 854                         void *context);
 855
 856
 857 /* SFTP Server Interface */
 858
 859 #include "silcsftp_fs.h"
 860
 861 /****f* silcsftp/SilcSFTPAPI/silc_sftp_server_start
 862  *
 863  * SYNOPSIS
 864  *
 865  *    SilcSFTP silc_sftp_server_start(SilcStream stream,
 866  *                                    SilcSchedule schedule,
 867  *                                    SilcSFTPErrorCallback error_cb,
 868  *                                    void *context,
 869  *                                    SilcSFTPFilesystem fs);
 870  *
 871  * DESCRIPTION
 872  *
 873  *    Starts SFTP server and returns a context to it.  This function returns
 874  *    the allocated SFTP server context or NULL on error.  The `stream' is
 875  *    the stream (connection) to the client.  The `error_cb' will be called
 876  *    when the `stream' is ended (SILC_SFTP_STATUS_EOF).  The caller is
 877  *    responsible of closing and destroying the `stream'.  The `fs' is the
 878  *    filesystem context allocated by the application.
 879  *
 880  *    If `schedule' is NULL this will call silc_schedule_get_global to try to
 881  *    get global scheduler.
 882  *
 883  ***/
 884 SilcSFTP silc_sftp_server_start(SilcStream stream,
 885                                 SilcSchedule schedule,
 886                                 SilcSFTPErrorCallback error_cb,
 887                                 void *context,
 888                                 SilcSFTPFilesystem fs);
 889
 890 /****f* silcsftp/SilcSFTPAPI/silc_sftp_server_shutdown
 891  *
 892  * SYNOPSIS
 893  *
 894  *    void silc_sftp_server_shutdown(SilcSFTP sftp);
 895  *
 896  * DESCRIPTION
 897  *
 898  *    Shutdown the SFTP server.  The caller is responsible of closing the
 899  *    associated stream.  The SFTP context is freed and is invalid after
 900  *    this function returns.
 901  *
 902  ***/
 903 void silc_sftp_server_shutdown(SilcSFTP sftp);
 904
 905 /****d* silcsftp/SilcSFTPAPI/SilcSFTPMonitors
 906  *
 907  * NAME
 908  *
 909  *    typedef enum { ... } SilcSFTPMonitors;
 910  *
 911  * DESCRIPTION
 912  *
 913  *    SFTP server monitor types. These can be masked together to monitor
 914  *    various client requests.
 915  *
 916  * SOURCE
 917  */
 918 typedef enum {
 919   SILC_SFTP_MONITOR_INIT        = 0x0001,
 920   SILC_SFTP_MONITOR_OPEN        = 0x0002,
 921   SILC_SFTP_MONITOR_CLOSE       = 0x0004,
 922   SILC_SFTP_MONITOR_READ        = 0x0008,
 923   SILC_SFTP_MONITOR_WRITE       = 0x0010,
 924   SILC_SFTP_MONITOR_REMOVE      = 0x0020,
 925   SILC_SFTP_MONITOR_RENAME      = 0x0040,
 926   SILC_SFTP_MONITOR_MKDIR       = 0x0080,
 927   SILC_SFTP_MONITOR_RMDIR       = 0x0100,
 928   SILC_SFTP_MONITOR_OPENDIR     = 0x0200,
 929   SILC_SFTP_MONITOR_READDIR     = 0x0400,
 930   SILC_SFTP_MONITOR_STAT        = 0x0800,
 931   SILC_SFTP_MONITOR_LSTAT       = 0x1000,
 932   SILC_SFTP_MONITOR_FSTAT       = 0x2000,
 933   SILC_SFTP_MONITOR_SETSTAT     = 0x4000,
 934   SILC_SFTP_MONITOR_FSETSTAT    = 0x8000,
 935   SILC_SFTP_MONITOR_READLINK    = 0x10000,
 936   SILC_SFTP_MONITOR_SYMLINK     = 0x20000,
 937   SILC_SFTP_MONITOR_REALPATH    = 0x40000,
 938   SILC_SFTP_MONITOR_EXTENDED    = 0x80000,
 939 } SilcSFTPMonitors;
 940 /***/
 941
 942 /****s* silcsftp/SilcSFTPAPI/SilcSFTPMonitorData
 943  *
 944  * NAME
 945  *
 946  *    typedef struct { ... } *SilcSFTPMonitorData, SilcSFTPMonitorDataStruct;
 947  *
 948  * DESCRIPTION
 949  *
 950  *    This structure includes the monitor type specific data.  The
 951  *    application can check what the client has requested from this
 952  *    structure.  See the comments below what data is available for what
 953  *    monitor type.
 954  *
 955  * SOURCE
 956  */
 957 typedef struct SilcSFTPMonitorDataObject {
 958   SilcSFTPVersion version;      /* _INIT */
 959   char *name;                   /* _OPEN, _REMOVE, _RENAME, _MKDIR,
 960                                    _RMDIR, _OPENDIR, _STAT, _LSTAT,
 961                                    _SETSTAT, _READLINK, _SYMLINK, _REALPATH */
 962   char *name2;                  /* _RENAME, _SYMLINK */
 963   SilcSFTPFileOperation pflags; /* _OPEN */
 964   SilcUInt64 offset;            /* _READ, _WRITE */
 965   SilcUInt32 data_len;          /* _READ, _WRITE */
 966   SilcSFTPName names;           /* _READDIR, _READLINK, _REALPATH */
 967 } *SilcSFTPMonitorData, SilcSFTPMonitorDataStruct;
 968 /***/
 969
 970 /****f* silcsftp/SilcSFTPAPI/SilcSFTPMonitor
 971  *
 972  * SYNOPSIS
 973  *
 974  *    typedef void (*SilcSFTPMonitor)(SilcSFTP sftp
 975  *                                    SilcSFTPMonitors type,
 976  *                                    const SilcSFTPMonitorData data,
 977  *                                    void *context);
 978  *
 979  * DESCRIPTION
 980  *
 981  *    Monitor callback that is called when an specified request is
 982  *    received from client.  The `type' is the requested type that
 983  *    was being monitored.
 984  *
 985  ***/
 986 typedef void (*SilcSFTPMonitor)(SilcSFTP sftp,
 987                                 SilcSFTPMonitors type,
 988                                 const SilcSFTPMonitorData data,
 989                                 void *context);
 990
 991 /****f* silcsftp/SilcSFTPAPI/silc_sftp_server_set_monitor
 992  *
 993  * SYNOPSIS
 994  *
 995  *    void silc_sftp_server_set_monitor(SilcSFTP sftp,
 996  *                                      SilcSFTPMonitors monitors,
 997  *                                      SilcSFTPMonitor monitor,
 998  *                                      void *context);
 999  *
1000  * DESCRIPTION
1001  *
1002  *    Sets monitor callback to monitor various request sent by a client.
1003  *    When request that has been set in the `monitors' is received the
1004  *    monitor callback will be called to notify the caller.
1005  *
1006  ***/
1007 void silc_sftp_server_set_monitor(SilcSFTP sftp,
1008                                   SilcSFTPMonitors monitors,
1009                                   SilcSFTPMonitor monitor,
1010                                   void *context);
1011
1012 #endif /* SILCSFTP_H */