## GskHttpResponse

GskHttpResponse — An HTTP header that is sent from server to client.

## Synopsis

                        GskHttpResponse;
    GskHttpResponse *   gsk_http_response_new_blank         (void);
    GskHttpResponse *   gsk_http_response_new_redirect      (const char *location);
    GskHttpResponse *   gsk_http_response_from_request      (GskHttpRequest *request,
                                                             GskHttpStatus status_code,
                                                             gint64 length);
    gboolean            gsk_http_response_process_first_line
                                                            (GskHttpResponse *response,
                                                             const char *line);
    #define             gsk_http_response_set_status_code   (response, status)
    #define             gsk_http_response_get_status_code   (response)
    void                gsk_http_response_set_allowed_verbs (GskHttpResponse *response,
                                                             guint allowed);
    #define             gsk_http_response_get_allowed_verbs (header)
    #define             gsk_http_response_set_age           (response, age)
    #define             gsk_http_response_get_age           (response)
    #define             gsk_http_response_set_location      (response, location)
    #define             gsk_http_response_peek_location     (response)
    #define             gsk_http_response_set_etag          (response, etag)
    #define             gsk_http_response_peek_etag         (response)
    void                gsk_http_response_set_cache_control (GskHttpResponse *response,
                                                             GskHttpResponseCacheDirective *directive);
    #define             gsk_http_response_peek_cache_control(response)
    #define             gsk_http_response_set_last_modified (response, last_modified)
    #define             gsk_http_response_get_last_modified (response)
    #define             gsk_http_response_set_expires       (response, expires)
    #define             gsk_http_response_get_expires       (response)
    void                gsk_http_response_set_md5           (GskHttpResponse *response,
                                                             const guint8 *md5sum);
    const guint8 *      gsk_http_response_peek_md5          (GskHttpResponse *response);
    #define             gsk_http_response_set_server        (response, server)
    #define             gsk_http_response_peek_server       (response)
    void                gsk_http_response_set_retry_after   (GskHttpResponse *response,
                                                             gboolean is_relative,
                                                             glong time);
    void                gsk_http_response_set_no_retry_after
                                                            (GskHttpResponse *response);
    void                gsk_http_response_set_authenticate  (GskHttpResponse *response,
                                                             gboolean is_proxy_auth,
                                                             GskHttpAuthenticate *auth);
    GskHttpAuthenticate * gsk_http_response_peek_authenticate
                                                            (GskHttpResponse *response,
                                                             gboolean is_proxy_auth);
    gboolean            gsk_http_response_has_content_body  (GskHttpResponse *response,
                                                             GskHttpRequest *request);
    void                gsk_http_response_cache_directive_free
                                                            (GskHttpResponseCacheDirective *directive);
    GskHttpResponseCacheDirective * gsk_http_response_cache_directive_new
                                                            (void);
    void                gsk_http_response_cache_directive_set_no_cache_name
                                                            (GskHttpResponseCacheDirective *directive,
                                                             const char *name,
                                                             gsize name_len);
    void                gsk_http_response_cache_directive_set_private_name
                                                            (GskHttpResponseCacheDirective *directive,
                                                             const char *name,
                                                             gsize name_len);
    #define             gsk_http_response_get_content_subtype
    #define             gsk_http_response_get_content_type
    #define             gsk_http_response_set_content_subtype
    #define             gsk_http_response_set_content_type

## Object Hierarchy

      GObject
       +----GskHttpHeader
             +----GskHttpResponse

## Properties

      "age"                      glong                 : Read / Write
      "e-tag"                    gchar*                : Read / Write
      "expires"                  glong                 : Read / Write
      "last-modified"            glong                 : Read / Write
      "location"                 gchar*                : Read / Write
      "server"                   gchar*                : Read / Write
      "status-code"              GskHttpStatus         : Read / Write

## Description

A response is the last of two messages in an HTTP transaction. It indicates whether the request succeeded, or what went wrong. It may also include often information about the content.

## Details

### GskHttpResponse

    typedef struct _GskHttpResponse GskHttpResponse;

An instance of a HTTP response header.

### gsk_http_response_new_blank ()

    GskHttpResponse *   gsk_http_response_new_blank         (void);

Create a new, empty default response.

Returns : | the newly allocated response.

### gsk_http_response_new_redirect ()

    GskHttpResponse *   gsk_http_response_new_redirect      (const char *location);

Create a redirection HTTP response header.

We use the 302 ("Found") status code.

