A small and easy to use HTTP client to send and receive data from the web.

Member Functions

Member functions for ISteamHTTP are called through the global accessor function SteamHTTP().

CreateCookieContainer

Name	Type	Description
bAllowResponsesToModify	bool	Set whether the server can set cookies in this container.

Creates a cookie container to store cookies during the lifetime of the process.

This API is just for during process lifetime, after Steam restarts no cookies are persisted and you have no way to access the cookie container across repeat executions of your process.

If bAllowResponsesToModify is true then any response to your requests using this cookie container may add new cookies to the container which may be transmitted with future requests. Otherwise, if it's false then only cookies you explicitly set will be sent.

You can associate the cookie container with a http request by using SetHTTPRequestCookieContainer, and you can set a cookie using SetCookie.

Don't forget to free the container when you're done with it to prevent leaking memory by calling ReleaseCookieContainer!

Returns: HTTPCookieContainerHandle
Returns a new cookie container handle to be used with future calls to SteamHTTP functions.

CreateHTTPRequest

Name	Type	Description
eHTTPRequestMethod	EHTTPMethod	The type of request to make with this request.
pchAbsoluteURL	const char *	The url to request. Must start with "http://" or "https://".

Initializes a new HTTP request.

Requires the method such as GET or POST and the absolute URL for the request. Both http and https are supported, so this string must start with "http://" or "https://" and should look like "http://store.steampowered.com/app/10/" or similar. This call returns a handle that you can use to make further calls to setup and then send the HTTP request with SendHTTPRequest or SendHTTPRequestAndStreamResponse.

Don't forget to free the HTTP request when you're done with it to prevent leaking memory by calling ReleaseHTTPRequest!

Returns: HTTPRequestHandle
Returns a new request handle to be used with future calls to SteamHTTP functions. Returns INVALID_HTTPREQUEST_HANDLE if pchAbsoluteURL is NULL or empty ("").

DeferHTTPRequest

Name	Type	Description
hRequest	HTTPRequestHandle	The request handle to defer.

Defers a request which has already been sent by moving it at the back of the queue.

Returns: bool
Returns true if the request has been successfully defered. Otherwise false if hRequest is an invalid handle, or if the request has not been sent yet.

See Also: SendHTTPRequest, SendHTTPRequestAndStreamResponse

GetHTTPDownloadProgressPct

Name	Type	Description
hRequest	HTTPRequestHandle	The request handle to get the download percentage for.
pflPercentOut	float *	Returns the download percentage if the call was successful.

Gets progress on downloading the body for the request.

This will be zero unless a response header has already been received which included a content-length field. For responses that contain no content-length it will report zero for the duration of the request as the size is unknown until the connection closes.

Returns: bool
Returns true upon success if the download percentage was successfully returned. Otherwise, false if the handle is invalid or pflPercentOut is NULL.

GetHTTPRequestWasTimedOut

Name	Type	Description
hRequest	HTTPRequestHandle	The request handle to check the failure reason for.
pbWasTimedOut	bool *	Returns whether the request was timed out or not.

Check if the reason the request failed was because we timed it out (rather than some harder failure).

You'll want to call this within the context of HTTPRequestCompleted_t if m_bRequestSuccessful is false.

Returns: bool
Returns true upon success if we successfully checked .
Returns false under the following conditions:

• hRequest was invalid.
  
• The request has not been sent or has not completed.

GetHTTPResponseBodyData

Name	Type	Description
hRequest	HTTPRequestHandle	The request handle to get the response body data for.
pBodyDataBuffer	uint8 *	The buffer where the data will be copied into.
unBufferSize	uint32	This should be the size of pBodyDataBuffer in bytes.

Gets the body data from an HTTP response.

This must be called after the HTTP request has completed and returned the HTTP response via the HTTPRequestCompleted_t call result associated with this request handle. You should first call GetHTTPResponseBodySize or use the m_unBodySize variable provided in the call result, you can then allocate a buffer with that size to pass into this function.

This is only for HTTP requests which were sent with SendHTTPRequest. Use GetHTTPStreamingResponseBodyData if you're using streaming HTTP requests via SendHTTPRequestAndStreamResponse.

