sourcemm/ISmmPluginExt.h
author David Anderson <dvander@alliedmods.net>
Thu Jan 10 19:05:59 2008 +0000 (2008-01-10)
changeset 489 77c6b0da24ec
parent 488 c05bc47b2ecd
child 513 ed5a3e60826a
permissions -rw-r--r--
fixed FormatMessage() misuse and improver error handling
dvander@398
     1
/**
dvander@398
     2
 * vim: set ts=4 :
dvander@398
     3
 * ======================================================
dvander@398
     4
 * Metamod:Source
dvander@398
     5
 * Copyright (C) 2004-2007 AlliedModders LLC and authors.
dvander@398
     6
 * All rights reserved.
dvander@398
     7
 * ======================================================
dvander@398
     8
 *
dvander@398
     9
 * This software is provided 'as-is', without any express or implied warranty.
dvander@398
    10
 * In no event will the authors be held liable for any damages arising from 
dvander@398
    11
 * the use of this software.
dvander@398
    12
 * 
dvander@398
    13
 * Permission is granted to anyone to use this software for any purpose, 
dvander@398
    14
 * including commercial applications, and to alter it and redistribute it 
dvander@398
    15
 * freely, subject to the following restrictions:
dvander@398
    16
 *
dvander@398
    17
 * 1. The origin of this software must not be misrepresented; you must not 
dvander@398
    18
 * claim that you wrote the original software. If you use this software in a 
dvander@398
    19
 * product, an acknowledgment in the product documentation would be 
dvander@398
    20
 * appreciated but is not required.
dvander@398
    21
 * 2. Altered source versions must be plainly marked as such, and must not be
dvander@398
    22
 * misrepresented as being the original software.
dvander@398
    23
 * 3. This notice may not be removed or altered from any source distribution.
dvander@398
    24
 *
dvander@398
    25
 * Version: $Id$
dvander@398
    26
 */
dvander@398
    27
dvander@398
    28
#ifndef _INCLUDE_METAMOD_SOURCE_PLUGIN_EXT_H_
dvander@405
    29
#define _INCLUDE_METAMOD_SOURCE_PLUGIN_EXT_H_
dvander@405
    30
dvander@488
    31
#include <stddef.h>
dvander@488
    32
dvander@487
    33
/**
dvander@487
    34
 * @file ISmmPluginExt.h 	Definitions for extended plugin exposure syntax.
dvander@487
    35
 * @brief Provides an alternate method for loading plugins, without needing to 
dvander@487
    36
 * 		  include the default headers and all their Half-Life baggage.
dvander@487
    37
 */
dvander@487
    38
dvander@405
    39
#define SOURCE_ENGINE_UNKNOWN			0				/**< Could not determine the engine version */
dvander@405
    40
#define SOURCE_ENGINE_ORIGINAL			1				/**< Original Source Engine (used by The Ship) */
dvander@405
    41
#define SOURCE_ENGINE_EPISODEONE		2				/**< Episode 1 Source Engine (second major SDK) */
dvander@405
    42
#define SOURCE_ENGINE_ORANGEBOX			3				/**< Orange Box Source Engine (third major SDK) */
dvander@405
    43
dvander@405
    44
#define METAMOD_PLAPI_VERSION			14				/**< Version of this header file */
dvander@405
    45
#define METAMOD_PLAPI_NAME				"ISmmPlugin"	/**< Name of the plugin interface */
dvander@398
    46
dvander@398
    47
namespace SourceMM
dvander@398
    48
{
dvander@400
    49
	class ISmmPlugin;
dvander@487
    50
	class ISmmAPI;
dvander@487
    51
dvander@487
    52
	/**
dvander@487
    53
	 * @brief Used to uniquely identify plugins.
dvander@487
    54
	 */
dvander@487
    55
	typedef int PluginId;
dvander@487
    56
dvander@487
    57
	#define METAMOD_FAIL_API_V1			7				/**< Minimum API version to detect for V1 */
dvander@487
    58
	#define METAMOD_FAIL_API_V2			14				/**< Minimum API version to detect for V2 */
dvander@487
    59
dvander@487
    60
	/**
dvander@487
    61
	 * Use this to instantiate a plugin that will always fail.
dvander@487
    62
	 * This class definition works against major API versions 1 and 2.
dvander@487
    63
	 */
dvander@487
    64
	class ISmmFailPlugin
dvander@487
    65
	{
dvander@487
    66
	public:
dvander@487
    67
		/**
dvander@487
    68
		 * @brief You must return METAMOD_FAIL_API_V1 or METAMOD_FAIL_API_V2 here, 
dvander@487
    69
		 * depending on which Metamod:Source version you detected.
dvander@487
    70
		 */
dvander@487
    71
		virtual int GetApiVersion() = 0;
dvander@487
    72
dvander@487
    73
		/**
dvander@487
    74
		 * @brief Do not change.
dvander@487
    75
		 */
dvander@487
    76
		virtual ~ISmmFailPlugin()
dvander@487
    77
		{
dvander@487
    78
		}
dvander@487
    79
dvander@487
    80
		/**
dvander@487
    81
		 * @brief Return false here -- fill in the error buffer appropriately.
dvander@487
    82
		 *
dvander@487
    83
		 * Do not ever return true.  If you do, MM:S will crash because the class layout is 
dvander@487
    84
		 * incomplete against ISmmPlugin.
dvander@487
    85
		 * 
dvander@487
    86
		 * @param id			Ignore.
dvander@487
    87
		 * @param ismm			Ignore.
dvander@487
    88
		 * @param error			Error buffer (must be filled).
dvander@487
    89
		 * @param maxlength		Maximum size of error buffer.
dvander@487
    90
		 * @param late			Ignore.
dvander@487
    91
		 * @return				Must return false.
dvander@487
    92
		 */
dvander@487
    93
		virtual bool Load(PluginId id, ISmmAPI *ismm, char *error, size_t maxlength, bool late) =0;
dvander@487
    94
	};
dvander@398
    95
}
dvander@398
    96
