1 /* ======== SourceMM ========
2 * Copyright (C) 2004-2007 Metamod:Source Development Team
3 * No warranties of any kind
7 * Author(s): David "BAILOPAN" Anderson
8 * ============================
11 #ifndef _INCLUDE_ISMM_API_H
12 #define _INCLUDE_ISMM_API_H
15 * @brief External API interface
19 #include <interface.h>
21 #include <sourcehook/sourcehook.h>
22 #include "IPluginManager.h"
25 #if ((__GNUC__ == 3) && (__GNUC_MINOR__ < 4)) || (__GNUC__ < 3)
26 #error "You must compile with at least GCC 3.4! If you know what you are doing, you can remove this message."
27 #endif //version check
30 class IMetamodListener;
31 class ISmmPluginManager;
34 #define MMIFACE_SOURCEHOOK "ISourceHook" /**< ISourceHook Pointer */
35 #define MMIFACE_PLMANAGER "IPluginManager" /**< SourceMM Plugin Functions */
36 #define IFACE_MAXNUM 999 /**< Maximum interface version */
38 #define SOURCE_ENGINE_UNKNOWN 0 /**< Could not determine the engine version */
39 #define SOURCE_ENGINE_ORIGINAL 1 /**< Original Source Engine (used by The Ship) */
40 #define SOURCE_ENGINE_EPISODEONE 2 /**< Episode 1 Source Engine (second major SDK) */
41 #define SOURCE_ENGINE_ORANGEBOX 3 /**< Orange Box Source Engine (third major SDK) */
47 * @brief Logs a message through the HL2 log system.
48 * Note: Newlines are appended automatically.
50 * @param pl Plugin API pointer (used for tagging message)
51 * @param msg Formatted string.
53 virtual void LogMsg(ISmmPlugin *pl, const char *msg, ...) =0;
56 * @brief Returns an interface factory for the HL2 engine.
58 * @param syn If syn is true, the synthetic wrapper is returned.
59 * If syn is false, the true function is returned.
60 * @return CreateInterfaceFn function pointer.
62 virtual CreateInterfaceFn engineFactory(bool syn=true) =0;
65 * @brief Returns an interface factory for the HL2 physics engine.
67 * @param syn If syn is true, the synthetic wrapper is returned.
68 * If syn is false, the true function is returned.
69 * @return CreateInterfaceFn function pointer.
71 virtual CreateInterfaceFn physicsFactory(bool syn=true) =0;
74 * @brief Returns an interface factory for the HL2 file system.
76 * @param syn If syn is true, the synthetic wrapper is returned.
77 * If syn is false, the true function is returned.
78 * @return CreateInterfaceFn function pointer.
80 virtual CreateInterfaceFn fileSystemFactory(bool syn=true) =0;
83 * @brief Returns an interface factory for the GameDLL.
85 * @param syn If syn is true, the synthetic wrapper is returned.
86 * If syn is false, the true function is returned.
87 * @return CreateInterfaceFn function pointer.
89 virtual CreateInterfaceFn serverFactory(bool syn=true) =0;
92 * @brief Returns a CGlobalVars pointer from the HL2 Engine.
94 * @return CGlobalVars pointer.
96 virtual CGlobalVars *pGlobals() =0;
99 * @brief Used with SourceHook, sets teh last meta return value.
100 * Note: Do not call this directly, use the Metamod macros.
102 * @param res META_RETURN value to set.
104 virtual void SetLastMetaReturn(META_RES res) =0;
107 * @brief Used with SourceHook, returns the last meta return value.
108 * Note: This is only valid inside a hook function.
110 * @return Last META_RETURN value set by a plugin.
112 virtual META_RES GetLastMetaReturn() =0;
114 public: // Added in 1.00-RC2 (0:0)
116 * @brief Allows access to Metamod's ConCommandBaseAccessor.
118 * @return Returns IConCommandBaseAccessor pointer.
120 virtual IConCommandBaseAccessor *GetCvarBaseAccessor() =0;
123 * @brief Registers a ConCommandBase.
125 * @param plugin Parent plugin API pointer.
126 * @param pCommand ConCommandBase to register.
127 * @return True if successful, false otherwise.
129 virtual bool RegisterConCmdBase(ISmmPlugin *plugin, ConCommandBase *pCommand) =0;
132 * @brief Unregisters a ConCommandBase.
134 * @param plugin Parent plugin API pointer.
135 * @param pCommand ConCommandBase to unlink.
137 virtual void UnregisterConCmdBase(ISmmPlugin *plugin, ConCommandBase *pCommand) =0;
140 * @brief Prints an unformatted string to the remote server console.
142 * Note: Newlines are not added automatically.
144 * @param str Message string.
146 virtual void ConPrint(const char *str) =0;
149 * @brief Prints a formatted message to the remote server console.
151 * Note: Newlines are not added automatically.
153 * @param fmt Formatted message.
155 virtual void ConPrintf(const char *fmt, ...) =0;
157 public: // Added in 1.1.0 (1:0)
159 * @brief Checks if ConPrint/ConPrintf will mirror to rcon.
161 * @return True if remote printing available, false otherwise.
163 virtual bool RemotePrintingAvailable() =0;
166 * @brief Returns the Metamod Version numbers as major version and minor (API) version.
167 * Changes to minor version are guaranteed to be backwards compatible.
168 * Changes to major version are not.
170 * @param major Filled with the major API version number.
171 * @param minor Filled with the minor API version number.
172 * @param plvers Filled with the current plugin API version number.
173 * @param plmin Filled with the minimum plugin API version number supported.
175 virtual void GetApiVersions(int &major, int &minor, int &plvers, int &plmin) =0;
178 * @brief Returns sourcehook API version and implementation version.
180 * @param shvers Filled with the SourceHook API version number.
181 * @param shimpl Filled with the SourceHook implementation number.
183 virtual void GetShVersions(int &shvers, int &shimpl) =0;
186 * @brief Adds a Metamod listener.
188 * @param plugin Plugin interface pointer.
189 * @param pListener Listener interface pointer to add.
191 virtual void AddListener(ISmmPlugin *plugin, IMetamodListener *pListener) =0;
194 * @brief Queries the metamod factory
196 * @param iface String containing interface name
197 * @param ret Optional pointer to store return status
198 * @param id Optional pointer to store id of plugin that overrode interface, 0 if none
199 * @return Returned pointer
201 virtual void *MetaFactory(const char *iface, int *ret, PluginId *id) =0;
203 public: // Added in 1.1.2 (1:1)
205 * @brief Given a base interface name, such as ServerGameDLL or ServerGameDLL003,
206 * reformats the string to increase the number, then returns the new number.
207 * This is the base function to InterfaceSearch() and VInterfaceMatch().
209 * @param iface Input/output interface name. Must be writable.
210 * @param maxlength Maximum length of iface buffer. Must be at least strlen(iface)+4 chars.
211 * @return The newly incremented iface version number.
213 virtual int FormatIface(char iface[], unsigned int maxlength) =0;
215 public: // Added in 1.2 (1:2)
217 * @brief Searches for an interface, eliminating the need to loop through FormatIface().
219 * @param fn InterfaceFactory function.
220 * @param iface Interface string name.
221 * @param max Maximum version to look up.
222 * @param ret Last return code from interface factory function.
223 * @return Interface pointer, or NULL if not found.
225 virtual void *InterfaceSearch(CreateInterfaceFn fn, const char *iface, int max, int *ret) =0;
228 * @brief Returns the base directory of the game/server, equivalent to
229 * IVEngineServer::GetGameDir(), except the path is absolute.
231 * @return Static pointer to game's absolute basedir.
233 virtual const char *GetBaseDir() =0;
236 * @brief Formats a file path to the local OS.
238 * Does not include any base directories. Note that all slashes and black
239 * slashes are reverted to the local OS's expectancy.
241 * @param buffer Destination buffer to store path.
242 * @param len Maximum length of buffer, including null terminator.
243 * @param fmt Formatted string.
245 virtual void PathFormat(char *buffer, size_t len, const char *fmt, ...) =0;
247 public: // Added in 1.2.2 (1:3)
249 * @brief Prints text in the specified client's console. Same as
250 * IVEngineServer::ClientPrintf except that it allows for string formatting.
252 * @param client Client edict pointer.
253 * @param fmt Formatted string to print to the client.
255 virtual void ClientConPrintf(edict_t *client, const char *fmt, ...) =0;
257 public: // Added in 1.3 (1:4)
259 * @brief Wrapper around InterfaceSearch(). Assumes no maximum.
260 * This is designed to replace the fact that searches only went upwards.
261 * The "V" is intended to convey that this is for Valve formatted interface strings.
263 * @param fn Interface factory function.
264 * @param iface Interface string.
265 * @param min Minimum value to search from. If zero, searching
266 * begins from the first available version regardless
267 * of the interface. Note that this can return
268 * interfaces EARLIER than the version specified. A
269 * value of -1 (default) specifies the string version
270 * as the minimum. Any other value specifices the
271 * minimum value to search from.
272 * @return Interface pointer, or NULL if not found.
274 virtual void *VInterfaceMatch(CreateInterfaceFn fn, const char *iface, int min=-1) =0;
276 public: // Added in 1.4 (1:5)
278 * @brief Tells SourceMM to add VSP hooking capability to plugins.
280 * Since this potentially uses more resources than it would otherwise,
281 * plugins have to explicitly enable the feature. Whether requested or
282 * not, if it is enabled, all plugins will get a pointer to the VSP
283 * listener through IMetamodListener. This will not be called more than
284 * once for a given plugin; if it is requested more than once, each
285 * successive call will only give the pointer to plugins which have not
288 virtual void EnableVSPListener() =0;
291 * @brief Returns the interface version of the GameDLL's IServerGameDLL
294 * @return Interface version of the loaded IServerGameDLL.
296 virtual int GetGameDLLVersion() =0;
299 * @brief Returns the number of user messages in the GameDLL.
301 * @return Number of user messages, or -1 if SourceMM has
302 * failed to get user message list.
304 virtual int GetUserMessageCount() =0;
307 * @brief Returns the index of the specified user message.
309 * @param name User message name.
310 * @param size Optional pointer to store size of user message.
311 * @return Message index, or -1 on failure.
313 virtual int FindUserMessage(const char *name, int *size=NULL) =0;
316 * @brief Returns the name of the specified user message.
318 * @param index User message index.
319 * @param size Optional pointer to store size of user message.
320 * @return Message name, or NULL on failure.
322 virtual const char *GetUserMessage(int index, int *size=NULL) =0;
324 public: // Added in 1.5.0 (1:6)
326 * @brief Returns the highest interface version of IServerPluginCallbacks
327 * that the engine supports. This is useful for games that run on older
328 * versions of the Source engine, such as The Ship.
330 * @return Highest interface version of IServerPluginCallbacks.
331 * Returns 0 if SourceMM's VSP listener isn't currently
334 virtual int GetVSPVersion() =0;
336 public: // Added in 1.6.0 (1:7)
338 * @brief Returns the engine interface that MM:S is using as a backend.
340 * The values will be one of the SOURCE_ENGINE_* constants from the top
343 * @return A SOURCE_ENGINE_* constant value.
345 virtual int GetSourceEngineBuild() =0;
352 * 1.1.0 Bumped API to 1:0. The breaking changes occurred in SourceHook and the plugin API.
353 * 1.1.2 Added API call for generating iface names.
354 * 1.2 Added API more helper functions and new SourceHook version.
355 * 1.2.2 Added API for printing to client console (with string formatting).
356 * 1.3 Added new interface search API.
357 * 1.4 Added VSP listener and user message API.
358 * 1.5.0 Added API for getting highest supported version of IServerPluginCallbacks.
359 * 1.6.0 Added API for Orange Box.
362 #endif //_INCLUDE_ISMM_API_H