Returns: bool
Returns true upon success indicating that pBodyDataBuffer has been filled with the body data.
Otherwise, returns false under the following conditions:

• hRequest was invalid.
  
• The request has not been sent or has not completed.
  
• The request is a streaming request.
  
• pBodyDataBuffer is NULL.
  
• unBufferSize is not the same size that was provided by GetHTTPResponseBodySize.

GetHTTPResponseBodySize

Name	Type	Description
hRequest	HTTPRequestHandle	The request handle to get the response body size for.
unBodySize	uint32 *	Returns the size of the response body.

Gets the size of the body data from an HTTP response.

This must be called after the HTTP request has completed and returned the HTTP response via the HTTPRequestCompleted_t or HTTPRequestDataReceived_t associated with this request handle. If this returns successfully, then you can allocate a buffer with the provided size to fill with the data obtained from GetHTTPResponseBodyData or GetHTTPStreamingResponseBodyData.

Returns: bool
Returns true upon success indicating that unBodySize has been filled with the size.
Otherwise, returns false under the following conditions:

• hRequest was invalid.
  
• The request has not been sent or has not completed.
  
• unBodySize is NULL.

GetHTTPResponseHeaderSize

Name	Type	Description
hRequest	HTTPRequestHandle	The request handle to check for the response header name.
pchHeaderName	const char *	The header name to check.
unResponseHeaderSize	uint32 *	Returns the size of the response header, if it is present in the response.

Checks if a header is present in an HTTP response and returns its size.

This must be called after the HTTP request has completed and returned the HTTP response via the HTTPRequestCompleted_t call result associated with this request handle. If the response header exists in the response, then you can allocate a correctly sized buffer to get the associated value with GetHTTPResponseHeaderValue.

Here is a list of standard response header names on wikipedia.

Returns: bool
Returns true if the header name is present in the response and unResponseHeaderSize has been filled with the size of the header value.
Otherwise, returns false and sets unResponseHeaderSize to 0 under the following conditions:

• hRequest was invalid.
  
• The request has not been sent or has not completed.
  
• pchHeaderName is NULL.
  
• unResponseHeaderSize is NULL.
  
• The header name is not present in the response.

GetHTTPResponseHeaderValue

Name	Type	Description
hRequest	HTTPRequestHandle	The request handle to get the response header value for.
pchHeaderName	const char *	The header name to get the header value for.
pHeaderValueBuffer	uint8 *	The buffer where the value will be copied into.
unBufferSize	uint32	This should be the size of pHeaderValueBuffer in bytes.

Gets a header value from an HTTP response.

This must be called after the HTTP request has completed and returned the HTTP response via the HTTPRequestCompleted_t call result associated with this request handle. You should first call GetHTTPResponseHeaderSize to check for the presence of the header and to get the size. You can then allocate a buffer with that size and pass it into this function.

Here is a list of standard response header names on wikipedia.

Returns: bool
Returns true upon success indicating that pHeaderValueBuffer has been filled with the header value.
Otherwise, returns false under the following conditions:

• hRequest was invalid.
  
• The request has not been sent or has not completed.
  
• pchHeaderName is NULL.
  
• pHeaderValueBuffer is NULL.
  
• The header name is not present in the response.
  
• unBufferSize is not large enough to hold the value.

GetHTTPStreamingResponseBodyData

Name	Type	Description
hRequest	HTTPRequestHandle	The request handle to get the response body data for.
cOffset	uint32	This must be the offset provided by HTTPRequestDataReceived_t.
pBodyDataBuffer	uint8 *	Returns the data by copying it into this buffer.
unBufferSize	uint32	This must be the size provided by HTTPRequestDataReceived_t.

Gets the body data from a streaming HTTP response.

This must be called after data is received from a streaming HTTP request via the HTTPRequestDataReceived_t callback associated with this request handle. Typically you'll want to allocate a buffer associated with the request handle using the Content-Length HTTP response field to receive the total size of the data when you receive the header via HTTPRequestHeadersReceived_t. You can then append data to that buffer as it comes in.

This is only for streaming HTTP requests which were sent with SendHTTPRequestAndStreamResponse. Use GetHTTPResponseBodyData if you're using SendHTTPRequest.