`location` : | the URL to redirect the client to, as a string.
Returns : | the newly allocated header.

### gsk_http_response_from_request ()

    GskHttpResponse *   gsk_http_response_from_request      (GskHttpRequest *request,
                                                             GskHttpStatus status_code,
                                                             gint64 length);

Create a response which macthes the request, with a caller-supplied status code and optional length.

`request` : | the client's request to match.
`status_code` : | the return status of the request.
`length` : | the length of the message, or -1 for unknown.
Returns : | a new, matching response.

### gsk_http_response_process_first_line ()

    gboolean            gsk_http_response_process_first_line
                                                            (GskHttpResponse *response,
                                                             const char *line);

Parse the first line of an HTTP response.

`response` : | response to initialize
`line` : | first line of response header.
Returns : | whether the line was the start of a valid HTTP-response.

### gsk_http_response_set_status_code()

    #define             gsk_http_response_set_status_code(response, status)

Set what kind of response is going to be given. See GskHttpStatus for a description of all the status codes defined in HTTP/1.1 (RFC 2616).

`response` : | the response to affect.
`status` : | the new status code.

### gsk_http_response_get_status_code()

    #define             gsk_http_response_get_status_code(response)

Query the status code from a response.

`response` : | the response to query.

### gsk_http_response_set_allowed_verbs ()

    void                gsk_http_response_set_allowed_verbs (GskHttpResponse *response,
                                                             guint allowed);

Set the Allow: header to indicate a particular set of HTTP verbs are allowed from the client. If you give a request with a verb which is not allowed, you should get a GSK_HTTP_STATUS_METHOD_NOT_ALLOWED response. That response MUST have an Allow: header.

`response` : | the response to affect.
`allowed` : | bits telling which type of requests this server allows. The bit for a verb 'Q' is (1 &lt;&lt; GSK_HTTP_VERB_Q); the default allowed bits are (1&lt;&lt;GSK_HTTP_VERB_GET) | (1&lt;&lt;GSK_HTTP_VERB_HEAD).

### gsk_http_response_get_allowed_verbs()

    #define             gsk_http_response_get_allowed_verbs(header)

Get the bitmask of verbs allowed by the server, according to the Allow: header line.

XXX: what should happen in the absence of an Allow header????

`header` : |

### gsk_http_response_set_age()

    #define             gsk_http_response_set_age(response, age)

Set the age of a response. This is only used for cached responses. It tells the length of time that the data has been sitting in the cache. [See RFC 2616, Section 14.6]

`response` : | the response to indicate the age of.
`age` : | the indicated age, or -1 to unset the age indication.

### gsk_http_response_get_age()

    #define             gsk_http_response_get_age(response)

Get the age of a response. This is only used for cached responses. It tells the length of time that the data has been sitting in the cache. [See RFC 2616, Section 14.6]

If there is no Age field, -1 is returned.

`response` : | the response to query.

### gsk_http_response_set_location()

    #define             gsk_http_response_set_location(response, location)

[RFC 2616, 14.30] The Location response-header field is used to redirect the recipient to a location other than the Request-URI for completion of the request or identification of a new resource. For 201 (Created) responses, the Location is that of the new resource which was created by the request. For 3xx responses, the location SHOULD indicate the server's preferred URI for automatic redirection to the resource. The field value consists of a single absolute URI.

`response` : | the response to affect.
`location` : | the absolute URI for the content the user is probably really interested in.

### gsk_http_response_peek_location()

    #define             gsk_http_response_peek_location(response)

Peek at the destination for a redirect. May return NULL if there is no redirect planned.

`response` : | the response to query.

### gsk_http_response_set_etag()

    #define             gsk_http_response_set_etag(response, etag)

Provide a unique tag for the content- this may be used by caches and proxy servers.

[RFC 2616, 14.19] The ETag response-header field provides the current value of the entity tag for the requested variant. The headers used with entity

This is typically used in conjunction with the If-Match, If-None-Match, and Vary. 14.24, 14.26 and 14.44, 13.3.3.

`response` : | the response to affect.
`etag` : | the entity-tag for the associated conetnt.

### gsk_http_response_peek_etag()

    #define             gsk_http_response_peek_etag(response)

Get the entity-tag for this content from the header. This is NULL by default, to indicate that there is no ETag field.

`response` : | the response to query.

### gsk_http_response_set_cache_control ()

    void                gsk_http_response_set_cache_control (GskHttpResponse *response,
                                                             GskHttpResponseCacheDirective *directive);

