## SSL support functions

SSL support functions — Functions to send and receive encrypted data over a socket.

## Synopsis

    typedef             GnomeVFSSSL;
    gboolean            gnome_vfs_ssl_enabled               (void);
    GnomeVFSResult      gnome_vfs_ssl_create                (GnomeVFSSSL **handle_return,
                                                             const char *host,
                                                             unsigned int port,
                                                             GnomeVFSCancellation *cancellation);
    GnomeVFSResult      gnome_vfs_ssl_create_from_fd        (GnomeVFSSSL **handle_return,
                                                             gint fd,
                                                             GnomeVFSCancellation *cancellation);
    GnomeVFSResult      gnome_vfs_ssl_read                  (GnomeVFSSSL *ssl,
                                                             gpointer buffer,
                                                             GnomeVFSFileSize bytes,
                                                             GnomeVFSFileSize *bytes_read,
                                                             GnomeVFSCancellation *cancellation);
    GnomeVFSResult      gnome_vfs_ssl_write                 (GnomeVFSSSL *ssl,
                                                             gconstpointer buffer,
                                                             GnomeVFSFileSize bytes,
                                                             GnomeVFSFileSize *bytes_written,
                                                             GnomeVFSCancellation *cancellation);
    void                gnome_vfs_ssl_destroy               (GnomeVFSSSL *ssl,
                                                             GnomeVFSCancellation *cancellation);
    GnomeVFSSocket *    gnome_vfs_ssl_to_socket             (GnomeVFSSSL *ssl);
    GnomeVFSResult      gnome_vfs_ssl_set_timeout           (GnomeVFSSSL *ssl,
                                                             GTimeVal *timeout,
                                                             GnomeVFSCancellation *cancellation);

## Description

## Details

### GnomeVFSSSL

    typedef struct GnomeVFSSSL GnomeVFSSSL;

### gnome_vfs_ssl_enabled ()

    gboolean            gnome_vfs_ssl_enabled               (void);

Checks whether gnome-vfs was compiled with SSL support.

Returns : | `TRUE` if gnome-vfs was compiled with SSL support, otherwise `FALSE`.

### gnome_vfs_ssl_create ()

    GnomeVFSResult      gnome_vfs_ssl_create                (GnomeVFSSSL **handle_return,
                                                             const char *host,
                                                             unsigned int port,
                                                             GnomeVFSCancellation *cancellation);

Creates an SSL socket connection at `handle_return` to `host` using port `port`.

`handle_return` : | pointer to a GnomeVFSSSL struct, which will contain an allocated GnomeVFSSSL object on return.
`host` : | string indicating the hostname to establish an SSL connection with.
`port` : | port number to connect to.
`cancellation` : | handle allowing cancellation of the operation.
Returns : | GnomeVFSResult indicating the success of the operation.

### gnome_vfs_ssl_create_from_fd ()

    GnomeVFSResult      gnome_vfs_ssl_create_from_fd        (GnomeVFSSSL **handle_return,
                                                             gint fd,
                                                             GnomeVFSCancellation *cancellation);

Try to establish an SSL connection over the file descriptor `fd`.

`handle_return` : | pointer to a GnomeVFSSSL struct, which will contain an allocated GnomeVFSSSL object on return.
`fd` : | file descriptior to try and establish an SSL connection over.
`cancellation` : | handle allowing cancellation of the operation.
Returns : | a GnomeVFSResult indicating the success of the operation.

### gnome_vfs_ssl_read ()

    GnomeVFSResult      gnome_vfs_ssl_read                  (GnomeVFSSSL *ssl,
                                                             gpointer buffer,
                                                             GnomeVFSFileSize bytes,
                                                             GnomeVFSFileSize *bytes_read,
                                                             GnomeVFSCancellation *cancellation);

Read `bytes` bytes of data from the SSL socket `ssl` into `buffer`.

`ssl` : | SSL socket to read data from.
`buffer` : | allocated buffer of at least `bytes` bytes to write into.
`bytes` : | number of bytes to read from `ssl` into `buffer`.
`bytes_read` : | pointer to a GnomeVFSFileSize, will contain the number of bytes actually read from the socket `ssl` on return.
`cancellation` : | handle allowing cancellation of the operation.
Returns : | GnomeVFSResult indicating the success of the operation.

### gnome_vfs_ssl_write ()

    GnomeVFSResult      gnome_vfs_ssl_write                 (GnomeVFSSSL *ssl,
                                                             gconstpointer buffer,
                                                             GnomeVFSFileSize bytes,
                                                             GnomeVFSFileSize *bytes_written,
                                                             GnomeVFSCancellation *cancellation);

Write `bytes` bytes of data from `buffer` to `ssl`.

`ssl` : | SSL socket to write data to.
`buffer` : | data to write to the socket.
`bytes` : | number of bytes to write from `buffer` to `ssl`.
`bytes_written` : | pointer to a GnomeVFSFileSize, will contain the number of bytes actually written to the socket on return.
`cancellation` : | handle allowing cancellation of the operation.
Returns : | GnomeVFSResult indicating the success of the operation.

### gnome_vfs_ssl_destroy ()

    void                gnome_vfs_ssl_destroy               (GnomeVFSSSL *ssl,
                                                             GnomeVFSCancellation *cancellation);

Free resources used by `ssl` and close the connection.

`ssl` : | SSL socket to be closed and destroyed.
`cancellation` : | handle allowing cancellation of the operation.

### gnome_vfs_ssl_to_socket ()

    GnomeVFSSocket *    gnome_vfs_ssl_to_socket             (GnomeVFSSSL *ssl);

Wrap an SSL socket inside a standard GnomeVFSSocket.

`ssl` : | SSL socket to convert into a standard socket.
Returns : | a newly allocated GnomeVFSSocket corresponding to `ssl`.

### gnome_vfs_ssl_set_timeout ()

    GnomeVFSResult      gnome_vfs_ssl_set_timeout           (GnomeVFSSSL *ssl,
                                                             GTimeVal *timeout,
                                                             GnomeVFSCancellation *cancellation);

Set a timeout of `timeout`. If `timeout` is `NULL` following operations will block indefinitely).

Note if you set `timeout` to 0 (means tv_sec and tv_usec are both 0) every following operation will return immediately. (This can be used for polling.)

`ssl` : | SSL socket to set the timeout of.
`timeout` : | the timeout.
`cancellation` : | optional cancellation object.
Returns : | GnomeVFSResult indicating the success of the operation.

Since 2.8