## GskHttpClient

GskHttpClient — The client end of an HTTP connection.

## Synopsis

                        GskHttpClientRequest;
    void                (*GskHttpClientResponse)            (GskHttpRequest *request,
                                                             GskHttpResponse *response,
                                                             GskStream *input,
                                                             gpointer hook_data);
    gboolean            (*GskHttpClientTrap)                (GskHttpClient *client,
                                                             gpointer data);
                        GskHttpClientClass;
                        GskHttpClient;
    #define             GSK_HTTP_CLIENT_FAST_NOTIFY
    #define             GSK_HTTP_CLIENT_DEFERRED_SHUTDOWN
    #define             GSK_HTTP_CLIENT_HOOK                (client)
    #define             GSK_HTTP_CLIENT_IS_FAST             (client)
    #define             gsk_http_client_trap_requestable    (client,func,shutdown,data,destroy)
    #define             gsk_http_client_untrap_requestable  (client)
    #define             gsk_http_client_is_requestable      (client)
    GskHttpClient *     gsk_http_client_new                 (void);
    void                gsk_http_client_notify_fast         (GskHttpClient *client,
                                                             gboolean is_fast);
    void                gsk_http_client_request             (GskHttpClient *client,
                                                             GskHttpRequest *request,
                                                             GskStream *post_data,
                                                             GskHttpClientResponse handle_response,
                                                             gpointer hook_data,
                                                             GDestroyNotify hook_destroy);
    void                gsk_http_client_shutdown_when_done  (GskHttpClient *client);
    void                gsk_http_client_propagate_content_read_shutdown
                                                            (GskHttpClient *client);

## Object Hierarchy

      GObject
       +----GskIO
             +----GskStream
                   +----GskHttpClient

## Description

This class manages the queuing of outgoing requests, and the handling of incoming responses.

## Details

### GskHttpClientRequest

    typedef struct _GskHttpClientRequest GskHttpClientRequest;

An opaque object representing a request that may be made to the HTTP server.

### GskHttpClientResponse ()

    void                (*GskHttpClientResponse)            (GskHttpRequest *request,
                                                             GskHttpResponse *response,
                                                             GskStream *input,
                                                             gpointer hook_data);

A callback to handle the response from the server. (The response content actually streams back -- at this point we may have merely have gotten the header.)

`request` : | the GskHttpRequest initially sent by the client.
`response` : | the GskHttpResponse parsed from the server.
`input` : | a GskStream which is the content, if any.
`hook_data` : | the argument to `gsk_http_client_request()`.

### GskHttpClientTrap ()

    gboolean            (*GskHttpClientTrap)                (GskHttpClient *client,
                                                             gpointer data);

Notification that the client is ready to take another HTTP request.

`client` : | the ready GskHttpClient
`data` : | data passed to `gsk_http_client_trap_requestable()`
Returns : | whether to keep getting new notifications.

### GskHttpClientClass

    typedef struct {
      GskStreamClass stream_class;
      void         (*set_poll_requestable) (GskHttpClient *client,
    					gboolean       do_poll);
      void         (*shutdown_requestable) (GskHttpClient *client);
    } GskHttpClientClass;

Class of the HTTP client stream. Not broadly useful.

GskStreamClass `stream_class`; | the base stream.
`set_poll_requestable` () | function called by the hook to change whether the HTTP client trap should be triggered.
`shutdown_requestable` () | function called by the hook to stop being able to accept new requests.

### GskHttpClient

    typedef struct _GskHttpClient GskHttpClient;

A stream which is the client side of an HTTP connection.

### GSK_HTTP_CLIENT_FAST_NOTIFY

    #define             GSK_HTTP_CLIENT_FAST_NOTIFY

### GSK_HTTP_CLIENT_DEFERRED_SHUTDOWN

    #define             GSK_HTTP_CLIENT_DEFERRED_SHUTDOWN

### GSK_HTTP_CLIENT_HOOK()

    #define             GSK_HTTP_CLIENT_HOOK(client)

Obtain the hook which is triggered by new ability to make a new request.

Mostly private.

`client` : | the client whose hook should be returned.

### GSK_HTTP_CLIENT_IS_FAST()

    #define             GSK_HTTP_CLIENT_IS_FAST(client)

`client` : |

### gsk_http_client_trap_requestable()

    #define             gsk_http_client_trap_requestable(client,func,shutdown,data,destroy)

Trap the event that the HTTP client is ready for another request to be issued.

If this is set to do "fast notify" (see `GSK_HTTP_CLIENT_IS_FAST()`), then this hook will be triggered nearly continuously.

`client` : | the HTTP client to watch.
`func` : | the callback for when a header is ready.
`shutdown` : | function called when no further requests can be made.
`data` : | data to pass to `func` and `shutdown`.
`destroy` : | function to call when the trap is removed.

### gsk_http_client_untrap_requestable()

    #define             gsk_http_client_untrap_requestable(client)

Untrap the event that the HTTP client is ready for another request to be issued.

`client` : | the HTTP client to stop watching.

### gsk_http_client_is_requestable()

    #define             gsk_http_client_is_requestable(client)

Get whether the HTTP client is able to handle another request.

Or at least, whether it thinks it is able to handle another request. The server may elect to set Connection: close and then further requests will never be processed.

`client` : | the client to query.

### gsk_http_client_new ()

    GskHttpClient *     gsk_http_client_new                 (void);

Create a new HTTP client protocol stream. Note that usually you want to hook this up to a transport layer, typically from `gsk_stream_new_connecting()`.

Returns : | the new client protocol stream.

### gsk_http_client_notify_fast ()

    void                gsk_http_client_notify_fast         (GskHttpClient *client,
                                                             gboolean is_fast);

Set whether the client should allow and want multiple outgoing requests before a single response has been received.

`client` : | the http client to affect.
`is_fast` : | whether to try to get requests without waiting for responses.

### gsk_http_client_request ()

    void                gsk_http_client_request             (GskHttpClient *client,
                                                             GskHttpRequest *request,
                                                             GskStream *post_data,
                                                             GskHttpClientResponse handle_response,
                                                             gpointer hook_data,
                                                             GDestroyNotify hook_destroy);

Queue or send a HTTP client request. The `handle_response` function will be called once the response header is available, and the content data will be available as a GskStream.

`client` : | the http client to transmit the outgoing request.
`request` : | a request which should be sent from the client.
`post_data` : | for PUT and POST requests, a stream of data to output.
`handle_response` : | function to call once an HTTP response header is received.
`hook_data` : | data to pass to `handle_response`.
`hook_destroy` : | method to call when the response is called or the request is aborted.

### gsk_http_client_shutdown_when_done ()

    void                gsk_http_client_shutdown_when_done  (GskHttpClient *client);

Set the client to shutdown after the current requests are done.

`client` : | the http client shut down.

### gsk_http_client_propagate_content_read_shutdown ()

    void                gsk_http_client_propagate_content_read_shutdown
                                                            (GskHttpClient *client);

Propagate shutdowns of the content-stream to the http-client.

`client` : | the http client to affect.