## GskHttpRequest

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

## Synopsis

                        GskHttpRequest;
    void                gsk_http_request_add_cookie         (GskHttpRequest *header,
                                                             GskHttpCookie *cookie);
    void                gsk_http_request_remove_cookie      (GskHttpRequest *header,
                                                             GskHttpCookie *cookie);
    GskHttpCookie *     gsk_http_request_find_cookie        (GskHttpRequest *header,
                                                             const char *key);
    void                gsk_http_request_add_charsets       (GskHttpRequest *header,
                                                             GskHttpCharSet *char_sets);
    void                gsk_http_request_clear_charsets     (GskHttpRequest *header);
    void                gsk_http_request_add_content_encodings
                                                            (GskHttpRequest *header,
                                                             GskHttpContentEncodingSet *set);
    void                gsk_http_request_clear_content_encodings
                                                            (GskHttpRequest *header);
    void                gsk_http_request_add_transfer_encodings
                                                            (GskHttpRequest *header,
                                                             GskHttpTransferEncodingSet *set);
    void                gsk_http_request_clear_transfer_encodings
                                                            (GskHttpRequest *header);
    void                gsk_http_request_add_media          (GskHttpRequest *header,
                                                             GskHttpMediaTypeSet *set);
    void                gsk_http_request_clear_media        (GskHttpRequest *header);
    GskHttpRequest *    gsk_http_request_new_blank          (void);
    GskHttpRequest *    gsk_http_request_new                (GskHttpVerb verb,
                                                             const char *path);
    #define             gsk_http_request_set_verb           (request, verb)
    #define             gsk_http_request_get_verb           (request)
    #define             gsk_http_request_peek_from          (request)
    #define             gsk_http_request_set_from           (request, from)
    #define             gsk_http_request_set_if_modified_since(request, t)
    #define             gsk_http_request_get_if_modified_since(request)
    void                gsk_http_request_set_authorization  (GskHttpRequest *request,
                                                             gboolean is_proxy_auth,
                                                             GskHttpAuthorization *auth);
    #define             gsk_http_request_set_host           (request, host)
    #define             gsk_http_request_set_user_agent     (request, user_agent)
    #define             gsk_http_request_peek_user_agent    (request)
    GskHttpAuthorization * gsk_http_request_peek_authorization
                                                            (GskHttpRequest *request,
                                                             gboolean is_proxy_auth);
    void                gsk_http_request_cache_directive_free
                                                            (GskHttpRequestCacheDirective *directive);
    GskHttpRequestCacheDirective * gsk_http_request_cache_directive_new
                                                            (void);
    GskHttpRequestFirstLineStatus  gsk_http_request_parse_first_line
                                                            (GskHttpRequest *request,
                                                             const char *line,
                                                             GError **error);
    void                gsk_http_request_set_cache_control  (GskHttpRequest *request,
                                                             GskHttpRequestCacheDirective *directive);
    gboolean            gsk_http_request_has_content_body   (GskHttpRequest *request);
    char **             gsk_http_parse_cgi_query_string     (const char *query_string,
                                                             GError **error);
    GHashTable *        gsk_http_request_parse_cgi_query_string
                                                            (const char *query_string);

## Object Hierarchy

      GObject
       +----GskHttpHeader
             +----GskHttpRequest

## Properties

      "host"                     gchar*                : Read / Write
      "if-modified-since"        glong                 : Read / Write
      "max-forwards"             glong                 : Read / Write
      "path"                     gchar*                : Read / Write
      "referrer"                 gchar*                : Read / Write
      "user-agent"               gchar*                : Read / Write
      "verb"                     GskHttpVerb           : Read / Write

## Description

A request is the first of two messages in an HTTP transaction. It indicates the type of transaction, usually GET or POST, and the desired path, and other assorted flags.

## Details