dvander@400
    97
typedef SourceMM::ISmmPlugin METAMOD_PLUGIN;
dvander@400
    98
dvander@398
    99
/**
dvander@398
   100
 * @brief Contains version information.
dvander@398
   101
 */
dvander@398
   102
struct MetamodVersionInfo
dvander@398
   103
{
dvander@398
   104
	int api_major;			/**< ISmmAPI major version */
dvander@398
   105
	int api_minor;			/**< ISmmAPI minor version */
dvander@398
   106
	int sh_iface;			/**< SourceHook interface version */
dvander@398
   107
	int sh_impl;			/**< SourceHook implementation version */
dvander@398
   108
	int pl_min;				/**< Plugin API minimum version */
dvander@398
   109
	int pl_max;				/**< Plugin API maximum version */
dvander@398
   110
	int source_engine;		/**< Source Engine version (SOURCE_* constants) */
dvander@398
   111
};
dvander@398
   112
dvander@398
   113
/**
dvander@398
   114
 * @brief Contains information about loading a plugin.
dvander@398
   115
 */
dvander@398
   116
struct MetamodLoaderInfo
dvander@398
   117
{
dvander@398
   118
	const char *pl_file;	/**< File path to the plugin being loaded. */
dvander@398
   119
	const char *pl_path;	/**< Folder path containing the plugin. */
dvander@398
   120
};
dvander@398
   121
dvander@398
   122
/**
dvander@398
   123
 * @brief If a function of this type is exposed as "CreateInterface_MMS", then
dvander@398
   124
 * Metamod:Source will attempt to call this function before calling 
dvander@398
   125
 * CreateInterface.  If this function returns a valid ISmmPlugin pointer, then 
dvander@398
   126
 * CreateInterface will not be called.
dvander@398
   127
 *
dvander@398
   128
 * This is useful for implementing a mini-loader plugin for multiple versions.
dvander@398
   129
 *
dvander@398
   130
 * @param mvi				MetamodVersionInfo structure.
dvander@398
   131
 * @param mli				MetamodLoaderInfo structure.
dvander@398
   132
 * @return					ISmmAPI pointer, or NULL if none.
dvander@398
   133
 */
dvander@400
   134
typedef METAMOD_PLUGIN *(*METAMOD_FN_LOAD)(const MetamodVersionInfo *mvi, 
dvander@400
   135
										   const MetamodLoaderInfo *mli);
dvander@398
   136
dvander@398
   137
/**
dvander@398
   138
 * @brief If a function of this type is exposed as "UnloadInterface_MMS", then
dvander@398
   139
 * Metamod:Source will attempt to call this function after calling 
dvander@398
   140
 * ISmmAPI::Unload(), and before closing the library.  This lets loader plugins 
dvander@398
   141
 * clean up before exiting.
dvander@400
   142
 *
dvander@400
   143
 * Note: This function will be ignored unless CreateInterfce_MMS was exposed.
dvander@400
   144
 * It may be called even if ISmmAPI::Unload() could not be called.
dvander@398
   145
 */
dvander@398
   146
typedef void (*METAMOD_FN_UNLOAD)();
dvander@398
   147
dvander@406
   148
/**
dvander@406
   149
 * @brief Original type of load function.  CreateInterfaceFn from Valve.
dvander@406
   150
 * 
dvander@406
   151
 * Plugins will expose this as "CreateInterface".
dvander@406
   152
 */
dvander@406
   153
typedef void *(*METAMOD_FN_ORIG_LOAD)(const char *, int *);
dvander@406
   154
dvander@398
   155
#endif //INCLUDE_METAMOD_SOURCE_PLUGIN_EXT_H_
dvander@398
   156