Returns: bool
Returns true upon success indicating that pBodyDataBuffer has been filled with the body data.
Otherwise, returns false under the following conditions:

• hRequest was invalid.
  
• The request has not been sent or has not completed.
  
• The request is not a streaming request.
  
• cOffset is not the same offset that was provided by HTTPRequestDataReceived_t.
  
• unBufferSize is not the same size that was provided by HTTPRequestDataReceived_t.

PrioritizeHTTPRequest

Name	Type	Description
hRequest	HTTPRequestHandle	The request handle to prioritize.

Prioritizes a request which has already been sent by moving it at the front of the queue.

Returns: bool
Returns true if the request has been successfully prioritized. Otherwise false if hRequest is an invalid handle, or if the request has not been sent yet.

See Also: SendHTTPRequest, SendHTTPRequestAndStreamResponse

ReleaseCookieContainer

Name	Type	Description
hCookieContainer	HTTPCookieContainerHandle	The cookie container handle to release.

Releases a cookie container, freeing the memory allocated within Steam.

You MUST call this when you are done using each HTTPCookieContainerHandle that you obtained via CreateCookieContainer!

Returns: bool
Returns true if the handle has been freed; otherwise, false if the handle was invalid.

ReleaseHTTPRequest

Name	Type	Description
hRequest	HTTPRequestHandle	The request handle to release.

Releases an HTTP request handle, freeing the memory allocated within Steam.

You MUST call this when you are done using each HTTPRequestHandle that you obtained via CreateHTTPRequest!

Returns: bool
Returns true if the the handle was released successfully, false only if the handle is invalid.

SendHTTPRequest

Name	Type	Description
hRequest	HTTPRequestHandle	The request handle to send.
pCallHandle	SteamAPICall_t *	Returns a call result handle to receive the response.

Sends an HTTP request.

This call is asynchronous and provides a call result handle which you must use to track the call to its completion. If you have multiple requests in flight at the same time you can use PrioritizeHTTPRequest or DeferHTTPRequest to set the priority of the request.

If the user is in offline mode in Steam, then this will add an only-if-cached cache-control header and only do a local cache lookup rather than sending any actual remote request.

If the data you are expecting is large, you can use SendHTTPRequestAndStreamResponse to stream the data in chunks.

Returns: bool
Triggers a HTTPRequestCompleted_t callback.
Returns true upon successfully setting the parameter.
Returns false under the following conditions:

• hRequest was invalid.
  
• The request has already been sent.
  
• pCallHandle is NULL.

SendHTTPRequestAndStreamResponse

Name	Type	Description
hRequest	HTTPRequestHandle	The request handle to send.
pCallHandle	SteamAPICall_t *	Returns a call result handle to receive the response.

Sends an HTTP request and streams the response back in chunks.

This call is asynchronous and provides a call result handle which you must use to track the call to its completion. Typically you'll want to allocate a buffer associated with the request handle using the Content-Length HTTP response field to receive the total size of the data when you receive the header via HTTPRequestHeadersReceived_t. You can then append data to that buffer as it comes in.

If you have multiple requests in flight at the same time you can use PrioritizeHTTPRequest or DeferHTTPRequest to set the priority of the request.

If the user is in offline mode in Steam, then this will add an only-if-cached cache-control header and only do a local cache lookup rather than sending any actual remote request.

If the data you are expecting is small (on the order of a few megabytes or less) then you'll likely want to use SendHTTPRequest.

Returns: bool
Triggers a HTTPRequestDataReceived_t callback.
Triggers a HTTPRequestHeadersReceived_t callback.
Triggers a HTTPRequestCompleted_t callback.
Returns true upon successfully setting the parameter.
Returns false under the following conditions:

• hRequest was invalid.
  
• The request has already been sent.
  
• pCallHandle is NULL.

SetCookie

Name	Type	Description
hCookieContainer	HTTPCookieContainerHandle	The cookie container to set the the cookie in.
pchHost	const char *	The host to set this cookie for.
pchUrl	const char *	The url to set this cookie for.
pchCookie	const char *	The cookie to set.

Adds a cookie to the specified cookie container that will be used with future requests.