### GskHttpRequest

    typedef struct {
      /* the command: GET, PUT, POST, HEAD, etc */
      GskHttpVerb                   verb;

      /* Note that HTTP/1.1 servers must accept the entire
       * URL being included in `path'! (maybe including http:// ... */
      char                         *path;

      GskHttpCharSet           *accept_charsets;              /* Accept-CharSet */
      GskHttpContentEncodingSet*accept_content_encodings;     /* Accept-Encoding */
      GskHttpTransferEncodingSet*accept_transfer_encodings;   /* TE */
      GskHttpMediaTypeSet      *accept_media_types;           /* Accept */
      GskHttpAuthorization     *authorization;                /* Authorization */
      GskHttpLanguageSet       *accept_languages;             /* Accept-Languages */
      char                     *host;                         /* Host */

      gboolean                  had_if_match;
      char                    **if_match;             /* If-Match */
      glong                     if_modified_since;    /* If-Modified-Since */
      char                     *user_agent;           /* User-Agent */

      char                     *referrer;             /* Referer */

      char                     *from;      /* The From: header (sect 14.22) */

      /* List of Cookie: headers. */
      GSList                   *cookies;

      GskHttpAuthorization     *proxy_authorization;

      int                       keep_alive_seconds;   /* -1 if not used */

      /* rarely used: */
      int                       max_forwards;         /* -1 if not used */

      /* Nonstandard User-Agent information.
         Many browsers provide this data to allow
         dynamic content to take advantage of the
         client configuration.  (0 indicated "not supplied").  */
      unsigned                  ua_width, ua_height;
      char                     *ua_color;
      char                     *ua_os;
      char                     *ua_cpu;
      char                     *ua_language;

      GskHttpRequestCacheDirective *cache_control;        /* Cache-Control */
    } GskHttpRequest;

An instance of a HTTP request header.

GskHttpVerb `verb`; | type of request (the intended action).
char *`path`; | the location of the resource to affect.
GskHttpCharSet *`accept_charsets`; | list of character-sets acceptable to the client.
GskHttpContentEncodingSet *`accept_content_encodings`; | list of content-encodings acceptable to the client.
GskHttpTransferEncodingSet *`accept_transfer_encodings`; | list of transfer-encodings acceptable to the client.
GskHttpMediaTypeSet *`accept_media_types`; | list of media-types acceptable to the client.
GskHttpAuthorization *`authorization`; | optional authorization information.
GskHttpLanguageSet *`accept_languages`; |
char *`host`; | optional host header, required principally on machines which do virtual hosting.
gboolean `had_if_match`; | whether an If-Match header is present.
char **`if_match`; |
glong `if_modified_since`; | unix time or -1 if no such header present.
char *`user_agent`; | program or agent making the request.
char *`referrer`; | URL which led us to this resource.
char *`from`; |
GSList *`cookies`; | list of cookies.
GskHttpAuthorization *`proxy_authorization`; |
int `keep_alive_seconds`; |
int `max_forwards`; |
unsigned ua_width `ua_height`; |
char *`ua_color`; |
char *`ua_os`; |
char *`ua_cpu`; |
char *`ua_language`; |
GskHttpRequestCacheDirective *`cache_control`; |

### gsk_http_request_add_cookie ()

    void                gsk_http_request_add_cookie         (GskHttpRequest *header,
                                                             GskHttpCookie *cookie);

Add a Cookie header line to a request.

Cookies are defined in RFC 2965, a draft standard.

[Section 3.3.4] Sending Cookies to the Origin Server. When [the user-agent] sends a request to an origin server, the user agent includes a Cookie request header if it has stored cookies that are applicable to the request, based on (1) the request-host and request-port; (2) the request-URI; (3) the cookie's age.

`header` : | the request to affect.
`cookie` : | the cookie to add to the request. It will be freed when the request is freed.

### gsk_http_request_remove_cookie ()

    void                gsk_http_request_remove_cookie      (GskHttpRequest *header,
                                                             GskHttpCookie *cookie);

Remove a cookie from the request's list and delete it.

`header` : | the request to affect.
`cookie` : | the cookie to remove from the request.

### gsk_http_request_find_cookie ()

    GskHttpCookie *     gsk_http_request_find_cookie        (GskHttpRequest *header,
                                                             const char *key);

Find a cookie provided in the request by key.

`header` : | the request to query.
`key` : | the key field of the cookie to return.
Returns : | a pointer to the cookie, or NULL if not found.

### gsk_http_request_add_charsets ()

    void                gsk_http_request_add_charsets       (GskHttpRequest *header,
                                                             GskHttpCharSet *char_sets);

Add Accept-CharSet headers to the header. The char-sets will be freed when `header` is destroyed.

A CharSet is a string representing a Character Set, and an optional real quality factor for that particular Character Set. (The default is 1.0)

The CharSet "*" matches all other Character Sets. If no "*" is given, then it is as though all other character sets were given a quality of 0.0.

If no Accept-CharSet header is given, then all character sets are equally acceptable.

If a server cannot meet character set requirements, it SHOULD response with an error (GSK_HTTP_STATUS_NOT_ACCEPTABLE) but it may also ignore it, and send output in a character-set the client has not suggested.

See RFC 2616, Section 14.2.

`header` : | the request to affect.
`char_sets` : | list of a GskHttpCharSet's to indicate are accepted.

### gsk_http_request_clear_charsets ()

    void                gsk_http_request_clear_charsets     (GskHttpRequest *header);

