added yet another interface searching function

commented ISmmAPI for doxygen

--HG--
extra : convert_revision : svn%3Ac2935e3e-5518-0410-8daf-afa5dab7d4e3/trunk%40275

sourcemm/CSmmAPI.cpp

@@ -357,6 +357,40 @@ void *CSmmAPI::InterfaceSearch(CreateInterfaceFn fn, const char *iface, int max,
 	return pf;
 }
 
+void *CSmmAPI::VInterfaceMatch(CreateInterfaceFn fn, const char *iface, bool chop)
+{
+	char buffer[256];	/* assume no interface will go beyond this */
+	int len = static_cast<int>(strlen(iface));
+
+	if (len > sizeof(buffer) - 4)
+	{
+		return NULL;
+	}
+
+	strcpy(buffer, iface);
+
+	if (chop)
+	{
+		char *ptr = &buffer[len-1];
+		int digits = 0;
+		while (isdigit(*ptr) && digits <=3)
+		{
+			*ptr = '\0';
+			digits++;
+			ptr--;
+		}
+		if (digits != 3)
+		{
+			/* for now, assume this is an error */
+			strcpy(buffer, iface);
+		}
+	}
+
+	strcat(buffer, "001");
+
+	return InterfaceSearch(fn, buffer, IFACE_MAXNUM, NULL);
+}
+
 const char *CSmmAPI::GetBaseDir()
 {
 	return g_ModPath.c_str();

sourcemm/CSmmAPI.h

@@ -55,6 +55,7 @@ namespace SourceMM
 		virtual const char *GetBaseDir();
 		virtual void PathFormat(char *buffer, size_t len, const char *fmt, ...);
 		void ClientConPrintf(edict_t *client, const char *fmt, ...);
+		void *VInterfaceMatch(CreateInterfaceFn fn, const char *iface, bool chop=true);
 	public:
 		bool CacheCmds();
 	private:

sourcemm/ISmmAPI.h

@@ -33,77 +33,232 @@ class ISmmPluginManager;
 class ISmmPlugin;
 
 #define	MMIFACE_SOURCEHOOK		"ISourceHook"
-#define	MMIFACE_PLMANAGER		"IPluginManager"	
+#define	MMIFACE_PLMANAGER		"IPluginManager"
+#define IFACE_MAXNUM			999
 
 class ISmmAPI
 {
 public:
+	/**
+	 * @brief Logs a message through the HL2 log system.
+	 * Note: Newlines are appended automatically.
+	 *
+	 * @param pl			Plugin API pointer (used for tagging message)
+	 * @param msg			Formatted string.
+	 */
 	virtual void LogMsg(ISmmPlugin *pl, const char *msg, ...) =0;
 public:
+	/**
+	 * @brief Returns an interface factory for the HL2 engine.
+	 *
+	 * @param syn			If syn is true, the synthetic wrapper is returned.  
+	 *						If syn is false, the true function is returned.
+	 * @return				CreateInterfaceFn function pointer.
+	 */
 	virtual CreateInterfaceFn engineFactory(bool syn=true) =0;
+
+	/**
+	 * @brief Returns an interface factory for the HL2 physics engine.
+	 *
+	 * @param syn			If syn is true, the synthetic wrapper is returned.  
+	 *						If syn is false, the true function is returned.
+	 * @return				CreateInterfaceFn function pointer.
+	 */
 	virtual CreateInterfaceFn physicsFactory(bool syn=true) =0;
+
+	/**
+	 * @brief Returns an interface factory for the HL2 file system.
+	 *
+	 * @param syn			If syn is true, the synthetic wrapper is returned.  
+	 *						If syn is false, the true function is returned.
+	 * @return				CreateInterfaceFn function pointer.
+	 */
 	virtual CreateInterfaceFn fileSystemFactory(bool syn=true) =0;
+
+	/**
+	 * @brief Returns an interface factory for the GameDLL.
+	 *
+	 * @param syn			If syn is true, the synthetic wrapper is returned.  
+	 *						If syn is false, the true function is returned.
+	 * @return				CreateInterfaceFn function pointer.
+	 */
 	virtual CreateInterfaceFn serverFactory(bool syn=true) =0;
+
+	/**
+	 * @brief Returns a CGlobalVars pointer from the HL2 Engine.
+	 *
+	 * @return				CGlobalVars pointer.
+	 */
 	virtual CGlobalVars *pGlobals() =0;
+
+	/**
+	 * @brief Used with SourceHook, sets teh last meta return value.
+	 * Note: Do not call this directly, use the Metamod macros.
+	 *
+	 * @param res			META_RETURN value to set.
+	 */
 	virtual void SetLastMetaReturn(META_RES res) =0;
+
+	/**
+	 * @brief Used with SourceHook, returns the last meta return value.
+	 * Note: This is only valid inside a hook function.
+	 *
+	 * @return				Last META_RETURN value set by a plugin.
+	 */
 	virtual META_RES GetLastMetaReturn() =0;
+
 public:		//Added in 1.00-RC2 (0:0)
-	//solves concommand problems by keeping track for loading/unloading
+	/**
+	 * @brief Allows access to Metamod's ConCommandBaseAccessor.
+	 *
+	 * @return				Returns IConCommandBaseAccessor pointer.
+	 */
 	virtual IConCommandBaseAccessor *GetCvarBaseAccessor() =0;
+
+	/**
+	 * @brief Registers a ConCommandBase.
+	 *
+	 * @param plugin		Parent plugin API pointer.
+	 * @param pCommand		ConCommandBase to register.
+	 * @return				True if successful, false otherwise.  Does not return false yet.
+	 */
 	virtual bool RegisterConCmdBase(ISmmPlugin *plugin, ConCommandBase *pCommand) =0;
+
+	/**
+	 * @brief Unregisters a ConCommandBase.
+	 *
+	 * @param plugin		Parent plugin API pointer.
+	 * @param pCommand		ConCommandBase to unlink.
+	 */
 	virtual void UnregisterConCmdBase(ISmmPlugin *plugin, ConCommandBase *pCommand) =0;
-	//attempt fix at valve not exporting rcon printing
-	//these do not add newlines
-	virtual void ConPrint(const char *fmt) =0;
+	
+	/**
+	 * @brief Prints an unformatted string to the remote server console.
+	 * Note: Newlines are not added automatically.
+	 *
+	 * @param str			Message string.
+	 */
+	virtual void ConPrint(const char *str) =0;
+
+	/**
+	 * @brief Prints a formatted message to the remote server console.  
+	 * Note: Newlines are not added automatically.
+	 *
+	 * @param fmt			Formatted message.
+	 */
 	virtual void ConPrintf(const char *fmt, ...) =0;
+
 public:		//Added in 1.1.0 (1:0)
-	//added by request.  Checks if ConPrint/ConPrintf will mirror to rcon.
+	/**
+	 * @brief Checks if ConPrint/ConPrintf will mirror to rcon.
+	 *
+	 * @return				True if remote printing available, false otherwise.
+	 */
 	virtual bool RemotePrintingAvailable() =0;
-	//Returns the Metamod Version numbers as major version and minor (API) version.
-	//changes to minor version are guaranteed to be backwards compatible.
-	//changes to major version are not.
-	//Also returns current plugin version and minimum plugin version
+
+	/**
+	 * @brief Returns the Metamod Version numbers as major version and minor (API) version.
+	 * Changes to minor version are guaranteed to be backwards compatible.
+	 * Changes to major version are not.
+	 * 
+	 * @param major			Filled with the major API version number.
+	 * @param minor			Filled with the minor API version number.
+	 * @param plvers		Filled with the current plugin API version number.
+	 * @param plmin			Filled with the minimum plugin API version number supported.
+	 */
 	virtual void GetApiVersions(int &major, int &minor, int &plvers, int &plmin) =0;
-	//Returns sourcehook API version and implementation version
+	
+	/** 
+	 * @brief Returns sourcehook API version and implementation version.
+	 *
+	 * @param shvers		Filled with the SourceHook API version number.
+	 * @param shimpl		Filled with the SourceHook implementation number.
+	 */
 	virtual void GetShVersions(int &shvers, int &shimpl) =0;
-	//Binds an event listener to your plugin
+	
+	/**
+	 * @brief Adds a Metamod listener.
+	 *
+	 * @param plugin		Plugin interface pointer.
+	 * @param pListener		Listener interface pointer to add.
+	 */
 	virtual void AddListener(ISmmPlugin *plugin, IMetamodListener *pListener) =0;
+
 	/**
 	  * @brief Queries the metamod factory
 	  *
-	  * @param iface	String containing interface name
-	  * @param ret		Optional pointer to store return status
-	  * @param id		Optional pointer to store id of plugin that overrode interface, 0 if none
-	  * @return			Returned pointer
+	  * @param iface		String containing interface name
+	  * @param ret			Optional pointer to store return status
+	  * @param id			Optional pointer to store id of plugin that overrode interface, 0 if none
+	  * @return				Returned pointer
 	  */
 	virtual void *MetaFactory(const char *iface, int *ret, PluginId *id) =0;
+
 public:		//Added in 1.1.2 (1:1)
 	/**
 	 * @brief Given a base interface name, such as ServerGameDLL or ServerGameDLL003, 
 	 * reformats the string to increase the number, then returns the new number.
+	 * This is the base function to InterfaceSearch() and VInterfaceMatch().
+	 * 
+	 * @param iface			Input/output interface name.  Must be writable.
+	 * @param maxlength		Maximum length of iface buffer.  Must be at least strlen(iface)+4 chars.
+	 * @return				The newly incremented iface version number.
 	 */
 	virtual int FormatIface(char iface[], unsigned int maxlength) =0;
+
 public:		//Added in 1.2 (1:2)
 	/**
 	 * @brief Searches for an interface for you.
+	 * 
+	 * @param fn			InterfaceFactory function.
+	 * @param iface			Interface string name.
+	 * @param max			Maximum version to look up.
+	 * @param ret			Last return code from interface factory function.
+	 * @return				Interface pointer, or NULL if not found.
 	 */
 	virtual void *InterfaceSearch(CreateInterfaceFn fn, const char *iface, int max, int *ret) =0;
 
 	/**
-	 * @brief Returns the base directory of the game/server, equivalent to IVEngineServer::GetGameDir
+	 * @brief Returns the base directory of the game/server, equivalent to 
+	 *  IVEngineServer::GetGameDir().
+	 *
+	 * @return				Static pointer to game's basedir.
 	 */
 	virtual const char *GetBaseDir() =0;
 
 	/**
 	 * @brief Formats a file path to the local OS.  Does not include any base directories.
+	 * Note that all slashes and black slashes are reverted to the local OS's expectancy.
+	 *
+	 * @param buffer		Destination buffer to store path.
+	 * @param len			Maximum length of buffer, including null terminator.
+	 * @param fmt			Formatted string.
 	 */
 	virtual void PathFormat(char *buffer, size_t len, const char *fmt, ...) =0;
+
 public:		// Added in 1.2.2 (1:3)
 	/**
 	 * @brief Prints text in the specified client's console. Same as IVEngineServer::ClientPrintf 
 	 *  except that it allows for string formatting.
+	 *
+	 * @param client		Client edict pointer.
+	 * @param fmt			Formatted string to print to the client.
 	 */
 	virtual void ClientConPrintf(edict_t *client, const char *fmt, ...) =0;
+
+public:		// Added in 1.3 (1:4)
+	/**
+	 * @brief Wrapper around InterfaceSearch().  Assumes no maximum.
+	 * This is designed to replace the fact that searches only went upwards.
+	 * The "V" is intended to convey that this is for Valve formatted interface strings.
+	 *
+	 * @param fn			Interface factory function.
+	 * @param iface			Interface string.
+	 * @param chop			If true, chops an interface version number off and searches 
+	 *                      from the beginning.
+	 * @return				Interface pointer, or NULL if not found.
+	 */
+	virtual void *VInterfaceMatch(CreateInterfaceFn fn, const char *iface, bool chop=true) =0;
 };
 
 
@@ -112,6 +267,7 @@ public:		// Added in 1.2.2 (1:3)
  * 1.1.2 added API call for generating iface names.
  * 1.2   added API more helper functions and new SourceHook version.
  * 1.2.2 added API for printing to client console (with string formatting)
+ * 1.3   added new interface search API
  */
 
 #endif //_INCLUDE_ISMM_API_H

sourcemm/sourcemm.h

@@ -38,7 +38,7 @@
 #define		SOURCEMM_DATE		__DATE__
 #define		SM_MAJOR_VERSION	1		//never need to increase this
 #define		SM_VERS_API_MAJOR	1		//increase this on a breaking change
-#define		SM_VERS_API_MINOR	3		//increase this on a non-breaking API change
+#define		SM_VERS_API_MINOR	4		//increase this on a non-breaking API change
 #define		SM_VERS_RELEASE		4		//increase this on a bug-fix release.
 
 //We need a good CServerGameDLL version to work properly.  We support these inclusively.