3 * ======================================================
5 * Copyright (C) 2004-2008 AlliedModders LLC and authors.
7 * ======================================================
9 * This software is provided 'as-is', without any express or implied warranty.
10 * In no event will the authors be held liable for any damages arising from
11 * the use of this software.
13 * Permission is granted to anyone to use this software for any purpose,
14 * including commercial applications, and to alter it and redistribute it
15 * freely, subject to the following restrictions:
17 * 1. The origin of this software must not be misrepresented; you must not
18 * claim that you wrote the original software. If you use this software in a
19 * product, an acknowledgment in the product documentation would be
20 * appreciated but is not required.
21 * 2. Altered source versions must be plainly marked as such, and must not be
22 * misrepresented as being the original software.
23 * 3. This notice may not be removed or altered from any source distribution.
28 #ifndef _INCLUDE_ISMM_API_H
29 #define _INCLUDE_ISMM_API_H
32 * @brief Core API calls that are provided to plugins.
37 #include <sourcehook.h>
38 #include <IPluginManager.h>
39 #include <ISmmPlugin.h>
40 #include <ISmmPluginExt.h>
43 #if ((__GNUC__ == 3) && (__GNUC_MINOR__ < 4)) || (__GNUC__ < 3)
44 #error "You must compile with at least GCC 3.4! If you know what you are doing, you can remove this message."
45 #endif //version check
48 #define MMIFACE_SOURCEHOOK "ISourceHook" /**< ISourceHook Pointer */
49 #define MMIFACE_PLMANAGER "IPluginManager" /**< SourceMM Plugin Functions */
50 #define MMIFACE_SH_HOOKMANAUTOGEN "IHookManagerAutoGen" /**< SourceHook::IHookManagerAutoGen Pointer */
51 #define IFACE_MAXNUM 999 /**< Maximum interface version */
53 #if defined META_NO_HL2SDK
55 class IServerPluginCallbacks;
62 // Interface return status, binary-compatible with HL2SDK's IFACE_OK and IFACE_FAILED.
69 typedef void* (*CreateInterfaceFn)(const char *pName, int *pReturnCode);
74 class IMetamodListener;
77 * The core API that Metamod:Source provides to plugins.
83 * @brief Logs a message through the HL2 log system.
84 * Note: Newlines are appended automatically.
86 * @param pl Plugin API pointer (used for tagging message)
87 * @param msg Formatted string.
89 virtual void LogMsg(ISmmPlugin *pl, const char *msg, ...) =0;
92 * @brief Returns an interface factory for the HL2 engine.
94 * @param syn If syn is true, the synthetic wrapper is returned.
95 * If syn is false, the true function is returned.
96 * @return CreateInterfaceFn function pointer.
98 virtual CreateInterfaceFn GetEngineFactory(bool syn=true) =0;
101 * @brief Returns an interface factory for the HL2 physics engine.
103 * @param syn If syn is true, the synthetic wrapper is returned.
104 * If syn is false, the true function is returned.
105 * @return CreateInterfaceFn function pointer.
107 virtual CreateInterfaceFn GetPhysicsFactory(bool syn=true) =0;
110 * @brief Returns an interface factory for the HL2 file system.
112 * @param syn If syn is true, the synthetic wrapper is returned.
113 * If syn is false, the true function is returned.
114 * @return CreateInterfaceFn function pointer.
116 virtual CreateInterfaceFn GetFileSystemFactory(bool syn=true) =0;
119 * @brief Returns an interface factory for the GameDLL.
121 * If syn is false, the true function is returned.
122 * @return CreateInterfaceFn function pointer.
124 virtual CreateInterfaceFn GetServerFactory(bool syn=true) =0;
127 * @brief Returns a CGlobalVars pointer from the HL2 Engine.
129 * @return CGlobalVars pointer.
131 virtual CGlobalVars *GetCGlobals() =0;
134 * @brief Registers a ConCommandBase.
136 * @param plugin Parent plugin API pointer.
137 * @param pCommand ConCommandBase to register.
138 * @return True if successful, false otherwise.
140 virtual bool RegisterConCommandBase(ISmmPlugin *plugin, ConCommandBase *pCommand) =0;
143 * @brief Unregisters a ConCommandBase.
145 * @param plugin Parent plugin API pointer.
146 * @param pCommand ConCommandBase to unlink.
148 virtual void UnregisterConCommandBase(ISmmPlugin *plugin, ConCommandBase *pCommand) =0;
151 * @brief Prints an unformatted string to the remote server console.
153 * Note: Newlines are not added automatically.
155 * @param str Message string.
157 virtual void ConPrint(const char *str) =0;
160 * @brief Prints a formatted message to the remote server console.
162 * Note: Newlines are not added automatically.
164 * @param fmt Formatted message.
166 virtual void ConPrintf(const char *fmt, ...) =0;
169 * @brief Returns the Metamod Version numbers as major version and
170 * minor (API) version. Changes to minor version are guaranteed to be
171 * backwards compatible. Changes to major version are not.
173 * @param major Filled with the major API version number.
174 * @param minor Filled with the minor API version number.
175 * @param plvers Filled with the current plugin API version number.
176 * @param plmin Filled with the minimum plugin API version number
179 virtual void GetApiVersions(int &major, int &minor, int &plvers, int &plmin) =0;
182 * @brief Returns sourcehook API version and implementation version.
184 * @param shvers Filled with the SourceHook API version number.
185 * @param shimpl Filled with the SourceHook implementation number.
187 virtual void GetShVersions(int &shvers, int &shimpl) =0;
190 * @brief Adds a Metamod listener.
192 * @param plugin Plugin interface pointer.
193 * @param pListener Listener interface pointer to add.
195 virtual void AddListener(ISmmPlugin *plugin, IMetamodListener *pListener) =0;
198 * @brief Queries the metamod factory
200 * @param iface String containing interface name
201 * @param ret Optional pointer to store return status
202 * @param id Optional pointer to store id of plugin that
203 * overrode interface, 0 if none
204 * @return Returned pointer
206 virtual void *MetaFactory(const char *iface, int *ret, PluginId *id) =0;
209 * @brief Given a base interface name, such as ServerGameDLL or
210 * ServerGameDLL003, reformats the string to increase the number, then
211 * returns the new number. This is the base function to InterfaceSearch()
212 * and VInterfaceMatch().
214 * @param iface Input/output interface name. Must be writable.
215 * @param maxlength Maximum length of iface buffer. Must be at least
216 * strlen(iface)+4 chars.
217 * @return The newly incremented iface version number.
218 * @deprecated Use InterfaceSearch() or VInterfaceMatch instead.
220 virtual int FormatIface(char iface[], unsigned int maxlength) =0;
223 * @brief Searches for an interface, eliminating the need to loop
224 * through FormatIface().
226 * @param fn InterfaceFactory function.
227 * @param iface Interface string name.
228 * @param max Maximum version to look up.
229 * @param ret Last return code from interface factory function.
230 * @return Interface pointer, or NULL if not found.
232 virtual void *InterfaceSearch(CreateInterfaceFn fn,
238 * @brief Returns the base directory of the game/server, equivalent to
239 * IVEngineServer::GetGameDir(), except the path is absolute.
241 * @return Static pointer to game's absolute basedir.
243 virtual const char *GetBaseDir() =0;
246 * @brief Formats a file path to the local OS.
248 * Does not include any base directories. Note that all slashes and
249 * black slashes are reverted to the local OS's expectancy.
251 * @param buffer Destination buffer to store path.
252 * @param len Maximum length of buffer, including null
254 * @param fmt Formatted string.
255 * @param ... Arguments in the string.
256 * @return Number of bytes written, not including the null
259 virtual size_t PathFormat(char *buffer, size_t len, const char *fmt, ...) =0;
262 * @brief Prints text in the specified client's console. Same as
263 * IVEngineServer::ClientPrintf except that it allows for string
266 * @param client Client edict pointer.
267 * @param fmt Formatted string to print to the client.
269 virtual void ClientConPrintf(edict_t *client, const char *fmt, ...) =0;
272 * @brief Wrapper around InterfaceSearch(). Assumes no maximum.
273 * This is designed to replace the fact that searches only went upwards.
274 * The "V" is intended to convey that this is for Valve formatted
277 * @param fn Interface factory function.
278 * @param iface Interface string.
279 * @param min Minimum value to search from. If zero, searching
280 * begins from the first available version regardless
281 * of the interface. Note that this can return
282 * interfaces EARLIER than the version specified. A
283 * value of -1 (default) specifies the string version
284 * as the minimum. Any other value specifices the
285 * minimum value to search from.
286 * @return Interface pointer, or NULL if not found.
288 virtual void *VInterfaceMatch(CreateInterfaceFn fn,
293 * @brief Tells SourceMM to add VSP hooking capability to plugins.
295 * Since this potentially uses more resources than it would otherwise,
296 * plugins have to explicitly enable the feature. Whether requested or
297 * not, if it is enabled, all plugins will get a pointer to the VSP
298 * listener through IMetamodListener. This will not be called more than
299 * once for a given plugin; if it is requested more than once, each
300 * successive call will only give the pointer to plugins which have not
303 virtual void EnableVSPListener() =0;
306 * @brief Returns the interface version of the GameDLL's IServerGameDLL
309 * @return Interface version of the loaded IServerGameDLL.
311 virtual int GetGameDLLVersion() =0;
314 * @brief Returns the number of user messages in the GameDLL.
316 * @return Number of user messages, or -1 if SourceMM has
317 * failed to get user message list.
319 virtual int GetUserMessageCount() =0;
322 * @brief Returns the index of the specified user message.
324 * @param name User message name.
325 * @param size Optional pointer to store size of user message.
326 * @return Message index, or -1 on failure.
328 virtual int FindUserMessage(const char *name, int *size=NULL) =0;
331 * @brief Returns the name of the specified user message.
333 * @param index User message index.
334 * @param size Optional pointer to store size of user message.
335 * @return Message name, or NULL on failure.
337 virtual const char *GetUserMessage(int index, int *size=NULL) =0;
340 * @brief Returns the highest interface version of IServerPluginCallbacks
341 * that the engine supports. This is useful for games that run on older
342 * versions of the Source engine, such as The Ship.
344 * @return Highest interface version of IServerPluginCallbacks.
345 * Returns 0 if SourceMM's VSP listener isn't
347 * @deprecated Use GetVSPInfo() instead.
349 virtual int GetVSPVersion() =0;
352 * @brief Returns the engine interface that MM:S is using as a backend.
354 * The values will be one of the SOURCE_ENGINE_* constants from the top
357 * @return A SOURCE_ENGINE_* constant value.
359 virtual int GetSourceEngineBuild() =0;
362 * @brief Returns the VSP listener loaded.
364 * This is useful for late-loading plugins which need to decide whether
365 * to add a listener or not (or need to get the pointer at all).
367 * @param pVersion Optional pointer to store the VSP version.
368 * @return IServerPluginCallbacks pointer, or NULL if an
369 * IMetamodListener event has yet to occur for
370 * EnableVSPListener().
372 virtual IServerPluginCallbacks *GetVSPInfo(int *pVersion) =0;
375 * @brief Formats a string. This is a platform safe wrapper around
376 * snprintf/_snprintf.
378 * @param buffer Buffer to write to.
379 * @param maxlength Maximum length of the buffer.
380 * @param format Format specifiers.
381 * @param ... Format arguments.
382 * @return Number of bytes actually written, not including
383 * the null terminator.
385 virtual size_t Format(char *buffer,
391 * @brief Formats a string. This is a platform safe wrapper around
392 * vsnprintf/_vsnprintf.
394 * @param buffer Buffer to write to.
395 * @param maxlength Maximum length of the buffer.
396 * @param format Format specifiers.
397 * @param ap Format argument list.
398 * @return Number of bytes actually written, not including the
401 virtual size_t FormatArgs(char *buffer,
408 #if !defined METAMOD_NO_AUTO_NAMESPACE
409 using namespace SourceMM;
415 * 1.1.0 Bumped API to 1:0. The breaking changes occurred in SourceHook and the plugin API.
416 * 1.1.2 Added API call for generating iface names.
417 * 1.2 Added API more helper functions and new SourceHook version.
418 * 1.2.2 Added API for printing to client console (with string formatting).
419 * 1.3 Added new interface search API.
420 * 1.4 Added VSP listener and user message API.
421 * 1.5.0 Added API for getting highest supported version of IServerPluginCallbacks.
422 * 1.6.0 Added API for Orange Box. Broke backwards compatibility.
425 #endif //_INCLUDE_ISMM_API_H