HTTP
A small and easy to use HTTP client to send and receive data from the web.
Only available in the main GodotSteam branches and GodotSteam Server branches
Functions
createCookieContainer
createCookieContainer( bool allow_responses_to_modify )
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 allow_responses_to_modify 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: uint32_t
createHTTPRequest
createHTTPRequest( int request_method, string absolute_url )
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: uint32_t
deferHTTPRequest
deferHTTPRequest( uint32 request_handle )
Defers a request which has already been sent by moving it at the back of the queue.
Returns: bool
getHTTPDownloadProgressPct
getHTTPDownloadProgressPct( uint32 request_handle )
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: float
getHTTPRequestWasTimedOut
getHTTPRequestWasTimedOut( int request_handle )
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 http_request_completed callback if request_success is false.
Returns: bool
getHTTPResponseBodyData
getHTTPResponseBodyData( uint32 request_handle, uint32 buffer_size )
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 http_request_completed call result associated with this request handle. You should first call getHTTPResponseBodySize or use the body_size 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: PoolByteArray
getHTTPResponseBodySize
getHTTPResponseBodySize( uint32 request_handle )
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 http_request_completed or http_request_data_received 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: uint32
getHTTPResponseHeaderSize
getHTTPResponseHeaderSize( uint32 request_handle, string header_name )
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 http_request_completed 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: uint32
getHTTPResponseHeaderValue
getHTTPResponseHeaderValue( uint32 request_handle, string header_name, uint32 buffer_size )
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 http_request_completed 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: uint8
getHTTPStreamingResponseBodyData
getHTTPStreamingResponseBodyData( uint32 request_handle, uint32 offset, uint32 buffer_size )
Gets the body data from a streaming HTTP response. This must be called after data is received from a streaming HTTP request via the http_request_completed 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 http_request_headers_received. 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: uint32
prioritizeHTTPRequest
prioritizeHTTPRequest( uint32 request_handle )
Prioritizes a request which has already been sent by moving it at the front of the queue.
Returns: bool
releaseCookieContainer
releaseCookieContainer()
Releases a cookie container, freeing the memory allocated within Steam. You must call this when you are done using each HTTP cookie container handle that you obtained via createCookieContainer!
Returns: bool
releaseHTTPRequest
releaseHTTPRequest( uint32 request_handle )
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
sendHTTPRequest
sendHTTPRequest( uint32 request_handle )
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
sendHTTPRequestAndStreamResponse
sendHTTPRequestAndStreamResponse( uint32 request_handle )
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 http_request_headers_received. 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
setHTTPCookie
setHTTPCookie( string host, string url, string cookie )
Adds a cookie to the specified cookie container that will be used with future requests.
Returns: bool
setHTTPRequestAbsoluteTimeoutMS
setHTTPRequestAbsoluteTimeoutMS( uint32 request_handle, uint32 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
setHTTPRequestContextValue
setHTTPRequestContextValue( uint32 request_handle, uint64_t context_value )
Set a context value for the request, which will be returned in the http_request_completed callback after sending the request.
This is just so the caller can easily keep track of which callbacks go with which request data.
Must be called before sending the request.
Returns: bool
setHTTPRequestCookieContainer
setHTTPRequestCookieContainer( uint32 request_handle, uint32 cookie_handle )
Associates a cookie container to use for an HTTP request.
Returns: bool
setHTTPRequestGetOrPostParameter
setHTTPRequestGetOrPostParameter( uint32 request_handle, string name, string value )
Set a GET or POST parameter value on the HTTP request.
Must be called prior to sending the request.
Returns: bool
setHTTPRequestHeaderValue
setHTTPRequestHeaderValue( uint32 request_handle, string header_name, string header_value )
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
setHTTPRequestNetworkActivityTimeout
setHTTPRequestNetworkActivityTimeout( uint32 request_handle, uint32 timeout_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
setHTTPRequestRawPostBody
setHTTPRequestRawPostBody( uint32 request_handle, string content_type, uint32 body_length )
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 content_type parameter will set the "content-type" header for the request to inform the server how to interpret the body.
Returns: uint8
setHTTPRequestRequiresVerifiedCertificate
setHTTPRequestRequiresVerifiedCertificate( uint32 request_handle, bool require_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
setHTTPRequestUserAgentInfo
setHTTPRequestUserAgentInfo( uint32 request_handle, string user_agent_info )
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
Signals
These callbacks require you to run Steam.run_callbacks() in your _process() function to receive them.
http_request_completed
http_request_completed
Result when an HTTP request completes. If you're using getHTTPStreamingResponseBodyData then you should be using the http_request_headers_received or http_request_data_received.
Returns:
- cookie_handle (uint32)
- context_value (uint64_t)
- request_success (bool)
- status_code (int)
- body_zize (uint32)
http_request_data_received
http_request_data_received
Triggered when a chunk of data is received from a streaming HTTP request.
Returns:
- cookie_handle (uint32)
- context_value (uint64_t)
- offset (uint32)
- bytes_received (uint32)
http_request_headers_received
http_request_headers_received
Triggered when HTTP headers are received from a streaming HTTP request.
Returns:
- cookie_handle (uint32)
- context_value (uint64_t)
Enums
HTTPMethod
| Enumerator | Value |
|---|---|
| HTTP_METHOD_INVALID | 0 |
| HTTP_METHOD_GET | 1 |
| HTTP_METHOD_HEAD | 2 |
| HTTP_METHOD_POST | 3 |
| HTTP_METHOD_PUT | 4 |
| HTTP_METHOD_DELETE | 5 |
| HTTP_METHOD_OPTIONS | 6 |
| HTTP_METHOD_PATCH | 7 |
HTTPStatusCode
| Enumerator | Value |
|---|---|
| HTTP_STATUS_CODE_INVALID | 0 |
| HTTP_STATUS_CODE_100_CONTINUE | 100 |
| HTTP_STATUS_CODE_101_SWITCHING_PROTOCOLS | 101 |
| HTTP_STATUS_CODE_200_OK | 200 |
| HTTP_STATUS_CODE_201_CREATED | 201 |
| HTTP_STATUS_CODE_202_ACCEPTED | 202 |
| HTTP_STATUS_CODE_203_NON_AUTHORITATIVE | 203 |
| HTTP_STATUS_CODE_204_NO_CONTENT | 204 |
| HTTP_STATUS_CODE_205_RESET_CONTENT | 205 |
| HTTP_STATUS_CODE_206_PARTIAL_CONTENT | 206 |
| HTTP_STATUS_CODE_300_MULTIPLE_CHOICES | 300 |
| HTTP_STATUS_CODE_301_MOVED_PERMANENTLY | 301 |
| HTTP_STATUS_CODE_302_FOUND | 302 |
| HTTP_STATUS_CODE_303_SEE_OTHER | 303 |
| HTTP_STATUS_CODE_304_NOT_MODIFIED | 304 |
| HTTP_STATUS_CODE_305_USE_PROXY | 305 |
| HTTP_STATUS_CODE_307_TEMPORARY_REDIRECT | 307 |
| HTTP_STATUS_CODE_400_BAD_REQUEST | 400 |
| HTTP_STATUS_CODE_401_UNAUTHORIZED | 401 |
| HTTP_STATUS_CODE_402_PAYMENT_REQUIRED | 402 |
| HTTP_STATUS_CODE_403_FORBIDDEN | 403 |
| HTTP_STATUS_CODE_404_NOT_FOUND | 404 |
| HTTP_STATUS_CODE_405_METHOD_NOT_ALLOWED | 405 |
| HTTP_STATUS_CODE_406_NOT_ACCEPTABLE | 406 |
| HTTP_STATUS_CODE_407_PROXY_AUTH_REQUIRED | 407 |
| HTTP_STATUS_CODE_408_REQUEST_TIMEOUT | 408 |
| HTTP_STATUS_CODE_409_CONFLICT | 409 |
| HTTP_STATUS_CODE_410_GONE | 410 |
| HTTP_STATUS_CODE_411_LENGTH_REQUIRED | 411 |
| HTTP_STATUS_CODE_412_PRECONDITION_FAILED | 412 |
| HTTP_STATUS_CODE_413_REQUEST_ENTITY_TOO_LARGE | 413 |
| HTTP_STATUS_CODE_414_REQUEST_URI_TOO_LONG | 414 |
| HTTP_STATUS_CODE_415_UNSUPPORTED_MEDIA_TYPE | 415 |
| HTTP_STATUS_CODE_416_REQUESTED_RANGE_NOT_SATISFIABLE | 416 |
| HTTP_STATUS_CODE_417_EXPECTATION_FAILED | 417 |
| HTTP_STATUS_CODE_4XX_UNKNOWN | 418 |
| HTTP_STATUS_CODE_429_TOO_MANY_REQUESTS | 429 |
| HTTP_STATUS_CODE_500_INTERNAL_SERVER_ERROR | 500 |
| HTTP_STATUS_CODE_501_NOT_IMPLEMENTED | 501 |
| HTTP_STATUS_CODE_502_BAD_GATEWAY | 502 |
| HTTP_STATUS_CODE_503_SERVICE_UNAVAILABLE | 503 |
| HTTP_STATUS_CODE_504_GATEWAY_TIMEOUT | 504 |
| HTTP_STATUS_CODE_505_HTTP_VERSION_NOT_SUPPORTED | 505 |
| HTTP_STATUS_CODE_5XX_UNKNOWN | 599 |