Http

Enums

enum sfHttpMethod

Enumerate the available HTTP methods for a request.

Values:

enumerator sfHttpGet

Request in get mode, standard method to retrieve a page.

enumerator sfHttpPost

Request in post mode, usually to send data to a page.

enumerator sfHttpHead

Request a page’s header only.

enumerator sfHttpPut

Request in put mode, useful for a REST API.

enumerator sfHttpDelete

Request in delete mode, useful for a REST API.

enum sfHttpStatus

Enumerate all the valid status codes for a response.

Values:

enumerator sfHttpOk

Most common code returned when operation was successful.

enumerator sfHttpCreated

The resource has successfully been created.

enumerator sfHttpAccepted

The request has been accepted, but will be processed later by the server.

enumerator sfHttpNoContent

Sent when the server didn’t send any data in return.

enumerator sfHttpResetContent

The server informs the client that it should clear the view (form) that caused the request to be sent.

enumerator sfHttpPartialContent

The server has sent a part of the resource, as a response to a partial GET request.

enumerator sfHttpMultipleChoices

The requested page can be accessed from several locations.

enumerator sfHttpMovedPermanently

The requested page has permanently moved to a new location.

enumerator sfHttpMovedTemporarily

The requested page has temporarily moved to a new location.

enumerator sfHttpNotModified

For conditional requests, means the requested page hasn’t changed and doesn’t need to be refreshed.

enumerator sfHttpBadRequest

The server couldn’t understand the request (syntax error)

enumerator sfHttpUnauthorized

The requested page needs an authentication to be accessed.

enumerator sfHttpForbidden

The requested page cannot be accessed at all, even with authentication.

enumerator sfHttpNotFound

The requested page doesn’t exist.

enumerator sfHttpRangeNotSatisfiable

The server can’t satisfy the partial GET request (with a “Range” header field)

enumerator sfHttpInternalServerError

The server encountered an unexpected error.

enumerator sfHttpNotImplemented

The server doesn’t implement a requested feature.

enumerator sfHttpBadGateway

The gateway server has received an error from the source server.

enumerator sfHttpServiceNotAvailable

The server is temporarily unavailable (overloaded, in maintenance, …)

enumerator sfHttpGatewayTimeout

The gateway server couldn’t receive a response from the source server.

enumerator sfHttpVersionNotSupported

The server doesn’t support the requested HTTP version.

enumerator sfHttpInvalidResponse

Response is not a valid HTTP one.

enumerator sfHttpConnectionFailed

Connection with server failed.

Functions

sfHttpRequest *sfHttpRequest_create(void)

Create a new HTTP request.

Returns:

A new sfHttpRequest object

void sfHttpRequest_destroy(sfHttpRequest *httpRequest)

Destroy a HTTP request.

Parameters:

• httpRequest – HTTP request to destroy

void sfHttpRequest_setField(sfHttpRequest *httpRequest, const char *field, const char *value)

Set the value of a header field of a HTTP request.

The field is created if it doesn’t exist. The name of the field is case insensitive. By default, a request doesn’t contain any field (but the mandatory fields are added later by the HTTP client when sending the request).

Parameters:

• httpRequest – HTTP request

• field – Name of the field to set

• value – Value of the field

void sfHttpRequest_setMethod(sfHttpRequest *httpRequest, sfHttpMethod method)

Set a HTTP request method.

See the sfHttpMethod enumeration for a complete list of all the availale methods. The method is sfHttpGet by default.

Parameters:

• httpRequest – HTTP request

• method – Method to use for the request

void sfHttpRequest_setUri(sfHttpRequest *httpRequest, const char *uri)

Set a HTTP request URI.

The URI is the resource (usually a web page or a file) that you want to get or post. The URI is “/” (the root page) by default.

Parameters:

• httpRequest – HTTP request

• uri – URI to request, relative to the host

void sfHttpRequest_setHttpVersion(sfHttpRequest *httpRequest, unsigned int major, unsigned int minor)

Set the HTTP version of a HTTP request.

The HTTP version is 1.0 by default.

Parameters:

• httpRequest – HTTP request

• major – Major HTTP version number

• minor – Minor HTTP version number

void sfHttpRequest_setBody(sfHttpRequest *httpRequest, const char *body)

Set the body of a HTTP request.

The body of a request is optional and only makes sense for POST requests. It is ignored for all other methods. The body is empty by default.

Parameters:

• httpRequest – HTTP request

• body – Content of the body

void sfHttpResponse_destroy(sfHttpResponse *httpResponse)

Destroy a HTTP response.

Parameters:

• httpResponse – HTTP response to destroy

const char *sfHttpResponse_getField(const sfHttpResponse *httpResponse, const char *field)

Get the value of a field of a HTTP response.

If the field field is not found in the response header, the empty string is returned. This function uses case-insensitive comparisons.

Parameters:

• httpResponse – HTTP response

• field – Name of the field to get

Returns:

Value of the field, or empty string if not found

sfHttpStatus sfHttpResponse_getStatus(const sfHttpResponse *httpResponse)

Get the status code of a HTTP reponse.

The status code should be the first thing to be checked after receiving a response, it defines whether it is a success, a failure or anything else (see the sfHttpStatus enumeration).

Parameters:

• httpResponse – HTTP response

Returns:

Status code of the response

unsigned int sfHttpResponse_getMajorVersion(const sfHttpResponse *httpResponse)

Get the major HTTP version number of a HTTP response.

Parameters:

• httpResponse – HTTP response

Returns:

Major HTTP version number

unsigned int sfHttpResponse_getMinorVersion(const sfHttpResponse *httpResponse)

Get the minor HTTP version number of a HTTP response.

Parameters:

• httpResponse – HTTP response

Returns:

Minor HTTP version number

const char *sfHttpResponse_getBody(const sfHttpResponse *httpResponse)

Get the body of a HTTP response.

The body of a response may contain:

• the requested page (for GET requests)

• a response from the server (for POST requests)

• nothing (for HEAD requests)

• an error message (in case of an error)

Parameters:

• httpResponse – HTTP response

Returns:

The response body

sfHttp *sfHttp_create(void)

Create a new Http object.

Returns:

A new sfHttp object

void sfHttp_destroy(sfHttp *http)

Destroy a Http object.

Parameters:

• http – Http object to destroy

void sfHttp_setHost(sfHttp *http, const char *host, unsigned short port)

Set the target host of a HTTP object.

This function just stores the host address and port, it doesn’t actually connect to it until you send a request. If the port is 0, it means that the HTTP client will use the right port according to the protocol used (80 for HTTP, 443 for HTTPS). You should leave it like this unless you really need a port other than the standard one, or use an unknown protocol.

Parameters:

• http – Http object

• host – Web server to connect to

• port – Port to use for connection

sfHttpResponse *sfHttp_sendRequest(sfHttp *http, const sfHttpRequest *request, sfTime timeout)

Send a HTTP request and return the server’s response.

You must have a valid host before sending a request (see sfHttp_setHost). Any missing mandatory header field in the request will be added with an appropriate value. Warning: this function waits for the server’s response and may not return instantly; use a thread if you don’t want to block your application, or use a timeout to limit the time to wait. A value of 0 means that the client will use the system defaut timeout (which is usually pretty long).

Parameters:

• http – Http object

• request – Request to send

• timeout – Maximum time to wait

Returns:

Server’s response