Returns: bool
Returns true if the cookie was set successfully. Otherwise, false if the request handle was invalid or if there was a security issue parsing the cookie.

SetHTTPRequestAbsoluteTimeoutMS

Name	Type	Description
hRequest	HTTPRequestHandle	The request handle to set the timeout on.
unMilliseconds	uint32	The length of the timeout period in milliseconds.

Set an absolute timeout in milliseconds for the HTTP request.

This is the total time timeout which is different than the network activity timeout which is set with SetHTTPRequestNetworkActivityTimeout which can bump everytime we get more data.

Returns: bool
Returns true upon successfully setting the timeout.
Returns false under the following conditions:

• hRequest was invalid.
  
• The request has already been sent.

SetHTTPRequestContextValue

Name	Type	Description
hRequest	HTTPRequestHandle	The request handle to set the context value on.
ulContextValue	uint64	The context value to set.

Set a context value for the request, which will be returned in the HTTPRequestCompleted_t callback after sending the request.

This allows the caller to set a context ID that can enable attribution of a particular callback to a particular request.

Must be called before sending the request.

Returns: bool
Returns true upon successfully setting the context value.
Returns false under the following conditions:

• hRequest was invalid.
  
• The request has already been sent.

SetHTTPRequestCookieContainer

Name	Type	Description
hRequest	HTTPRequestHandle	The request handle to associate the cookie container with.
hCookieContainer	HTTPCookieContainerHandle	The cookie container handle to associate with the request handle.

Associates a cookie container to use for an HTTP request.

Returns: bool
Returns true upon successfully setting the cookie container.
Returns false under the following conditions:

• hRequest was invalid.
  
• hCookieContainer was invalid.

SetHTTPRequestGetOrPostParameter

Name	Type	Description
hRequest	HTTPRequestHandle	The request handle to set the parameter on.
pchParamName	const char *	Parameter name field.
pchParamValue	const char *	Value to associate with the name field.

Set a GET or POST parameter value on the HTTP request.

Must be called prior to sending the request.

Returns: bool
Returns true upon successfully setting the parameter.
Returns false under the following conditions:

• hRequest was invalid.
  
• The request has already been sent.
  
• pchParamName or pchParamValue are NULL.
  
• The request method set in CreateHTTPRequest is not k_EHTTPMethodGET, k_EHTTPMethodHEAD, or k_EHTTPMethodPOST.
  
• If the request method is k_EHTTPMethodPOST and a POST body has already been set with SetHTTPRequestRawPostBody.

SetHTTPRequestHeaderValue

Name	Type	Description
hRequest	HTTPRequestHandle	The request handle to set the header value for.
pchHeaderName	const char *	The header name field.
pchHeaderValue	const char *	Value to associate with the header name field.

Set a request header value for the HTTP request.

Must be called before sending the request.

A full list of standard request fields are available here on wikipedia. The User-Agent field is explicitly disallowed as it gets overwritten when the request is sent.

Returns: bool
Returns true upon successfully setting the header value.
Returns false under the following conditions:

• hRequest was invalid.
  
• The request has already been sent.
  
• pchHeaderName is "User-Agent".
  
• pchHeaderName or pchHeaderValue are NULL.

SetHTTPRequestNetworkActivityTimeout

Name	Type	Description
hRequest	HTTPRequestHandle	The request handle to set the timeout on.
unTimeoutSeconds	uint32	The length of the timeout period in seconds.

Set the timeout in seconds for the HTTP request.

The default timeout is 60 seconds if you don't call this. This can get bumped everytime we get more data. Use SetHTTPRequestAbsoluteTimeoutMS if you need a strict maximum timeout.

Returns: bool
Returns true upon successfully setting the timeout.
Returns false under the following conditions:

• hRequest was invalid.
  
• The request has already been sent.

SetHTTPRequestRawPostBody

Name	Type	Description
hRequest	HTTPRequestHandle	The request handle to set the post body on.
pchContentType	const char *	Sets the value of the calls "content-type" http header.
pubBody	uint8 *	The raw POST body data to set.
unBodyLen	uint32	The length of the body data passed into pubBody.