Delete all accepted char-sets from the HTTP request.

This has the effect of leaving a server free to use any character set.

`header` : | the request to affect.

### gsk_http_request_add_content_encodings ()

    void                gsk_http_request_add_content_encodings
                                                            (GskHttpRequest *header,
                                                             GskHttpContentEncodingSet *set);

Add Accept-Encoding lines to the header. Each GskHttpContentEncodingSet represents a single possible encoding and an optional associated quality factor.

The rules for conduct are the same as for character set, with the exception that if no Accept-Encoding line is given then the 'identity' encoding should be preferred.

Note that the GSK http server and client handle content encoding automatically, and will do the correct thing without your intervention.

See RFC 2616, Section 14.3.

`header` : | the request to affect.
`set` : | list of a GskHttpContentEncodingSet's to indicate are acceptable. The list is taken over by the header; you must not free it or use it further.

### gsk_http_request_clear_content_encodings ()

    void                gsk_http_request_clear_content_encodings
                                                            (GskHttpRequest *header);

Delete all accepted encodings from the HTTP request.

This has the effect of leaving a server free to use any content encoding.

`header` : | the request to affect.

### gsk_http_request_add_transfer_encodings ()

    void                gsk_http_request_add_transfer_encodings
                                                            (GskHttpRequest *header,
                                                             GskHttpTransferEncodingSet *set);

The rules for conduct are the same as for character set, with the exception that the defaults are 'none' for HTTP 1.0 clients, and 'none' and 'chunked' for HTTP 1.1 clients.

Note that the GSK http server and client handle content encoding automatically, and will do the correct thing without your intervention.

This corresponds to the TE: header. See RFC 2616, Section 14.39.

`header` : | the request to affect.
`set` : | list of a GskHttpTransferEncodingSet's to indicate are acceptable. The list is taken over by the header; you must not free it or use it further.

### gsk_http_request_clear_transfer_encodings ()

    void                gsk_http_request_clear_transfer_encodings
                                                            (GskHttpRequest *header);

Delete all accepted transfer encodings from the HTTP request.

This has the effect of leaving a server free to use just no encoding for HTTP 1.0 clients and also 'chunked' for HTTP 1.1 clients.

`header` : | the request to affect.

### gsk_http_request_add_media ()

    void                gsk_http_request_add_media          (GskHttpRequest *header,
                                                             GskHttpMediaTypeSet *set);

Add Accept: headers to the header. The media-type-sets will be freed when `header` is destroyed.

A MediaSet is a range of media accepted, with quality factors as for `gsk_http_request_add_charsets()`.

Note that '*' in a subtype applies to all media with that major type, but if a specific subtype matches, then it's quality is given priority.

XXX: Also, there is an accept-extension 'level='... find out what it does!

See RFC 2616, Section 14.1.

`header` : | the request to affect.
`set` : | list of a GskHttpMediaTypeSet's to indicate are acceptable.

### gsk_http_request_clear_media ()

    void                gsk_http_request_clear_media        (GskHttpRequest *header);

Delete all accepted media-type-sets from the HTTP request.

`header` : | the request to affect.

### gsk_http_request_new_blank ()

    GskHttpRequest *    gsk_http_request_new_blank          (void);

Create a new empty HTTP request.

Returns : | the new request.

### gsk_http_request_new ()

    GskHttpRequest *    gsk_http_request_new                (GskHttpVerb verb,
                                                             const char *path);

Create a new simple HTTP request.

`verb` : | what type of request to make.
`path` : | path requested.
Returns : | the new request.

### gsk_http_request_set_verb()

    #define             gsk_http_request_set_verb(request, verb)

The verb is GSK's name for the type of action being requested. It is the very first word of the HTTP transaction. See GskHttpVerb for a list.

`request` : | the request to affect.
`verb` : | the new HTTP request verb.

### gsk_http_request_get_verb()

    #define             gsk_http_request_get_verb(request)

Get the type of action being requested. See GskHttpVerb for a list.

Every HTTP server should know GET and HEAD requested; other requests might not be allowed unless the server had indicated that they are with a "Allow" response header.

`request` : | the request to query.

### gsk_http_request_peek_from()

    #define             gsk_http_request_peek_from(request)

Get the From field, if any, from the HTTP header.

`request` : | the request to query.

### gsk_http_request_set_from()

    #define             gsk_http_request_set_from(request, from)

[From RFC 2616, Section 14.22] The From request-header field, if given, SHOULD contain an Internet e-mail address for the human user who controls the requesting user agent. The address SHOULD be machine-usable, as defined by "mailbox" in RFC 822 as updated by RFC 1123.

