/* GameSpy GHTTP SDK Dan "Mr. Pants" Schoenblum dan@gamespy.com Copyright 1999-2007 GameSpy Industries, Inc devsupport@gamespy.com */ #ifndef _GHTTP_H_ #define _GHTTP_H_ #include #include "../common/gsCommon.h" #include "../common/gsXML.h" #ifdef __cplusplus extern "C" { #endif #ifndef GSI_UNICODE #define ghttpGet ghttpGetA #define ghttpGetEx ghttpGetExA #define ghttpSave ghttpSaveA #define ghttpSaveEx ghttpSaveExA #define ghttpStream ghttpStreamA #define ghttpStreamEx ghttpStreamExA #define ghttpHead ghttpHeadA #define ghttpHeadEx ghttpHeadExA #define ghttpPost ghttpPostA #define ghttpPostEx ghttpPostExA #define ghttpPostAddString ghttpPostAddStringA #define ghttpPostAddFileFromDisk ghttpPostAddFileFromDiskA #define ghttpPostAddFileFromMemory ghttpPostAddFileFromMemoryA #else #define ghttpGet ghttpGetW #define ghttpGetEx ghttpGetExW #define ghttpSave ghttpSaveW #define ghttpSaveEx ghttpSaveExW #define ghttpStream ghttpStreamW #define ghttpStreamEx ghttpStreamExW #define ghttpHead ghttpHeadW #define ghttpHeadEx ghttpHeadExW #define ghttpPost ghttpPostW #define ghttpPostEx ghttpPostExW #define ghttpPostAddString ghttpPostAddStringW #define ghttpPostAddFileFromDisk ghttpPostAddFileFromDiskW #define ghttpPostAddFileFromMemory ghttpPostAddFileFromMemoryW #endif // Boolean. /////////// typedef enum { GHTTPFalse, GHTTPTrue } GHTTPBool; // ByteCount. ///////////// #if (GSI_MAX_INTEGRAL_BITS >= 64) typedef gsi_i64 GHTTPByteCount; #else typedef gsi_i32 GHTTPByteCount; #endif // The current state of an http request. //////////////////////////////////////// typedef enum { GHTTPSocketInit, // Socket creation and initialization. GHTTPHostLookup, // Resolving hostname to IP (asynchronously if possible). GHTTPLookupPending, // Asychronous DNS lookup pending. GHTTPConnecting, // Waiting for socket connect to complete. GHTTPSecuringSession, // Setup secure channel. GHTTPSendingRequest, // Sending the request. GHTTPPosting, // Positing data (skipped if not posting). GHTTPWaiting, // Waiting for a response. GHTTPReceivingStatus, // Receiving the response status. GHTTPReceivingHeaders, // Receiving the headers. GHTTPReceivingFile // Receiving the file. } GHTTPState; // The result of an http request. ///////////////////////////////// typedef enum { GHTTPSuccess, // 0: Successfully retrieved file. GHTTPOutOfMemory, // 1: A memory allocation failed. GHTTPBufferOverflow, // 2: The user-supplied buffer was too small to hold the file. GHTTPParseURLFailed, // 3: There was an error parsing the URL. GHTTPHostLookupFailed, // 4: Failed looking up the hostname. GHTTPSocketFailed, // 5: Failed to create/initialize/read/write a socket. GHTTPConnectFailed, // 6: Failed connecting to the http server. GHTTPBadResponse, // 7: Error understanding a response from the server. GHTTPRequestRejected, // 8: The request has been rejected by the server. GHTTPUnauthorized, // 9: Not authorized to get the file. GHTTPForbidden, // 10: The server has refused to send the file. GHTTPFileNotFound, // 11: Failed to find the file on the server. GHTTPServerError, // 12: The server has encountered an internal error. GHTTPFileWriteFailed, // 13: An error occured writing to the local file (for ghttpSaveFile[Ex]). GHTTPFileReadFailed, // 14: There was an error reading from a local file (for posting files from disk). GHTTPFileIncomplete, // 15: Download started but was interrupted. Only reported if file size is known. GHTTPFileToBig, // 16: The file is to big to be downloaded (size exceeds range of interal data types) GHTTPEncryptionError, // 17: Error with encryption engine. GHTTPRequestCancelled // 18: User requested cancel and/or graceful close. } GHTTPResult; // Encryption engines typedef enum { GHTTPEncryptionEngine_None, GHTTPEncryptionEngine_GameSpy, // must add /common/gsSSL.h and /common/gsSSL.c to project GHTTPEncryptionEngine_MatrixSsl, // must define MATRIXSSL and include matrixssl source files GHTTPEncryptionEngine_RevoEx, // must define REVOEXSSL and include RevoEX SSL source files GHTTPEncryptionEngine_Default // Will use GameSpy unless another engine is defined // using MATRIXSSL or REVOEXSSL } GHTTPEncryptionEngine; // Represents an http file request. /////////////////////////////////// typedef int GHTTPRequest; // Invalid GHTTPRequest values represent an error /////////////////////////////////// #ifdef GHTTP_EXTENDEDERROR typedef enum { GHTTPErrorStart = -8, GHTTPFailedToOpenFile, GHTTPInvalidPost, GHTTPInsufficientMemory, GHTTPInvalidFileName, GHTTPInvalidBufferSize, GHTTPInvalidURL, GHTTPUnspecifiedError = -1 } GHTTPRequestError; #else // Backwards compatibility, developers may have relied on -1 as the only error code typedef enum { GHTTPErrorStart = -1, GHTTPFailedToOpenFile = -1, GHTTPInvalidPost = -1, GHTTPInsufficientMemory = -1, GHTTPInvalidFileName = -1, GHTTPInvalidBufferSize = -1, GHTTPInvalidURL = -1, GHTTPUnspecifiedError = -1 } GHTTPRequestError; #endif #define IS_GHTTP_ERROR(x) (x<0) // Data that can be posted to the server. // Don't try to access this object directly, // use the ghttpPost*() functions. //////////////////////////////////////////// typedef struct GHIPost * GHTTPPost; // Called with updates on the current state of the request. // The buffer should not be accessed once this callback returns. // If ghttpGetFile[Ex] was used, buffer contains all of the data that has been // received so far, and bufferSize is the total number of bytes received. // If ghttpSaveFile[Ex] was used, buffer only contains the most recent data // that has been received. This same data is saved to the file. The buffer // will not be valid after this callback returns. // If ghttpStreamFileEx was used, buffer only contains the most recent data // that has been received. This data will be lost once the callback // returns, and should be copied if it needs to be saved. bufferSize // is the number of bytes in the current block of data. ////////////////////////////////////////////////////////////////////////////// typedef void (* ghttpProgressCallback) ( GHTTPRequest request, // The request. GHTTPState state, // The current state of the request. const char * buffer, // The file's bytes so far, NULL if state[:port]". If port is omitted, 80 will be used. // If server is NULL or "", no proxy server will be used. // This should not be called while there are any current requests. ////////////////////////////////////////////////////////////////// GHTTPBool ghttpSetProxy ( const char * server ); // Sets a proxy server for a specific request. The address should be of the // form "[:port]". If port is omitted, 80 will be used. // If server is NULL or "", no proxy server will be used. ////////////////////////////////////////////////////////////////// GHTTPBool ghttpSetRequestProxy ( GHTTPRequest request, const char * server ); // Used to start/stop throttling an existing connection. // This may not be as efficient as starting a request // with the desired setting. //////////////////////////////////////////////////////// void ghttpSetThrottle ( GHTTPRequest request, GHTTPBool throttle ); // Used to adjust the throttle settings. //////////////////////////////////////// void ghttpThrottleSettings ( int bufferSize, // The number of bytes to get each receive. gsi_time timeDelay // How often to receive data, in milliseconds. ); // Used to throttle based on time, not on bandwidth // Prevents recv-loop blocking on ultrafast connections without directly limiting transfer rate //////////////////////////////////////// void ghttpSetMaxRecvTime ( GHTTPRequest request, gsi_time maxRecvTime ); // Creates a new post object, which is used to represent data to send to // the web server as part of a request. // After getting the post object, use the ghttpPostAdd*() functions // to add data to the object, and ghttPostSetCallback() to add a // callback to monitor the progress of the data upload. // By default post objects automatically free themselves after posting. // To use the same post with more than one request, set auto-free to false, // then use ghttpFreePost to free it _after_ every request its being used // in is _completed_. // Returns NULL on error. /////////////////////////////////////////////////////////////////////////// GHTTPPost ghttpNewPost ( void ); // Sets a post object's auto-free flag. // By default post objects automatically free themselves after posting. // To use the same post with more than one request, set auto-free to false, // then use ghttpFreePost to free it _after_ every request its being used // in is _completed_. /////////////////////////////////////////////////////////////////////////// void ghttpPostSetAutoFree ( GHTTPPost post, GHTTPBool autoFree ); // Frees a post object. /////////////////////// void ghttpFreePost ( GHTTPPost post // The post object to free. ); // Adds a string to the post object. //////////////////////////////////// GHTTPBool ghttpPostAddString ( GHTTPPost post, // The post object to add to. const gsi_char * name, // The name to attach to this string. const gsi_char * string // The actual string. ); // Adds a disk file to the post object. // The reportFilename is what is reported to the server as the filename. // If NULL or empty, the filename will be used (including any possible path). // The contentType is the MIME type to report for this file. // If NULL, "application/octet-stream" is used. // The file isn't read from until the data is actually sent to the server. // Returns false for any error. ///////////////////////////////////////////////////////////////////////////// GHTTPBool ghttpPostAddFileFromDisk ( GHTTPPost post, // The post object to add to. const gsi_char * name, // The name to attach to this file. const gsi_char * filename, // The name (and possibly path) to the file to upload. const gsi_char * reportFilename,// The filename given to the web server. const gsi_char * contentType // The MIME type for this file. ); // Adds a file, in memory, to the post object. // The reportFilename is what is reported to the server as the filename. // Cannot be NULL or empty. // The contentType is the MIME type to report for this file. // If NULL, "application/octet-stream" is used. // The data is NOT copied off in this call. The data pointer is read from // as the data is actually sent to the server. The pointer must remain // valid during requests. // Returns false for any error. ////////////////////////////////////////////////////////////////////////// GHTTPBool ghttpPostAddFileFromMemory ( GHTTPPost post, // The post object to add to. const gsi_char * name, // The name to attach to this string. const char * buffer, // The data to send. int bufferLen, // The number of bytes of data to send. const gsi_char * reportFilename, // The filename given to the web server. const gsi_char * contentType // The MIME type for this file. ); // Adds an XML SOAP object to the post object. // See ghttpNewSoap and other Soap related functions // Content-Type = text/xml // The most common use of this function is to add ghttpSoap data GHTTPBool ghttpPostAddXml ( GHTTPPost post, GSXmlStreamWriter xmlSoap ); // Called during requests to let the app know how much of the post // data has been uploaded. ////////////////////////////////////////////////////////////////// typedef void (* ghttpPostCallback) ( GHTTPRequest request, // The request. int bytesPosted, // The number of bytes of data posted so far. int totalBytes, // The total number of bytes being posted. int objectsPosted, // The total number of data objects uploaded so far. int totalObjects, // The total number of data objects to upload. void * param // User-data. ); // Set the callback for a post object. ////////////////////////////////////// void ghttpPostSetCallback ( GHTTPPost post, // The post object to set the callback on. ghttpPostCallback callback, // The callback to call when using this post object. void * param // User-data passed to the callback. ); // Use ssl encryption engine GHTTPBool ghttpSetRequestEncryptionEngine ( GHTTPRequest request, GHTTPEncryptionEngine engine ); // These are defined for backwards compatibility with the "file" function names. //////////////////////////////////////////////////////////////////////////////// #define ghttpGetFile(a, b, c, d) ghttpGet(a, b, c, d) #define ghttpGetFileEx(a, b, c, d, e, f, g, h, i, j) ghttpGetEx(a, b, c, d, e, f, g, h, i, j) #define ghttpSaveFile(a, b, c, d, e) ghttpSave(a, b, c, d, e) #define ghttpSaveFileEx(a, b, c, d, e, f, g, h, i) ghttpSaveEx(a, b, c, d, e, f, g, h, i) #define ghttpStreamFile(a, b, c, d, e) ghttpStream(a, b, c, d, e) #define ghttpStreamFileEx(a, b, c, d, e, f, g, h) ghttpStreamEx(a, b, c, d, e, f, g, h) #define ghttpHeadFile(a, b, c, d) ghttpHead(a, b, c, d) #define ghttpHeadFileEx(a, b, c, d, e, f, g) ghttpHeadEx(a, b, c, d, e, f, g) // This ASCII version needs to be define even in UNICODE mode GHTTPRequest ghttpGetA ( const char * URL, // The URL for the file ("http://host.domain[:port]/path/filename"). GHTTPBool blocking, // If true, this call doesn't return until the file has been recevied. ghttpCompletedCallback completedCallback, // Called when the file has been received. void * param // User-data to be passed to the callbacks. ); #define ghttpGetFileA(a, b, c, d) ghttpGetA(a, b, c, d) #ifdef __cplusplus } #endif #endif