Sets the body for an HTTP Post request.

Will fail and return false on a GET request, and will fail if POST params have already been set for the request. Setting this raw body makes it the only contents for the post, the pchContentType parameter will set the "content-type" header for the request to inform the server how to interpret the body.

Returns: bool
Returns true upon success indicating that the content-type field and the body data have been set.
Otherwise, returns false under the following conditions:

• hRequest was invalid.
  
• The HTTP Method set in CreateHTTPRequest is not k_EHTTPMethodPOST, k_EHTTPMethodPUT, or k_EHTTPMethodPATCH.
  
• A POST body has already been set for this request either via this function or with SetHTTPRequestGetOrPostParameter.

SetHTTPRequestRequiresVerifiedCertificate

Name	Type	Description
hRequest	HTTPRequestHandle	The request handle to set whether the request requires a verified certificate.
bRequireVerifiedCertificate	bool	Turn on verified certificate?

Sets that the HTTPS request should require verified SSL certificate via machines certificate trust store.

This currently only works Windows and macOS.

Returns: bool
Returns true upon success. Otherwise, false if the request handle is invalid.

SetHTTPRequestUserAgentInfo

Name	Type	Description
hRequest	HTTPRequestHandle	The request handle to set the user agent info for.
pchUserAgentInfo	const char *	The string to append to the end of the user agent.

Set additional user agent info for a request.

This doesn't clobber the normal user agent, it just adds the extra info on the end. Sending NULL or an empty string resets the user agent info to the default value.

Returns: bool
Returns true upon success indicating that the user agent has been updated. Otherwise, false if the request handle is invalid.

Callbacks

These are callbacks which can be fired by calling SteamAPI_RunCallbacks. Many of these will be fired directly in response to the member functions of ISteamHTTP.

HTTPRequestCompleted_t

Result when an HTTP request completes.
If you're using GetHTTPStreamingResponseBodyData then you should be using the HTTPRequestHeadersReceived_t or HTTPRequestDataReceived_t.

Name	Type	Description
m_hRequest	HTTPRequestHandle	Handle for the request that has completed. You should call ReleaseHTTPRequest on this handle to free the resources when you're done using it, which is typically in this callback.
m_ulContextValue	uint64	Context value that the user defined on the request with SetHTTPRequestContextValue that this callback is associated with. 0 if no context value was set.
m_bRequestSuccessful	bool	This will be true if the request actually got any sort of response from the server (even an error). Otherwise it will be false if the request failed due to an internal error or client side network failure.
m_eStatusCode	EHTTPStatusCode	Will be the HTTP status code value returned by the server. k_EHTTPStatusCode200OK is the normal OK response, if you get something else you probably need to treat it as a failure.
m_unBodySize	uint32	The size of the request body in bytes. This is the same as GetHTTPResponseBodySize.

Associated Functions: SendHTTPRequest, SendHTTPRequestAndStreamResponse

HTTPRequestDataReceived_t

Triggered when a chunk of data is received from a streaming HTTP request.

Name	Type	Description
m_hRequest	HTTPRequestHandle	Handle value for the request that has received data.
m_ulContextValue	uint64	Context value that the user defined on the request that this callback is associated with, 0 if no context value was set.
m_cOffset	uint32	Offset to provide to GetHTTPStreamingResponseBodyData to get this chunk of data
m_cBytesReceived	uint32	Size in bytes to provide to GetHTTPStreamingResponseBodyData to get this chunk of data

Associated Functions: SendHTTPRequestAndStreamResponse

HTTPRequestHeadersReceived_t

Triggered when HTTP headers are received from a streaming HTTP request.

Name	Type	Description
m_hRequest	HTTPRequestHandle	Handle value for the request that has received headers.
m_ulContextValue	uint64	Context value that the user defined on the request that this callback is associated with, 0 if no context value was set.

Associated Functions: SendHTTPRequestAndStreamResponse

Enums

These are enums which are defined for use with ISteamHTTP.

EHTTPMethod

Used to set the HTTP request method in CreateHTTPRequest. For the most part you should only ever need GET or POST.

You can read more about HTTP request methods on the Mozilla Developer Network.