Set the cache-control flags in the header. Note that `directive` will be freed by the HTTP header when it is destroyed.

`response` : | the HTTP response header to affect.
`directive` : | the new cache control directive, stolen by the HTTP header.

### gsk_http_response_peek_cache_control()

    #define             gsk_http_response_peek_cache_control(response)

Obtain the GskHttpCacheDirective associated with the response.

`response` : | the HTTP response whose cache-directive should be returned.

### gsk_http_response_set_last_modified()

    #define             gsk_http_response_set_last_modified(response, last_modified)

[RFC 2616, Section 14.29] The Last-Modified entity-header field indicates the date and time at which the origin server believes the variant was last modified.

If the time is -1, then there will be no Last-Modified header printed.

`response` : | the response to affect.
`last_modified` : | the unix time the content was last modified.

### gsk_http_response_get_last_modified()

    #define             gsk_http_response_get_last_modified(response)

Get the time that the response advertises that the content was last modified. It returns -1 if there will be no such indication.

`response` : | the response to query.

### gsk_http_response_set_expires()

    #define             gsk_http_response_set_expires(response, expires)

[From RFC 2616, Section 14.21] The Expires entity-header field gives the date/time after which the response is considered stale. A stale cache entry may not normally be returned by a cache (either a proxy cache or a user agent cache) unless it is first validated with the origin server (or with an intermediate cache that has a fresh copy of the entity). See section 13.2 for further discussion of the expiration model.

The presence of an Expires field does not imply that the original resource will change or cease to exist at, before, or after that time.

`response` : | the header to affect.
`expires` : | the expiration time in standard unix notation, ie. seconds from 1Jan1970 GMT. Or -1 may be used to indicate that there is no Expires header.

### gsk_http_response_get_expires()

    #define             gsk_http_response_get_expires(response)

Get the expiration time for this content, or -1 if no expiration time given.

`response` : | the header to query.

### gsk_http_response_set_md5 ()

    void                gsk_http_response_set_md5           (GskHttpResponse *response,
                                                             const guint8 *md5sum);

Set the MD5 field of the HTTP response to the given `md5sum`. GSK does not attempt to verify the MD5 sum; the caller should be sure they have the right MD5 sum.

`response` : | the HTTP response whose content MD5 sum is being given.
`md5sum` : | the 16-byte binary value of the MD5 hash of the content. If this is NULL, unset the MD5 field.

### gsk_http_response_peek_md5 ()

    const guint8 *      gsk_http_response_peek_md5          (GskHttpResponse *response);

Get the MD5 sum associated with this response. (It should be the MD5 sum of the content stream).

It will return NULL if there is no associated content MD5 sum. This is the default state.

`response` : | the response to query.
Returns : | the MD5 checksum (as 16 binary bytes) or NULL.

### gsk_http_response_set_server()

    #define             gsk_http_response_set_server(response, server)

Set the server name of this HTTP header. This may be any ASCII string.

See RFC 2616, Section 14.38.

`response` : | the response to affect.
`server` : | the name of the server, which will be copied.

### gsk_http_response_peek_server()

    #define             gsk_http_response_peek_server(response)

Obtain a reference to the type of server from which this response came, as a C string. This field is optional, but is helpful for debugging, etc.

`response` : | the response to look for a server in

### gsk_http_response_set_retry_after ()

    void                gsk_http_response_set_retry_after   (GskHttpResponse *response,
                                                             gboolean is_relative,
                                                             glong time);

Set the Retry-After header for this response.

[From RFC 2616, Section 14.37] The Retry-After response-header field can be used with a 503 (Service Unavailable) response to indicate how long the service is expected to be unavailable to the requesting client. This field MAY also be used with any 3xx (Redirection) response to indicate the minimum time the user-agent is asked wait before issuing the redirected request.

`response` : | the response to set a Retry-After line in.
`is_relative` : | whether the time should be relative to the current time (in which case it is printed as a raw integer), or whether it is an absolute time (in which case it is printed in the standard date format.)
`time` : | the time in seconds. If is_relative, then its the number of seconds after the current time; otherwise, it's unix time (ie seconds after Jan 1 1970, GMT).

### gsk_http_response_set_no_retry_after ()

    void                gsk_http_response_set_no_retry_after
                                                            (GskHttpResponse *response);

Clear the Retry-After header for this response.

`response` : | the response to clear the Retry-After line from.

