272 lines
13 KiB
C++
272 lines
13 KiB
C++
//====== Copyright © 1996-2009, Valve Corporation, All rights reserved. =======
|
|
//
|
|
// Purpose: interface to http client
|
|
//
|
|
//=============================================================================
|
|
|
|
#ifndef ISTEAMHTTP_H
|
|
#define ISTEAMHTTP_H
|
|
#ifdef _WIN32
|
|
#pragma once
|
|
#endif
|
|
|
|
#include "isteamclient.h"
|
|
#include "steamhttpenums.h"
|
|
|
|
// Handle to a HTTP Request handle
|
|
typedef uint32 HTTPRequestHandle;
|
|
#define INVALID_HTTPREQUEST_HANDLE 0
|
|
|
|
typedef uint32 HTTPCookieContainerHandle;
|
|
#define INVALID_HTTPCOOKIE_HANDLE 0
|
|
|
|
//-----------------------------------------------------------------------------
|
|
// Purpose: interface to http client
|
|
//-----------------------------------------------------------------------------
|
|
class ISteamHTTP {
|
|
public:
|
|
// Initializes a new HTTP request, returning a handle to use in further
|
|
// operations on it. Requires the method (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/250/ or such.
|
|
virtual HTTPRequestHandle CreateHTTPRequest(EHTTPMethod eHTTPRequestMethod,
|
|
const char *pchAbsoluteURL) = 0;
|
|
|
|
// Set a context value for the request, which will be returned in the
|
|
// HTTPRequestCompleted_t callback after sending the request. This is just
|
|
// so the caller can easily keep track of which callbacks go with which
|
|
// request data.
|
|
virtual bool SetHTTPRequestContextValue(HTTPRequestHandle hRequest,
|
|
uint64 ulContextValue) = 0;
|
|
|
|
// Set a timeout in seconds for the HTTP request, must be called prior to
|
|
// sending the request. Default timeout is 60 seconds if you don't call
|
|
// this. Returns false if the handle is invalid, or the request has already
|
|
// been sent.
|
|
virtual bool SetHTTPRequestNetworkActivityTimeout(
|
|
HTTPRequestHandle hRequest, uint32 unTimeoutSeconds) = 0;
|
|
|
|
// Set a request header value for the request, must be called prior to
|
|
// sending the request. Will return false if the handle is invalid or the
|
|
// request is already sent.
|
|
virtual bool SetHTTPRequestHeaderValue(HTTPRequestHandle hRequest,
|
|
const char *pchHeaderName,
|
|
const char *pchHeaderValue) = 0;
|
|
|
|
// Set a GET or POST parameter value on the request, which is set will
|
|
// depend on the EHTTPMethod specified when creating the request. Must be
|
|
// called prior to sending the request. Will return false if the handle is
|
|
// invalid or the request is already sent.
|
|
virtual bool SetHTTPRequestGetOrPostParameter(
|
|
HTTPRequestHandle hRequest, const char *pchParamName,
|
|
const char *pchParamValue) = 0;
|
|
|
|
// Sends the HTTP request, will return false on a bad handle, otherwise use
|
|
// SteamCallHandle to wait on asynchronous response via callback.
|
|
//
|
|
// Note: If the user is in offline mode in Steam, then this will add a
|
|
// only-if-cached cache-control header and only do a local cache lookup
|
|
// rather than sending any actual remote request.
|
|
virtual bool SendHTTPRequest(HTTPRequestHandle hRequest,
|
|
SteamAPICall_t *pCallHandle) = 0;
|
|
|
|
// Sends the HTTP request, will return false on a bad handle, otherwise use
|
|
// SteamCallHandle to wait on asynchronous response via callback for
|
|
// completion, and listen for HTTPRequestHeadersReceived_t and
|
|
// HTTPRequestDataReceived_t callbacks while streaming.
|
|
virtual bool SendHTTPRequestAndStreamResponse(
|
|
HTTPRequestHandle hRequest, SteamAPICall_t *pCallHandle) = 0;
|
|
|
|
// Defers a request you have sent, the actual HTTP client code may have many
|
|
// requests queued, and this will move the specified request to the tail of
|
|
// the queue. Returns false on invalid handle, or if the request is not yet
|
|
// sent.
|
|
virtual bool DeferHTTPRequest(HTTPRequestHandle hRequest) = 0;
|
|
|
|
// Prioritizes a request you have sent, the actual HTTP client code may have
|
|
// many requests queued, and this will move the specified request to the
|
|
// head of the queue. Returns false on invalid handle, or if the request is
|
|
// not yet sent.
|
|
virtual bool PrioritizeHTTPRequest(HTTPRequestHandle hRequest) = 0;
|
|
|
|
// Checks if a response header is present in a HTTP response given a handle
|
|
// from HTTPRequestCompleted_t, also returns the size of the header value if
|
|
// present so the caller and allocate a correctly sized buffer for
|
|
// GetHTTPResponseHeaderValue.
|
|
virtual bool GetHTTPResponseHeaderSize(HTTPRequestHandle hRequest,
|
|
const char *pchHeaderName,
|
|
uint32 *unResponseHeaderSize) = 0;
|
|
|
|
// Gets header values from a HTTP response given a handle from
|
|
// HTTPRequestCompleted_t, will return false if the header is not present or
|
|
// if your buffer is too small to contain it's value. You should first call
|
|
// BGetHTTPResponseHeaderSize to check for the presence of the header and to
|
|
// find out the size buffer needed.
|
|
virtual bool GetHTTPResponseHeaderValue(HTTPRequestHandle hRequest,
|
|
const char *pchHeaderName,
|
|
uint8 *pHeaderValueBuffer,
|
|
uint32 unBufferSize) = 0;
|
|
|
|
// Gets the size of the body data from a HTTP response given a handle from
|
|
// HTTPRequestCompleted_t, will return false if the handle is invalid.
|
|
virtual bool GetHTTPResponseBodySize(HTTPRequestHandle hRequest,
|
|
uint32 *unBodySize) = 0;
|
|
|
|
// Gets the body data from a HTTP response given a handle from
|
|
// HTTPRequestCompleted_t, will return false if the handle is invalid or is
|
|
// to a streaming response, or if the provided buffer is not the correct
|
|
// size. Use BGetHTTPResponseBodySize first to find out the correct buffer
|
|
// size to use.
|
|
virtual bool GetHTTPResponseBodyData(HTTPRequestHandle hRequest,
|
|
uint8 *pBodyDataBuffer,
|
|
uint32 unBufferSize) = 0;
|
|
|
|
// Gets the body data from a streaming HTTP response given a handle from
|
|
// HTTPRequestDataReceived_t. Will return false if the handle is invalid or
|
|
// is to a non-streaming response (meaning it wasn't sent with
|
|
// SendHTTPRequestAndStreamResponse), or if the buffer size and offset do
|
|
// not match the size and offset sent in HTTPRequestDataReceived_t.
|
|
virtual bool GetHTTPStreamingResponseBodyData(HTTPRequestHandle hRequest,
|
|
uint32 cOffset,
|
|
uint8 *pBodyDataBuffer,
|
|
uint32 unBufferSize) = 0;
|
|
|
|
// Releases an HTTP response handle, should always be called to free
|
|
// resources after receiving a HTTPRequestCompleted_t callback and finishing
|
|
// using the response.
|
|
virtual bool ReleaseHTTPRequest(HTTPRequestHandle hRequest) = 0;
|
|
|
|
// 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.
|
|
virtual bool GetHTTPDownloadProgressPct(HTTPRequestHandle hRequest,
|
|
float *pflPercentOut) = 0;
|
|
|
|
// 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 so the server may know how to interpret the body.
|
|
virtual bool SetHTTPRequestRawPostBody(HTTPRequestHandle hRequest,
|
|
const char *pchContentType,
|
|
uint8 *pubBody,
|
|
uint32 unBodyLen) = 0;
|
|
|
|
// Creates a cookie container handle which you must later free with
|
|
// ReleaseCookieContainer(). If bAllowResponsesToModify=true than any
|
|
// response to your requests using this cookie container may add new cookies
|
|
// which may be transmitted with future requests. If
|
|
// bAllowResponsesToModify=false than only cookies you explicitly set will
|
|
// be sent. 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.
|
|
virtual HTTPCookieContainerHandle CreateCookieContainer(
|
|
bool bAllowResponsesToModify) = 0;
|
|
|
|
// Release a cookie container you are finished using, freeing it's memory
|
|
virtual bool ReleaseCookieContainer(
|
|
HTTPCookieContainerHandle hCookieContainer) = 0;
|
|
|
|
// Adds a cookie to the specified cookie container that will be used with
|
|
// future requests.
|
|
virtual bool SetCookie(HTTPCookieContainerHandle hCookieContainer,
|
|
const char *pchHost, const char *pchUrl,
|
|
const char *pchCookie) = 0;
|
|
|
|
// Set the cookie container to use for a HTTP request
|
|
virtual bool SetHTTPRequestCookieContainer(
|
|
HTTPRequestHandle hRequest,
|
|
HTTPCookieContainerHandle hCookieContainer) = 0;
|
|
|
|
// Set the extra user agent info for a request, this doesn't clobber the
|
|
// normal user agent, it just adds the extra info on the end
|
|
virtual bool SetHTTPRequestUserAgentInfo(HTTPRequestHandle hRequest,
|
|
const char *pchUserAgentInfo) = 0;
|
|
|
|
// Set that https request should require verified SSL certificate via
|
|
// machines certificate trust store
|
|
virtual bool SetHTTPRequestRequiresVerifiedCertificate(
|
|
HTTPRequestHandle hRequest, bool bRequireVerifiedCertificate) = 0;
|
|
|
|
// Set an absolute timeout on the HTTP request, this is just a total time
|
|
// timeout different than the network activity timeout which can bump
|
|
// everytime we get more data
|
|
virtual bool SetHTTPRequestAbsoluteTimeoutMS(HTTPRequestHandle hRequest,
|
|
uint32 unMilliseconds) = 0;
|
|
|
|
// Check if the reason the request failed was because we timed it out
|
|
// (rather than some harder failure)
|
|
virtual bool GetHTTPRequestWasTimedOut(HTTPRequestHandle hRequest,
|
|
bool *pbWasTimedOut) = 0;
|
|
};
|
|
|
|
#define STEAMHTTP_INTERFACE_VERSION "STEAMHTTP_INTERFACE_VERSION002"
|
|
|
|
// callbacks
|
|
#if defined(VALVE_CALLBACK_PACK_SMALL)
|
|
#pragma pack(push, 4)
|
|
#elif defined(VALVE_CALLBACK_PACK_LARGE)
|
|
#pragma pack(push, 8)
|
|
#else
|
|
#error isteamclient.h must be included
|
|
#endif
|
|
|
|
struct HTTPRequestCompleted_t {
|
|
enum { k_iCallback = k_iClientHTTPCallbacks + 1 };
|
|
|
|
// Handle value for the request that has completed.
|
|
HTTPRequestHandle m_hRequest;
|
|
|
|
// Context value that the user defined on the request that this callback is
|
|
// associated with, 0 if no context value was set.
|
|
uint64 m_ulContextValue;
|
|
|
|
// This will be true if we actually got any sort of response from the server
|
|
// (even an error). It will be false if we failed due to an internal error
|
|
// or client side network failure.
|
|
bool m_bRequestSuccessful;
|
|
|
|
// 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.
|
|
EHTTPStatusCode m_eStatusCode;
|
|
|
|
uint32 m_unBodySize; // Same as GetHTTPResponseBodySize()
|
|
};
|
|
|
|
struct HTTPRequestHeadersReceived_t {
|
|
enum { k_iCallback = k_iClientHTTPCallbacks + 2 };
|
|
|
|
// Handle value for the request that has received headers.
|
|
HTTPRequestHandle m_hRequest;
|
|
|
|
// Context value that the user defined on the request that this callback is
|
|
// associated with, 0 if no context value was set.
|
|
uint64 m_ulContextValue;
|
|
};
|
|
|
|
struct HTTPRequestDataReceived_t {
|
|
enum { k_iCallback = k_iClientHTTPCallbacks + 3 };
|
|
|
|
// Handle value for the request that has received data.
|
|
HTTPRequestHandle m_hRequest;
|
|
|
|
// Context value that the user defined on the request that this callback is
|
|
// associated with, 0 if no context value was set.
|
|
uint64 m_ulContextValue;
|
|
|
|
// Offset to provide to GetHTTPStreamingResponseBodyData to get this chunk
|
|
// of data
|
|
uint32 m_cOffset;
|
|
|
|
// Size to provide to GetHTTPStreamingResponseBodyData to get this chunk of
|
|
// data
|
|
uint32 m_cBytesReceived;
|
|
};
|
|
|
|
#pragma pack(pop)
|
|
|
|
#endif // ISTEAMHTTP_H
|