Name	Value	Description
k_EHTTPMethodInvalid	0	Invalid.
k_EHTTPMethodGET	1	The HTTP Method is set to GET.
k_EHTTPMethodHEAD	2	The HTTP Method is set to HEAD.
k_EHTTPMethodPOST	3	The HTTP Method is set to POST.
k_EHTTPMethodPUT	4	The HTTP Method is set to PUT.
k_EHTTPMethodDELETE	5	The HTTP Method is set to DELETE.
k_EHTTPMethodOPTIONS	6	The HTTP Method is set to OPTIONS.
k_EHTTPMethodPATCH	7	The HTTP Method is set to PATCH.

EHTTPStatusCode

HTTP response status codes that the server can send in response to a request.

See the Mozilla Developer Network or RFC2616 section 10.3 for detailed descriptions for each of these.

Name	Value	Description
k_EHTTPStatusCodeInvalid	0	Invalid status code. This isn't defined in HTTP, used to indicate unset in our code.
k_EHTTPStatusCode100Continue	100
k_EHTTPStatusCode101SwitchingProtocols	101
k_EHTTPStatusCode200OK	200
k_EHTTPStatusCode201Created	201
k_EHTTPStatusCode202Accepted	202
k_EHTTPStatusCode203NonAuthoritative	203
k_EHTTPStatusCode204NoContent	204
k_EHTTPStatusCode205ResetContent	205
k_EHTTPStatusCode206PartialContent	206
k_EHTTPStatusCode300MultipleChoices	300
k_EHTTPStatusCode301MovedPermanently	301
k_EHTTPStatusCode302Found	302
k_EHTTPStatusCode303SeeOther	303
k_EHTTPStatusCode304NotModified	304
k_EHTTPStatusCode305UseProxy	305
k_EHTTPStatusCode307TemporaryRedirect	307
k_EHTTPStatusCode400BadRequest	400
k_EHTTPStatusCode401Unauthorized	401	You probably want 403 or something else. 401 implies you're sending a WWW-Authenticate header and the client can sent an Authorization header in response.
k_EHTTPStatusCode402PaymentRequired	402	This is reserved for future HTTP specs, not really supported by clients.
k_EHTTPStatusCode403Forbidden	403
k_EHTTPStatusCode404NotFound	404
k_EHTTPStatusCode405MethodNotAllowed	405
k_EHTTPStatusCode406NotAcceptable	406
k_EHTTPStatusCode407ProxyAuthRequired	407
k_EHTTPStatusCode408RequestTimeout	408
k_EHTTPStatusCode409Conflict	409
k_EHTTPStatusCode410Gone	410
k_EHTTPStatusCode411LengthRequired	411
k_EHTTPStatusCode412PreconditionFailed	412
k_EHTTPStatusCode413RequestEntityTooLarge	413
k_EHTTPStatusCode414RequestURITooLong	414
k_EHTTPStatusCode415UnsupportedMediaType	415
k_EHTTPStatusCode416RequestedRangeNotSatisfiable	416
k_EHTTPStatusCode417ExpectationFailed	417
k_EHTTPStatusCode4xxUnknown	418	418 is reserved, so we use it to mean unknown.
k_EHTTPStatusCode429TooManyRequests	429
k_EHTTPStatusCode500InternalServerError	500
k_EHTTPStatusCode501NotImplemented	501
k_EHTTPStatusCode502BadGateway	502
k_EHTTPStatusCode503ServiceUnavailable	503
k_EHTTPStatusCode504GatewayTimeout	504
k_EHTTPStatusCode505HTTPVersionNotSupported	505
k_EHTTPStatusCode5xxUnknown	599

Typedefs

These are typedefs which are defined for use with ISteamHTTP.

Name	Base type	Description
HTTPCookieContainerHandle	uint32
HTTPRequestHandle	uint32	Handle to a HTTP Request handle

Constants

These are constants which are defined for use with ISteamHTTP.

Name	Type	Value	Description
INVALID_HTTPCOOKIE_HANDLE	int	0
INVALID_HTTPREQUEST_HANDLE	int	0
STEAMHTTP_INTERFACE_VERSION	const char *	"STEAMHTTP_INTERFACE_VERSION002"