### gsk_http_response_set_authenticate ()

    void                gsk_http_response_set_authenticate  (GskHttpResponse *response,
                                                             gboolean is_proxy_auth,
                                                             GskHttpAuthenticate *auth);

Set the authentication for this response. This is like a key to get access to certain entities.

Proxy-Authorization is intended to provide access control to the proxy. Normal Authorization is passed through a proxy. See sections 14.8 for normal Authorization and 14.34.

`response` : | the response to adjust the authentication for.
`is_proxy_auth` : | whether to set the Proxy-Authorization or the Authorization field.
`auth` : | the new authentication to use in this response.

### gsk_http_response_peek_authenticate ()

    GskHttpAuthenticate * gsk_http_response_peek_authenticate
                                                            (GskHttpResponse *response,
                                                             gboolean is_proxy_auth);

Get the responseed authentication information.

`response` : | the response to query.
`is_proxy_auth` : | whether to query information about proxy authentication, or normal server authentication.
Returns : | the authentication information, or NULL if none exists (default).

### gsk_http_response_has_content_body ()

    gboolean            gsk_http_response_has_content_body  (GskHttpResponse *response,
                                                             GskHttpRequest *request);

Find out whether a HTTP Response should be accompanied by a body.

It also depends on the request, in particular, HEAD requests do not retrieve bodies.

`response` : | the response to query
`request` : | the request that provoked the response.
Returns : | whether the response should be accompanied by a body of data.

### gsk_http_response_cache_directive_free ()

    void                gsk_http_response_cache_directive_free
                                                            (GskHttpResponseCacheDirective *directive);

Deallocate a GskHttpResponseCacheDirective.

`directive` : | cache-directive to de-allocate.

### gsk_http_response_cache_directive_new ()

    GskHttpResponseCacheDirective * gsk_http_response_cache_directive_new
                                                            (void);

Returns : | the new cache response directive.

### gsk_http_response_cache_directive_set_no_cache_name ()

    void                gsk_http_response_cache_directive_set_no_cache_name
                                                            (GskHttpResponseCacheDirective *directive,
                                                             const char *name,
                                                             gsize name_len);

Intended for more detailed specification of no-cache data, which is never supposed to be cached.

[RFC 2616, 14.9.1] If the no-cache directive does specify one or more field-names, then a cache MAY use the response to satisfy a subsequent request, subject to any other restrictions on caching. However, the specified field-name(s) MUST NOT be sent in the response to a subsequent request without successful revalidation with the origin server. This allows an origin server to prevent the re-use of certain header fields in a response, while still allowing caching of the rest of the response.

good luck.

`directive` : | the cache directive to affect.
`name` : | new qualifier for how the no-cache data is allowed to be used.
`name_len` : |

### gsk_http_response_cache_directive_set_private_name ()

    void                gsk_http_response_cache_directive_set_private_name
                                                            (GskHttpResponseCacheDirective *directive,
                                                             const char *name,
                                                             gsize name_len);

Intended for more detailed specification of private cache data.

`directive` : | the cache directive to affect.
`name` : | new qualifier for how the private data is allowed to be used.
`name_len` : | length of name string

### gsk_http_response_get_content_subtype

    #define             gsk_http_response_get_content_subtype

### gsk_http_response_get_content_type

    #define             gsk_http_response_get_content_type

### gsk_http_response_set_content_subtype

    #define             gsk_http_response_set_content_subtype

### gsk_http_response_set_content_type

    #define             gsk_http_response_set_content_type

## Property Details

### The `"age"` property

      "age"                      glong                 : Read / Write

Age of content.

Allowed values: >= -1

Default value: -1

### The `"e-tag"` property

      "e-tag"                    gchar*                : Read / Write

Unique identifier for this content.

Default value: NULL

### The `"expires"` property

      "expires"                  glong                 : Read / Write

Length of time to wait for content to expire.

Allowed values: >= -1

Default value: -1

### The `"last-modified"` property

      "last-modified"            glong                 : Read / Write

Time this content was last changed.

Allowed values: >= -1

Default value: -1

### The `"location"` property

      "location"                 gchar*                : Read / Write

The URL of the content, for redirect responses.

Default value: NULL

### The `"server"` property

      "server"                   gchar*                : Read / Write

Name of this webserver program.

Default value: NULL

### The `"status-code"` property

      "status-code"              GskHttpStatus         : Read / Write

HTTP status code.

Default value: GSK_HTTP_STATUS_OK

## See Also

GskHttpHeader, GskHttpRequest