sourcemm/ISmmAPI.h
author Scott Ehlert <ds@alliedmods.net>
Thu Feb 08 09:19:19 2007 +0000 (2007-02-08)
changeset 280 946485e00593
parent 251 3bd7e7008ac3
child 282 7a237e9ea5a1
permissions -rw-r--r--
Renamed convar.h to convar_smm.h in order to avoid potential compiling problems with the order of include directories.
     1 /* ======== SourceMM ========
     2 * Copyright (C) 2004-2006 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"
    35 #define	MMIFACE_PLMANAGER		"IPluginManager"
    36 #define IFACE_MAXNUM			999
    37 
    38 class ISmmAPI
    39 {
    40 public:
    41 	/**
    42 	 * @brief Logs a message through the HL2 log system.
    43 	 * Note: Newlines are appended automatically.
    44 	 *
    45 	 * @param pl			Plugin API pointer (used for tagging message)
    46 	 * @param msg			Formatted string.
    47 	 */
    48 	virtual void LogMsg(ISmmPlugin *pl, const char *msg, ...) =0;
    49 public:
    50 	/**
    51 	 * @brief Returns an interface factory for the HL2 engine.
    52 	 *
    53 	 * @param syn			If syn is true, the synthetic wrapper is returned.  
    54 	 *						If syn is false, the true function is returned.
    55 	 * @return				CreateInterfaceFn function pointer.
    56 	 */
    57 	virtual CreateInterfaceFn engineFactory(bool syn=true) =0;
    58 
    59 	/**
    60 	 * @brief Returns an interface factory for the HL2 physics engine.
    61 	 *
    62 	 * @param syn			If syn is true, the synthetic wrapper is returned.  
    63 	 *						If syn is false, the true function is returned.
    64 	 * @return				CreateInterfaceFn function pointer.
    65 	 */
    66 	virtual CreateInterfaceFn physicsFactory(bool syn=true) =0;
    67 
    68 	/**
    69 	 * @brief Returns an interface factory for the HL2 file system.
    70 	 *
    71 	 * @param syn			If syn is true, the synthetic wrapper is returned.  
    72 	 *						If syn is false, the true function is returned.
    73 	 * @return				CreateInterfaceFn function pointer.
    74 	 */
    75 	virtual CreateInterfaceFn fileSystemFactory(bool syn=true) =0;
    76 
    77 	/**
    78 	 * @brief Returns an interface factory for the GameDLL.
    79 	 *
    80 	 * @param syn			If syn is true, the synthetic wrapper is returned.  
    81 	 *						If syn is false, the true function is returned.
    82 	 * @return				CreateInterfaceFn function pointer.
    83 	 */
    84 	virtual CreateInterfaceFn serverFactory(bool syn=true) =0;
    85 
    86 	/**
    87 	 * @brief Returns a CGlobalVars pointer from the HL2 Engine.
    88 	 *
    89 	 * @return				CGlobalVars pointer.
    90 	 */
    91 	virtual CGlobalVars *pGlobals() =0;
    92 
    93 	/**
    94 	 * @brief Used with SourceHook, sets teh last meta return value.
    95 	 * Note: Do not call this directly, use the Metamod macros.
    96 	 *
    97 	 * @param res			META_RETURN value to set.
    98 	 */
    99 	virtual void SetLastMetaReturn(META_RES res) =0;
   100 
   101 	/**
   102 	 * @brief Used with SourceHook, returns the last meta return value.
   103 	 * Note: This is only valid inside a hook function.
   104 	 *
   105 	 * @return				Last META_RETURN value set by a plugin.
   106 	 */
   107 	virtual META_RES GetLastMetaReturn() =0;
   108 
   109 public:		//Added in 1.00-RC2 (0:0)
   110 	/**
   111 	 * @brief Allows access to Metamod's ConCommandBaseAccessor.
   112 	 *
   113 	 * @return				Returns IConCommandBaseAccessor pointer.
   114 	 */
   115 	virtual IConCommandBaseAccessor *GetCvarBaseAccessor() =0;
   116 
   117 	/**
   118 	 * @brief Registers a ConCommandBase.
   119 	 *
   120 	 * @param plugin		Parent plugin API pointer.
   121 	 * @param pCommand		ConCommandBase to register.
   122 	 * @return				True if successful, false otherwise.  Does not return false yet.
   123 	 */
   124 	virtual bool RegisterConCmdBase(ISmmPlugin *plugin, ConCommandBase *pCommand) =0;
   125 
   126 	/**
   127 	 * @brief Unregisters a ConCommandBase.
   128 	 *
   129 	 * @param plugin		Parent plugin API pointer.
   130 	 * @param pCommand		ConCommandBase to unlink.
   131 	 */
   132 	virtual void UnregisterConCmdBase(ISmmPlugin *plugin, ConCommandBase *pCommand) =0;
   133 	
   134 	/**
   135 	 * @brief Prints an unformatted string to the remote server console.
   136 	 * Note: Newlines are not added automatically.
   137 	 *
   138 	 * @param str			Message string.
   139 	 */
   140 	virtual void ConPrint(const char *str) =0;
   141 
   142 	/**
   143 	 * @brief Prints a formatted message to the remote server console.  
   144 	 * Note: Newlines are not added automatically.
   145 	 *
   146 	 * @param fmt			Formatted message.
   147 	 */
   148 	virtual void ConPrintf(const char *fmt, ...) =0;
   149 
   150 public:		//Added in 1.1.0 (1:0)
   151 	/**
   152 	 * @brief Checks if ConPrint/ConPrintf will mirror to rcon.
   153 	 *
   154 	 * @return				True if remote printing available, false otherwise.
   155 	 */
   156 	virtual bool RemotePrintingAvailable() =0;
   157 
   158 	/**
   159 	 * @brief Returns the Metamod Version numbers as major version and minor (API) version.
   160 	 * Changes to minor version are guaranteed to be backwards compatible.
   161 	 * Changes to major version are not.
   162 	 * 
   163 	 * @param major			Filled with the major API version number.
   164 	 * @param minor			Filled with the minor API version number.
   165 	 * @param plvers		Filled with the current plugin API version number.
   166 	 * @param plmin			Filled with the minimum plugin API version number supported.
   167 	 */
   168 	virtual void GetApiVersions(int &major, int &minor, int &plvers, int &plmin) =0;
   169 	
   170 	/** 
   171 	 * @brief Returns sourcehook API version and implementation version.
   172 	 *
   173 	 * @param shvers		Filled with the SourceHook API version number.
   174 	 * @param shimpl		Filled with the SourceHook implementation number.
   175 	 */
   176 	virtual void GetShVersions(int &shvers, int &shimpl) =0;
   177 	
   178 	/**
   179 	 * @brief Adds a Metamod listener.
   180 	 *
   181 	 * @param plugin		Plugin interface pointer.
   182 	 * @param pListener		Listener interface pointer to add.
   183 	 */
   184 	virtual void AddListener(ISmmPlugin *plugin, IMetamodListener *pListener) =0;
   185 
   186 	/**
   187 	  * @brief Queries the metamod factory
   188 	  *
   189 	  * @param iface		String containing interface name
   190 	  * @param ret			Optional pointer to store return status
   191 	  * @param id			Optional pointer to store id of plugin that overrode interface, 0 if none
   192 	  * @return				Returned pointer
   193 	  */
   194 	virtual void *MetaFactory(const char *iface, int *ret, PluginId *id) =0;
   195 
   196 public:		//Added in 1.1.2 (1:1)
   197 	/**
   198 	 * @brief Given a base interface name, such as ServerGameDLL or ServerGameDLL003, 
   199 	 * reformats the string to increase the number, then returns the new number.
   200 	 * This is the base function to InterfaceSearch() and VInterfaceMatch().
   201 	 * 
   202 	 * @param iface			Input/output interface name.  Must be writable.
   203 	 * @param maxlength		Maximum length of iface buffer.  Must be at least strlen(iface)+4 chars.
   204 	 * @return				The newly incremented iface version number.
   205 	 */
   206 	virtual int FormatIface(char iface[], unsigned int maxlength) =0;
   207 
   208 public:		//Added in 1.2 (1:2)
   209 	/**
   210 	 * @brief Searches for an interface for you.
   211 	 * 
   212 	 * @param fn			InterfaceFactory function.
   213 	 * @param iface			Interface string name.
   214 	 * @param max			Maximum version to look up.
   215 	 * @param ret			Last return code from interface factory function.
   216 	 * @return				Interface pointer, or NULL if not found.
   217 	 */
   218 	virtual void *InterfaceSearch(CreateInterfaceFn fn, const char *iface, int max, int *ret) =0;
   219 
   220 	/**
   221 	 * @brief Returns the base directory of the game/server, equivalent to 
   222 	 *  IVEngineServer::GetGameDir().
   223 	 *
   224 	 * @return				Static pointer to game's basedir.
   225 	 */
   226 	virtual const char *GetBaseDir() =0;
   227 
   228 	/**
   229 	 * @brief Formats a file path to the local OS.  Does not include any base directories.
   230 	 * Note that all slashes and black slashes are reverted to the local OS's expectancy.
   231 	 *
   232 	 * @param buffer		Destination buffer to store path.
   233 	 * @param len			Maximum length of buffer, including null terminator.
   234 	 * @param fmt			Formatted string.
   235 	 */
   236 	virtual void PathFormat(char *buffer, size_t len, const char *fmt, ...) =0;
   237 
   238 public:		// Added in 1.2.2 (1:3)
   239 	/**
   240 	 * @brief Prints text in the specified client's console. Same as IVEngineServer::ClientPrintf 
   241 	 *  except that it allows for string formatting.
   242 	 *
   243 	 * @param client		Client edict pointer.
   244 	 * @param fmt			Formatted string to print to the client.
   245 	 */
   246 	virtual void ClientConPrintf(edict_t *client, const char *fmt, ...) =0;
   247 
   248 public:		// Added in 1.3 (1:4)
   249 	/**
   250 	 * @brief Wrapper around InterfaceSearch().  Assumes no maximum.
   251 	 * This is designed to replace the fact that searches only went upwards.
   252 	 * The "V" is intended to convey that this is for Valve formatted interface strings.
   253 	 *
   254 	 * @param fn			Interface factory function.
   255 	 * @param iface			Interface string.
   256 	 * @param min			Minimum value to search from.  If zero, searching begins from the
   257 	 *                       first available version regardless of the interface.  
   258 	 *                      Note that this can return interfaces EARLIER than the version specified.
   259 	 *                      A value of -1 (default) specifies the string version as the minimum.
   260 	 *                      Any other value specifices the minimum value to search from.
   261 	 * @return				Interface pointer, or NULL if not found.
   262 	 */
   263 	virtual void *VInterfaceMatch(CreateInterfaceFn fn, const char *iface, int min=-1) =0;
   264 };
   265 
   266 
   267 /** Version history
   268  * 1.1.0 bumped API to 1:0.  The breaking changes occured in sourcehook and the plugin API.
   269  * 1.1.2 added API call for generating iface names.
   270  * 1.2   added API more helper functions and new SourceHook version.
   271  * 1.2.2 added API for printing to client console (with string formatting)
   272  * 1.3   added new interface search API
   273  */
   274 
   275 #endif //_INCLUDE_ISMM_API_H