`request` : | the request to affect.
`from` : | the email of the user making the request.

### gsk_http_request_set_if_modified_since()

    #define             gsk_http_request_set_if_modified_since(request, t)

[From RFC 2616, Section 14.25] The If-Modified-Since request-header field is used with a method to make it conditional: if the requested variant has not been modified since the time specified in this field, an entity will not be returned from the server; instead, a 304 (not modified) response will be returned without any message-body.

`request` : | the header to affect.
`t` : | the time to compare the content's modification time with. The content should only be transmitted if its modification time is later than `t`.

### gsk_http_request_get_if_modified_since()

    #define             gsk_http_request_get_if_modified_since(request)

Get the time which will be compared with the content's modification time by the server to eliminate unnecessary content transfers. If this returns (time_t)-1 then there is no If-Modified-Since header.

`request` : | the request to query.

### gsk_http_request_set_authorization ()

    void                gsk_http_request_set_authorization  (GskHttpRequest *request,
                                                             gboolean is_proxy_auth,
                                                             GskHttpAuthorization *auth);

Set the authorization for this request. 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.

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

### gsk_http_request_set_host()

    #define             gsk_http_request_set_host(request, host)

Set the Host: header for the HTTP request.

`request` : | the HTTP Request object to affect.
`host` : | the hostname as a string.

### gsk_http_request_set_user_agent()

    #define             gsk_http_request_set_user_agent(request, user_agent)

`request` : |
`user_agent` : |

### gsk_http_request_peek_user_agent()

    #define             gsk_http_request_peek_user_agent(request)

`request` : |

### gsk_http_request_peek_authorization ()

    GskHttpAuthorization * gsk_http_request_peek_authorization
                                                            (GskHttpRequest *request,
                                                             gboolean is_proxy_auth);

Get the requested authorization information.

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

### gsk_http_request_cache_directive_free ()

    void                gsk_http_request_cache_directive_free
                                                            (GskHttpRequestCacheDirective *directive);

Deallocate a GskHttpRequestCacheDirective.

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

### gsk_http_request_cache_directive_new ()

    GskHttpRequestCacheDirective * gsk_http_request_cache_directive_new
                                                            (void);

Returns : |

### gsk_http_request_parse_first_line ()

    GskHttpRequestFirstLineStatus  gsk_http_request_parse_first_line
                                                            (GskHttpRequest *request,
                                                             const char *line,
                                                             GError **error);

Parse the first line of an HTTP request.

`request` : | request to initialize
`line` : | first line of request header, e.g. GET / HTTP/1.0
`error` : |
Returns : | whether the line was the start of a valid HTTP-request.

### gsk_http_request_set_cache_control ()

    void                gsk_http_request_set_cache_control  (GskHttpRequest *request,
                                                             GskHttpRequestCacheDirective *directive);

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

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

### gsk_http_request_has_content_body ()

    gboolean            gsk_http_request_has_content_body   (GskHttpRequest *request);

Get whether this header should be accompanied by a content-body.

`request` : | the request to query.
Returns : |

### gsk_http_parse_cgi_query_string ()

    char **             gsk_http_parse_cgi_query_string     (const char *query_string,
                                                             GError **error);

Parse the CGI key-value pairs from a query. The keys are normal alphanumeric strings; the values are de-escaped.

`query_string` : | the full path from the HttpRequest.
`error` : | the place to put the error if something goes wrong. returns: the key-value pairs of CGI data, NULL-terminated.
Returns : |

### gsk_http_request_parse_cgi_query_string ()

    GHashTable *        gsk_http_request_parse_cgi_query_string
                                                            (const char *query_string);

`query_string` : |
Returns : |

## Property Details

### The `"host"` property

      "host"                     gchar*                : Read / Write

Hostname.

Default value: NULL

### The `"if-modified-since"` property

      "if-modified-since"        glong                 : Read / Write

IMS tag.

Allowed values: >= -1

Default value: -1

### The `"max-forwards"` property

      "max-forwards"             glong                 : Read / Write

IMax-Forwards.

Allowed values: [-1,32]

Default value: -1

### The `"path"` property

      "path"                     gchar*                : Read / Write

Path.

Default value: NULL

### The `"referrer"` property

      "referrer"                 gchar*                : Read / Write

Referrer.

Default value: NULL

### The `"user-agent"` property

      "user-agent"               gchar*                : Read / Write

User Agent.

Default value: NULL

### The `"verb"` property

      "verb"                     GskHttpVerb           : Read / Write

verb.

Default value: GSK_HTTP_VERB_GET

## See Also

GskHttpHeader, GskHttpResponse