SSL support functions

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

## Synopsis

    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

### gnome_vfs_ssl_enabled ()

    gboolean    gnome_vfs_ssl_enabled           (void);

Checks whether GnomeVFS was compiled with SSL support.

Returns : | `TRUE` if GnomeVFS 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 GnmoeVFSSSL struct, which will contain an allocated GnomeVFSSSL object on return.
`host` : | string indicating the host to establish an SSL connection with.
`port` : | the 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 GnmoeVFSSSL 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 be read 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 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 from `buffer` to write 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);

Wrapper 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