00001 /** 00002 * vim: set ts=4 noet : 00003 * ============================================================================= 00004 * SourceMod 00005 * Copyright (C) 2004-2008 AlliedModders LLC. All rights reserved. 00006 * ============================================================================= 00007 * 00008 * This program is free software; you can redistribute it and/or modify it under 00009 * the terms of the GNU General Public License, version 3.0, as published by the 00010 * Free Software Foundation. 00011 * 00012 * This program is distributed in the hope that it will be useful, but WITHOUT 00013 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS 00014 * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more 00015 * details. 00016 * 00017 * You should have received a copy of the GNU General Public License along with 00018 * this program. If not, see <http://www.gnu.org/licenses/>. 00019 * 00020 * As a special exception, AlliedModders LLC gives you permission to link the 00021 * code of this program (as well as its derivative works) to "Half-Life 2," the 00022 * "Source Engine," the "SourcePawn JIT," and any Game MODs that run on software 00023 * by the Valve Corporation. You must obey the GNU General Public License in 00024 * all respects for all other code used. Additionally, AlliedModders LLC grants 00025 * this exception to all derivative works. AlliedModders LLC defines further 00026 * exceptions, found in LICENSE.txt (as of this writing, version JULY-31-2007), 00027 * or <http://www.sourcemod.net/license.php>. 00028 * 00029 * Version: $Id$ 00030 */ 00031 00032 #ifndef _INCLUDE_SOURCEMOD_WEBTERNET_INTERFACE_H_ 00033 #define _INCLUDE_SOURCEMOD_WEBTERNET_INTERFACE_H_ 00034 00035 #include <IShareSys.h> 00036 00037 /** 00038 * @file IWebternet.h 00039 * @brief Interface header for lib cURL. 00040 */ 00041 00042 #define SMINTERFACE_WEBTERNET_NAME "IWebternet" 00043 #define SMINTERFACE_WEBTERNET_VERSION 2 00044 00045 namespace SourceMod 00046 { 00047 /** 00048 * @brief Status to return via the OnDownloadWrite function of ITransferHandler. 00049 */ 00050 enum DownloadWriteStatus 00051 { 00052 DownloadWrite_Okay, /**< Data transfer was successful. */ 00053 DownloadWrite_Error, /**< Halt the transfer and return an error. */ 00054 }; 00055 00056 class IWebTransfer; 00057 class IWebternet; 00058 00059 /** 00060 * @brief Form for POSTing data. 00061 */ 00062 class IWebForm 00063 { 00064 public: 00065 /** 00066 * @brief Free with delete. 00067 */ 00068 virtual ~IWebForm() 00069 { 00070 } 00071 public: 00072 /** 00073 * @brief Adds raw data to the form. 00074 * 00075 * All data is copied locally and may go out of scope. 00076 * 00077 * @param name Field name (null terminated). 00078 * @param data Field data (null terminated). 00079 * @return True on success, false on failure. 00080 */ 00081 virtual bool AddString(const char *name, const char *data) = 0; 00082 }; 00083 00084 /** 00085 * @brief Transfer handler interface. 00086 */ 00087 class ITransferHandler 00088 { 00089 public: 00090 /** 00091 * @brief Must return the interface version this listener is compatible with. 00092 * 00093 * @return Interface version. 00094 */ 00095 virtual unsigned int GetURLInterfaceVersion() 00096 { 00097 return SMINTERFACE_WEBTERNET_VERSION; 00098 } 00099 00100 /** 00101 * @brief Called when a downloader needs to write data it has received. 00102 * 00103 * @param downloader Downloader object. 00104 * @param userdata User data passed to download function. 00105 * @param ptr Memory containing the received data. 00106 * @param size Size of each block in ptr. 00107 * @param nmemb Number of blocks in ptr. 00108 * @return Download status. 00109 */ 00110 virtual DownloadWriteStatus OnDownloadWrite(IWebTransfer *session, 00111 void *userdata, 00112 void *ptr, 00113 size_t size, 00114 size_t nmemb) 00115 { 00116 return DownloadWrite_Error; 00117 } 00118 }; 00119 00120 /** 00121 * @brief Transfer interface. 00122 * 00123 * Though one instance may be used across multiple threads, the interface cannot be modified 00124 * while a transfer is in progress. 00125 */ 00126 class IWebTransfer 00127 { 00128 public: 00129 /** 00130 * @brief Virtual destructor. Call delete to release the resources. 00131 */ 00132 virtual ~IWebTransfer() 00133 { 00134 } 00135 00136 /** 00137 * @brief Returns a human-readable error message from the last failure. 00138 * 00139 * @return Error message. 00140 */ 00141 virtual const char *LastErrorMessage() = 0; 00142 00143 /** 00144 * @brief Returns the last error code, if any. 00145 * 00146 * @return Last error code. 00147 */ 00148 virtual int LastErrorCode() = 0; 00149 00150 /** 00151 * @brief Sets whether header information is returned, if any. 00152 * 00153 * @param recv_hdr True to return headers, false otherwise. 00154 * @return True on success, false on failure. 00155 */ 00156 virtual bool SetHeaderReturn(bool recv_hdr) = 0; 00157 00158 /** 00159 * @brief Downloads a URL. 00160 * 00161 * @param url URL to download. 00162 * @param handler Handler object. 00163 * @param userdata User data pointer. 00164 * @return True on success, false on failure. 00165 */ 00166 virtual bool Download(const char *url, ITransferHandler *handler, void *data) = 0; 00167 00168 /** 00169 * @brief Downloads a URL with POST options. 00170 * 00171 * @param url URL to download. 00172 * @param form Form to read POST info from. 00173 * @param handler Handler object. 00174 * @param userdata User data pointer. 00175 * @return True on success, false on failure. 00176 */ 00177 virtual bool PostAndDownload(const char *url, 00178 IWebForm *form, 00179 ITransferHandler *handler, 00180 void *data) = 0; 00181 00182 /** 00183 * @brief Sets whether an HTTP failure (>= 400) returns false from Download(). 00184 * 00185 * Note: defaults to false. 00186 * 00187 * @param fail True to fail, false otherwise. 00188 * @return True on success, false otherwise. 00189 */ 00190 virtual bool SetFailOnHTTPError(bool fail) = 0; 00191 }; 00192 00193 /** 00194 * @brief Interface for managing web URL sessions. 00195 */ 00196 class IWebternet : public SMInterface 00197 { 00198 public: 00199 virtual unsigned int GetInterfaceVersion() = 0; 00200 virtual const char *GetInterfaceName() = 0; 00201 public: 00202 /** 00203 * @brief Create a URL transfer session object. 00204 * 00205 * @return Object, or NULL on failure. 00206 */ 00207 virtual IWebTransfer *CreateSession() = 0; 00208 00209 /** 00210 * @brief Creates a form for building POST data. 00211 * 00212 * @return New form, or NULL on failure. 00213 */ 00214 virtual IWebForm *CreateForm() = 0; 00215 }; 00216 } 00217 00218 #endif //_INCLUDE_SOURCEMOD_WEBTERNET_INTERFACE_H_ 00219
1.7.1