sourcemm/ISmmAPI.h
author David Anderson <dvander@alliedmods.net>
Thu Sep 27 18:12:20 2007 +0000 (2007-09-27)
branchsourcemm-1.6.0
changeset 355 8f221ded1568
parent 352 7d8c71df909f
child 359 9b3c625f3a83
permissions -rw-r--r--
added svn:keywords property
     1 /* ======== SourceMM ========
     2 * Copyright (C) 2004-2007 Metamod:Source Development Team
     3 * No warranties of any kind
     4 *
     5 * License: zlib/libpng
     6 *
     7 * Author(s): David "BAILOPAN" Anderson
     8 * ============================
     9 */
    10 
    11 #ifndef _INCLUDE_ISMM_API_H
    12 #define _INCLUDE_ISMM_API_H
    13 
    14 /**
    15  * @brief External API interface
    16  * @file ISmmAPI.h
    17  */
    18 
    19 #include <interface.h>
    20 #include <eiface.h>
    21 #include <sourcehook/sourcehook.h>
    22 #include "IPluginManager.h"
    23 
    24 #if defined __GNUC__
    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
    28 #endif //__GNUC__
    29 
    30 class IMetamodListener;
    31 class ISmmPluginManager;
    32 class ISmmPlugin;
    33 
    34 #define	MMIFACE_SOURCEHOOK		"ISourceHook"			/**< ISourceHook Pointer */
    35 #define	MMIFACE_PLMANAGER		"IPluginManager"		/**< SourceMM Plugin Functions */
    36 #define IFACE_MAXNUM			999						/**< Maximum interface version */
    37 
    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) */
    42 
    43 class ISmmAPI
    44 {
    45 public:
    46 	/**
    47 	 * @brief Logs a message through the HL2 log system.
    48 	 * Note: Newlines are appended automatically.
    49 	 *
    50 	 * @param pl			Plugin API pointer (used for tagging message)
    51 	 * @param msg			Formatted string.
    52 	 */
    53 	virtual void LogMsg(ISmmPlugin *pl, const char *msg, ...) =0;
    54 public:
    55 	/**
    56 	 * @brief Returns an interface factory for the HL2 engine.
    57 	 *
    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.
    61 	 */
    62 	virtual CreateInterfaceFn engineFactory(bool syn=true) =0;
    63 
    64 	/**
    65 	 * @brief Returns an interface factory for the HL2 physics engine.
    66 	 *
    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.
    70 	 */
    71 	virtual CreateInterfaceFn physicsFactory(bool syn=true) =0;
    72 
    73 	/**
    74 	 * @brief Returns an interface factory for the HL2 file system.
    75 	 *
    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.
    79 	 */
    80 	virtual CreateInterfaceFn fileSystemFactory(bool syn=true) =0;
    81 
    82 	/**
    83 	 * @brief Returns an interface factory for the GameDLL.
    84 	 *
    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.
    88 	 */
    89 	virtual CreateInterfaceFn serverFactory(bool syn=true) =0;
    90 
    91 	/**
    92 	 * @brief Returns a CGlobalVars pointer from the HL2 Engine.
    93 	 *
    94 	 * @return				CGlobalVars pointer.
    95 	 */
    96 	virtual CGlobalVars *pGlobals() =0;
    97 
    98 	/**
    99 	 * @brief Used with SourceHook, sets teh last meta return value.
   100 	 * Note: Do not call this directly, use the Metamod macros.
   101 	 *
   102 	 * @param res			META_RETURN value to set.
   103 	 */
   104 	virtual void SetLastMetaReturn(META_RES res) =0;
   105 
   106 	/**
   107 	 * @brief Used with SourceHook, returns the last meta return value.
   108 	 * Note: This is only valid inside a hook function.
   109 	 *
   110 	 * @return				Last META_RETURN value set by a plugin.
   111 	 */
   112 	virtual META_RES GetLastMetaReturn() =0;
   113 
   114 public:		// Added in 1.00-RC2 (0:0)
   115 	/**
   116 	 * @brief Allows access to Metamod's ConCommandBaseAccessor.
   117 	 *
   118 	 * @return				Returns IConCommandBaseAccessor pointer.
   119 	 */
   120 	virtual IConCommandBaseAccessor *GetCvarBaseAccessor() =0;
   121 
   122 	/**
   123 	 * @brief Registers a ConCommandBase.
   124 	 *
   125 	 * @param plugin		Parent plugin API pointer.
   126 	 * @param pCommand		ConCommandBase to register.
   127 	 * @return				True if successful, false otherwise.
   128 	 */
   129 	virtual bool RegisterConCmdBase(ISmmPlugin *plugin, ConCommandBase *pCommand) =0;
   130 
   131 	/**
   132 	 * @brief Unregisters a ConCommandBase.
   133 	 *
   134 	 * @param plugin		Parent plugin API pointer.
   135 	 * @param pCommand		ConCommandBase to unlink.
   136 	 */
   137 	virtual void UnregisterConCmdBase(ISmmPlugin *plugin, ConCommandBase *pCommand) =0;
   138 	
   139 	/**
   140 	 * @brief Prints an unformatted string to the remote server console.
   141 	 * 
   142 	 * Note: Newlines are not added automatically.
   143 	 *
   144 	 * @param str			Message string.
   145 	 */
   146 	virtual void ConPrint(const char *str) =0;
   147 
   148 	/**
   149 	 * @brief Prints a formatted message to the remote server console.  
   150 	 * 
   151 	 * Note: Newlines are not added automatically.
   152 	 *
   153 	 * @param fmt			Formatted message.
   154 	 */
   155 	virtual void ConPrintf(const char *fmt, ...) =0;
   156 
   157 public:		// Added in 1.1.0 (1:0)
   158 	/**
   159 	 * @brief Checks if ConPrint/ConPrintf will mirror to rcon.
   160 	 *
   161 	 * @return				True if remote printing available, false otherwise.
   162 	 */
   163 	virtual bool RemotePrintingAvailable() =0;
   164 
   165 	/**
   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.
   169 	 * 
   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.
   174 	 */
   175 	virtual void GetApiVersions(int &major, int &minor, int &plvers, int &plmin) =0;
   176 	
   177 	/** 
   178 	 * @brief Returns sourcehook API version and implementation version.
   179 	 *
   180 	 * @param shvers		Filled with the SourceHook API version number.
   181 	 * @param shimpl		Filled with the SourceHook implementation number.
   182 	 */
   183 	virtual void GetShVersions(int &shvers, int &shimpl) =0;
   184 	
   185 	/**
   186 	 * @brief Adds a Metamod listener.
   187 	 *
   188 	 * @param plugin		Plugin interface pointer.
   189 	 * @param pListener		Listener interface pointer to add.
   190 	 */
   191 	virtual void AddListener(ISmmPlugin *plugin, IMetamodListener *pListener) =0;
   192 
   193 	/**
   194 	  * @brief Queries the metamod factory
   195 	  *
   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
   200 	  */
   201 	virtual void *MetaFactory(const char *iface, int *ret, PluginId *id) =0;
   202 
   203 public:		// Added in 1.1.2 (1:1)
   204 	/**
   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().
   208 	 * 
   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.
   212 	 */
   213 	virtual int FormatIface(char iface[], unsigned int maxlength) =0;
   214 
   215 public:		// Added in 1.2 (1:2)
   216 	/**
   217 	 * @brief Searches for an interface, eliminating the need to loop through FormatIface().
   218 	 * 
   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.
   224 	 */
   225 	virtual void *InterfaceSearch(CreateInterfaceFn fn, const char *iface, int max, int *ret) =0;
   226 
   227 	/**
   228 	 * @brief Returns the base directory of the game/server, equivalent to 
   229 	 * IVEngineServer::GetGameDir(), except the path is absolute.
   230 	 *
   231 	 * @return				Static pointer to game's absolute basedir.
   232 	 */
   233 	virtual const char *GetBaseDir() =0;
   234 
   235 	/**
   236 	 * @brief Formats a file path to the local OS.  
   237 	 *
   238 	 * Does not include any base directories.  Note that all slashes and black 
   239 	 * slashes are reverted to the local OS's expectancy.
   240 	 *
   241 	 * @param buffer		Destination buffer to store path.
   242 	 * @param len			Maximum length of buffer, including null terminator.
   243 	 * @param fmt			Formatted string.
   244 	 */
   245 	virtual void PathFormat(char *buffer, size_t len, const char *fmt, ...) =0;
   246 
   247 public:		// Added in 1.2.2 (1:3)
   248 	/**
   249 	 * @brief Prints text in the specified client's console. Same as 
   250 	 * IVEngineServer::ClientPrintf except that it allows for string formatting.
   251 	 *
   252 	 * @param client		Client edict pointer.
   253 	 * @param fmt			Formatted string to print to the client.
   254 	 */
   255 	virtual void ClientConPrintf(edict_t *client, const char *fmt, ...) =0;
   256 
   257 public:		// Added in 1.3 (1:4)
   258 	/**
   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.
   262 	 *
   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.
   273 	 */
   274 	virtual void *VInterfaceMatch(CreateInterfaceFn fn, const char *iface, int min=-1) =0;
   275 
   276 public:		// Added in 1.4 (1:5)
   277 	/**
   278 	 * @brief Tells SourceMM to add VSP hooking capability to plugins.  
   279 	 *
   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 
   286 	 * yet received it.
   287 	 */
   288 	virtual void EnableVSPListener() =0;
   289 
   290 	/**
   291 	 * @brief Returns the interface version of the GameDLL's IServerGameDLL 
   292 	 * implementation.
   293 	 *
   294 	 * @return				Interface version of the loaded IServerGameDLL.
   295 	 */
   296 	virtual int GetGameDLLVersion() =0;
   297 
   298 	/**
   299 	 * @brief Returns the number of user messages in the GameDLL.
   300 	 *
   301 	 * @return				Number of user messages, or -1 if SourceMM has 
   302 	 *						failed to get user message list.
   303 	 */
   304 	virtual int GetUserMessageCount() =0;
   305 
   306 	/**
   307 	 * @brief Returns the index of the specified user message.
   308 	 *
   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.
   312 	 */
   313 	virtual int FindUserMessage(const char *name, int *size=NULL) =0;
   314 
   315 	/**
   316 	 * @brief Returns the name of the specified user message.
   317 	 *
   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.
   321 	 */
   322 	virtual const char *GetUserMessage(int index, int *size=NULL) =0;
   323 
   324 public:		// Added in 1.5.0 (1:6)
   325 	/**
   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.
   329 	 *
   330 	 * @return				Highest interface version of IServerPluginCallbacks.
   331 	 *						Returns 0 if SourceMM's VSP listener isn't currently 
   332 	 *						enabled.
   333 	 */
   334 	virtual int GetVSPVersion() =0;
   335 
   336 public:		// Added in 1.6.0 (1:7)
   337 	/**
   338 	 * @brief Returns the engine interface that MM:S is using as a backend.
   339 	 *
   340 	 * The values will be one of the SOURCE_ENGINE_* constants from the top
   341 	 * of this file.
   342 	 *
   343 	 * @return				A SOURCE_ENGINE_* constant value.
   344 	 */
   345 	virtual int GetSourceEngineBuild() =0;
   346 };
   347 
   348 
   349 /** 
   350  * Version History
   351  *
   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.
   360  */
   361 
   362 #endif //_INCLUDE_ISMM_API_H
   363