00001 /** 00002 * vim: set ts=4 : 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_INTERFACE_USERMESSAGES_H_ 00033 #define _INCLUDE_SOURCEMOD_INTERFACE_USERMESSAGES_H_ 00034 00035 #include <IShareSys.h> 00036 #include <sp_vm_api.h> 00037 #include <IForwardSys.h> 00038 #include <bitbuf.h> 00039 #include <irecipientfilter.h> 00040 00041 /** 00042 * @file IUserMessages.h 00043 * @brief Contains functions for advanced usermessage hooking. 00044 */ 00045 00046 #define SMINTERFACE_USERMSGS_NAME "IUserMessages" 00047 #define SMINTERFACE_USERMSGS_VERSION 3 00048 00049 namespace SourceMod 00050 { 00051 /** 00052 * @brief Listens to user messages sent from the server. 00053 */ 00054 class IUserMessageListener 00055 { 00056 public: 00057 /** 00058 * @brief Called when a hooked user message is being sent 00059 * and all interceptions have finished. 00060 * 00061 * @param msg_id Message Id. 00062 * @param bf bf_write structure containing written bytes. 00063 * @param pFilter Recipient filter. 00064 */ 00065 virtual void OnUserMessage(int msg_id, bf_write *bf, IRecipientFilter *pFilter) 00066 { 00067 } 00068 00069 /** 00070 * @brief Called when a hooked user message is intercepted. 00071 * 00072 * @param msg_id Message Id. 00073 * @param bf bf_write structure containing written bytes. 00074 * @param pFilter Recipient filter. 00075 * @return Pl_Continue to allow message, Pl_Stop or Pl_Handled to scrap it. 00076 */ 00077 virtual ResultType InterceptUserMessage(int msg_id, bf_write *bf, IRecipientFilter *pFilter) 00078 { 00079 return Pl_Continue; 00080 } 00081 00082 /** 00083 * @brief Called when a hooked user message is sent, regardless of the hook type. 00084 * 00085 * Note: This is called regardless of the API version, though it only happens if the 00086 * message is successfully sent. 00087 * 00088 * @param msg_id Message Id. 00089 */ 00090 virtual void OnUserMessageSent(int msg_id) 00091 { 00092 } 00093 00094 /** 00095 * @brief Returns the user message API version. 00096 */ 00097 virtual unsigned int GetUserMessageAPIVersion() 00098 { 00099 return SMINTERFACE_USERMSGS_VERSION; 00100 } 00101 00102 /** 00103 * @brief Called when a hooked user message hook is finished, regardless of the hook type. 00104 * 00105 * Note: this is only called if hooked using the new API (version 2 or greater). 00106 * 00107 * @param msg_id Message Id. 00108 * @param sent True if message was sent, false if blocked. 00109 */ 00110 virtual void OnPostUserMessage(int msg_id, bool sent) 00111 { 00112 } 00113 }; 00114 00115 #define USERMSG_RELIABLE (1<<2) /**< Message will be set to reliable */ 00116 #define USERMSG_INITMSG (1<<3) /**< Message will be considered to be an initmsg */ 00117 #define USERMSG_BLOCKHOOKS (1<<7) /**< Prevents the message from triggering SourceMod and Metamod hooks */ 00118 00119 /** 00120 * @brief Contains functions for hooking user messages. 00121 */ 00122 class IUserMessages : public SMInterface 00123 { 00124 public: 00125 virtual unsigned int GetInterfaceVersion() 00126 { 00127 return SMINTERFACE_USERMSGS_VERSION; 00128 } 00129 virtual const char *GetInterfaceName() 00130 { 00131 return SMINTERFACE_USERMSGS_NAME; 00132 } 00133 public: 00134 /** 00135 * @brief Finds a message id by name. 00136 * 00137 * @param msg Case-sensitive string containing the message. 00138 * @return A message index, or -1 on failure. 00139 */ 00140 virtual int GetMessageIndex(const char *msg) =0; 00141 00142 /** 00143 * @brief Sets a hook on a user message. 00144 * 00145 * @param msg_id Message Id. 00146 * @param pListener Pointer to an IUserMessageListener. 00147 * @param intercept If true, message will be intercepted rather than merely hooked. 00148 * @return True on success, false otherwise. 00149 */ 00150 virtual bool HookUserMessage(int msg_id, 00151 IUserMessageListener *pListener, 00152 bool intercept=false) =0; 00153 00154 /** 00155 * @brief Unhooks a user message. 00156 * 00157 * @param msg_id Message Id. 00158 * @param pListener Pointer to an IUserMessageListener. 00159 * @param intercept If true, message is removed from interception pool rather than the 00160 * normal hook pool. 00161 * @return True on success, false otherwise. 00162 */ 00163 virtual bool UnhookUserMessage(int msg_id, 00164 IUserMessageListener *pListener, 00165 bool intercept=false) =0; 00166 00167 /** 00168 * @brief Wrapper around UserMessageBegin for more options. 00169 * 00170 * @param msg_id Message Id. 00171 * @param players Array containing player indexes. 00172 * @param playersNum Number of players in the array. 00173 * @param flags Flags to use for sending the message. 00174 * @return bf_write structure to write message with, or NULL on failure. 00175 */ 00176 virtual bf_write *StartMessage(int msg_id, 00177 const cell_t players[], 00178 unsigned int playersNum, 00179 int flags) =0; 00180 00181 /** 00182 * @brief Wrapper around UserMessageEnd for use with StartMessage(). 00183 * @return True on success, false otherwise. 00184 */ 00185 virtual bool EndMessage() =0; 00186 00187 /** 00188 * @brief Sets a hook on a user message using the newer API (OnPostUserMessage). 00189 * 00190 * @param msg_id Message Id. 00191 * @param pListener Pointer to an IUserMessageListener. 00192 * @param intercept If true, message will be intercepted rather than merely hooked. 00193 * @return True on success, false otherwise. 00194 */ 00195 virtual bool HookUserMessage2(int msg_id, 00196 IUserMessageListener *pListener, 00197 bool intercept=false) =0; 00198 00199 /** 00200 * @brief Unhooks a user message using the newer API (OnPostUserMessage). 00201 * 00202 * @param msg_id Message Id. 00203 * @param pListener Pointer to an IUserMessageListener. 00204 * @param intercept If true, message is removed from interception pool rather than the 00205 * normal hook pool. 00206 * @return True on success, false otherwise. 00207 */ 00208 virtual bool UnhookUserMessage2(int msg_id, 00209 IUserMessageListener *pListener, 00210 bool intercept=false) =0; 00211 00212 /** 00213 * @brief Finds a message name by id. 00214 * 00215 * @param msgid The message index. 00216 * @param buffer Buffer string to hold the message name in. 00217 * @param maxlength Size of the buffer. 00218 * @return A message index, or -1 on failure. 00219 */ 00220 virtual bool GetMessageName(int msgid, char *buffer, size_t maxlength) const =0; 00221 }; 00222 } 00223 00224 #endif //_INCLUDE_SOURCEMOD_INTERFACE_USERMESSAGES_H_
1.7.1