sourcehook/sourcehook_impl.h
author David Anderson <dvander@alliedmods.net>
Tue Oct 16 20:03:12 2007 +0000 (2007-10-16)
changeset 429 cadecde4b802
parent 418 109309ff6350
child 523 6f1630519b81
permissions -rw-r--r--
removed 1.6.0 branch
pavolmarko@1
     1
/* ======== SourceHook ========
ds@294
     2
* Copyright (C) 2004-2007 Metamod:Source Development Team
pavolmarko@1
     3
* No warranties of any kind
pavolmarko@1
     4
*
dvander@10
     5
* License: zlib/libpng
dvander@10
     6
*
dvander@10
     7
* Author(s): Pavol "PM OnoTo" Marko
pavolmarko@1
     8
* ============================
pavolmarko@1
     9
*/
pavolmarko@1
    10
pavolmarko@1
    11
#ifndef __SOURCEHOOK_IMPL_H__
pavolmarko@1
    12
#define __SOURCEHOOK_IMPL_H__
pavolmarko@1
    13
pavolmarko@1
    14
#include "sourcehook.h"
pavolmarko@418
    15
#include "sh_memory.h"
pavolmarko@117
    16
#include "sh_list.h"
pavolmarko@117
    17
#include "sh_vector.h"
pavolmarko@117
    18
#include "sh_tinyhash.h"
pavolmarko@128
    19
#include "sh_stack.h"
ds@86
    20
pavolmarko@163
    21
/*
pavolmarko@163
    22
pavolmarko@163
    23
IMPLEMENTATION INFO
pavolmarko@163
    24
pavolmarko@163
    25
---------------------------------------
pavolmarko@380
    26
 :TODO: update ???
pavolmarko@380
    27
pavolmarko@163
    28
Protos ("Prototypes")
pavolmarko@163
    29
	The purpose of protos is to provide the amount of type information about a function
pavolmarko@163
    30
	which is required to be able to execute a function call without corrupting the stack.
pavolmarko@233
    31
	Our protos do not fully do this, but they provide the size of the return value, the number of
pavolmarko@233
    32
	parameters, and the size of each parameter, which is enough for most situations.
pavolmarko@163
    33
pavolmarko@163
    34
	There are two version of protos:
pavolmarko@163
    35
	OLD:
pavolmarko@163
    36
		C-Style strings.
pavolmarko@163
    37
pavolmarko@163
    38
		0_void:
pavolmarko@163
    39
		"attrib"
pavolmarko@163
    40
		1_void:
pavolmarko@163
    41
		"attrib|param1_type"
pavolmarko@163
    42
		2_void:
pavolmarko@163
    43
		"attrib|param1_type|param2_type
pavolmarko@163
    44
		0:
pavolmarko@163
    45
		"attrib|ret_type"
pavolmarko@163
    46
		1:
pavolmarko@163
    47
		"attrib|ret_type|param1_type"
pavolmarko@163
    48
		2:
pavolmarko@163
    49
		"attrib|ret_type|param2_type"
pavolmarko@163
    50
pavolmarko@163
    51
		Old protos are deprecated.
pavolmarko@163
    52
pavolmarko@163
    53
	NEW:
pavolmarko@163
    54
		New protos are in fact pointers to the ProtoInfo structure (see sourcehook.h)
pavolmarko@163
    55
pavolmarko@163
    56
	Old protos begin with a non-zero byte, new protos begin with a zero byte.
pavolmarko@163
    57
pavolmarko@163
    58
	Protos are usually stored in a CProto instance.
pavolmarko@163
    59
pavolmarko@163
    60
---------------------------------------
pavolmarko@163
    61
Hook managers and hook manager containers
pavolmarko@163
    62
	Each hookman container is tied to _one_ proto/vtable index/vtable offset info.
pavolmarko@163
    63
	Hookman containers then contain a list of hook managers provided by plugins, sorted by version.
pavolmarko@163
    64
	(higher versions come first)
pavolmarko@163
    65
pavolmarko@163
    66
	Duplicate hook managers are ignored (ie. hook managers where proto, vtable index, vtable offset,
pavolmarko@163
    67
	plugin, version are the same as in an already exisiting hook manager)
pavolmarko@163
    68
pavolmarko@163
    69
	A new hook manager is always added to the end of the version group in the corresponding
pavolmarko@163
    70
	hook container. 
pavolmarko@163
    71
pavolmarko@163
    72
	If the new hook manager was added to the beginning of the container (which only happens if
pavolmarko@163
    73
	it is the first one or if it has a higher version than the previously first hook manager),
pavolmarko@163
    74
	the now second hook manager is shut down and the new hook manager takes its job.
pavolmarko@163
    75
pavolmarko@163
    76
	A "hook manager container id" (HMCI) consits of three values: proto, vtbl index, vtbl offset.
pavolmarko@163
    77
---------------------------------------
pavolmarko@163
    78
Hooks 
pavolmarko@163
    79
	When adding a hook, first the proposed hook manager is added to the corresponding
pavolmarko@163
    80
	hook manager container as described above.
pavolmarko@163
    81
pavolmarko@163
    82
	Then the first hook manager in the the manhook container is chosen to handle the function.
pavolmarko@163
    83
pavolmarko@163
    84
	Removing a hook does not neccessarily unreigster the plugin's hook manager. In order to do this,
pavolmarko@163
    85
	use RemoveHookManager or UnloadPlugin/
pavolmarko@163
    86
pavolmarko@163
    87
	Hooks can be paused - they remain in memory but they are not called. In SH, the hook iterator
pavolmarko@163
    88
	classes handle pausing transparently.
pavolmarko@163
    89
pavolmarko@163
    90
	The hook loop is supposed to call ShouldContinue before each iteration. This makes hook handlers
pavolmarko@163
    91
	able to remove themselves.
pavolmarko@163
    92
pavolmarko@163
    93
---------------------------------------
pavolmarko@163
    94
Call classes
pavolmarko@328
    95
pavolmarko@328
    96
	!! deprecated !!   - see below (new SH_CALL)
pavolmarko@328
    97
pavolmarko@163
    98
	Call classes are identified by a this pointer and an instance size
pavolmarko@163
    99
pavolmarko@163
   100
	We use the instance size because a derived class instance and a base class instance could
pavolmarko@163
   101
	have the same this pointers, and we want to avoid that the derived class
pavolmarko@163
   102
	(which could be bigger) gets the same callclass as the base class (mainly if the
pavolmarko@163
   103
	base class' callclass was requested first).
pavolmarko@163
   104
pavolmarko@163
   105
	Call classes are reference counted.
pavolmarko@163
   106
pavolmarko@163
   107
	The original function pointers are stored in a vector (in order to allow fast random access).
pavolmarko@163
   108
	These vectors are stored as the value type of a hash. The key type is int and represents the
pavolmarko@163
   109
	vtable offset.
pavolmarko@163
   110
pavolmarko@163
   111
	If the hash key doesn't exist or the vtblidx is out of range or the corresponding element in the
pavolmarko@163
   112
	vector is NULL, there is no hook on that function.
pavolmarko@163
   113
pavolmarko@163
   114
---------------------------------------
pavolmarko@163
   115
Recalls
pavolmarko@163
   116
	Recalls are used for the META_RETURN_(VALUE_)NEWPARAMS macros, ie. to change the parameters
pavolmarko@163
   117
	in the hook loop on the fly.
pavolmarko@163
   118
	
pavolmarko@163
   119
	First, the macro calls DoRecall(), then it calls the function the hook is attached to -> it 
pavolmarko@163
   120
	calls the hookfunc. SourceHook makes sure that the newly invoked hook loop starts where the last
pavolmarko@163
   121
	one left off and that status variables like status, previous result, override return are kept.
pavolmarko@163
   122
	When this recurisvely called hookfunc returns, the macro returns what it returned
pavolmarko@163
   123
	(using MRES_SUPERCEDE). CSourceHookImpl returns false from ShouldContinue so the original hook loop
pavolmarko@163
   124
	is abandonned.
pavolmarko@179
   125
pavolmarko@179
   126
Post Recalls
pavolmarko@179
   127
	People wanted to be able to use META_RETURN_(VALUE_)NEWPARAMS from post hooks as well. Crazy people!
pavolmarko@179
   128
	Anyway, for this, we have to know where a hook handler is. Is it executing pre or post hooks at the moment?
pavolmarko@179
   129
	The only way we can know this is watching when it calls CHookList::GetIter(). So CHookList gets a new variable:
pavolmarko@179
   130
	m_RequestedFlag. It also gets two new functions: RQFlagReset() and RQFlagGet().
pavolmarko@179
   131
	HookLoopBegin() calls RQFlagReset on both hooklists of the iface; then DoRecall() checks whether the postlist's 
pavolmarko@179
   132
	RQ flag is set. if yes, the hook loop is in post mode.
pavolmarko@179
   133
pavolmarko@179
   134
	So, what a about a recall in post mode? The first ShouldContinue returns false and sets Status to supercede. 
pavolmarko@179
   135
	This way the pre hooks and the function call will be skipped. Then, then next ShouldContinue returns true, so we get
pavolmarko@179
   136
	into the post hooks. HA!
pavolmarko@179
   137
pavolmarko@179
   138
Return Values in Post Recalls
pavolmarko@179
   139
	The easy case is when we already have an override return value. In this case, the status register gets transferred,
pavolmarko@179
   140
	and so does the override return pointer. So, basically, everything is ok.
pavolmarko@179
   141
pavolmarko@179
   142
	However, what happens if we don't? ie. the status register is on MRES_IGNORED? In this case we'd have to transfer the
pavolmarko@179
   143
	orig ret value. But we can't: There's no way to tell the hookfunc: "Use this as orig ret pointer". It uses its own.
pavolmarko@179
   144
	So, we emulate it. GetOrigRet will return the orig ret pointer from the old hook loop. If still no one overrides it,
pavolmarko@179
   145
	we'd have to return it. BUT! HOW TO DO THIS? Check out SH_RETURN(). First calls HookLoopEnd(), then decides whether
pavolmarko@179
   146
	to return the override retval or the orig retval. But it doesn't ask for a new override return. So we give the function
pavolmarko@179
   147
	the last orig return value as its new override return value; but leave status where it is so everything works, and in
pavolmarko@179
   148
	HookLoopEnd we make sure that status is high enough so that the override return will be returned. crazy.
pavolmarko@179
   149
pavolmarko@179
   150
	All this stuff could be much less complicated if I didn't try to preserve binary compatibility :)
pavolmarko@324
   151
pavolmarko@324
   152
VP Hooks
pavolmarko@324
   153
	VP hooks are hooks which are called on a vfnptr, regardless of the this pointer with which it was called. They are
pavolmarko@324
   154
	implemented as a special CIface instance with m_Ptr = NULL. All Hook Lists have a new "ListCatIterator" which
pavolmarko@324
   155
	virtually concatenates the NULL-interface-hook-list with their normal hook list.
pavolmarko@324
   156
pavolmarko@324
   157
pavolmarko@324
   158
	I'm afraid that with the addition of Recalls and VP Hooks, SourceHook is now a pretty complex and hacked-together
pavolmarko@324
   159
	binary compatible beast which is pretty hard to maintain unless you've written it :)
pavolmarko@328
   160
pavolmarko@328
   161
New SH_CALL
pavolmarko@328
   162
	The addition of VP hooks messed up the Call Classes concept (see above) - call classes are bound to an
pavolmarko@328
   163
	instance pointer; they only work on one of the hooked instances. But VP hooks are called on all instances.
pavolmarko@328
   164
	
pavolmarko@328
   165
	That's why now, SH_CALL takes an instance pointer instead of a callclass pointer. It basically does this:
pavolmarko@328
   166
	1) call SH_GLOB_PTR->SetIgnoreHooks(vfnptr)
pavolmarko@328
   167
	2) call this->*mfp
pavolmarko@328
   168
	3) call SH_GLOB_PTR->ResetIgnoreHooks(vfnptr)
pavolmarko@328
   169
pavolmarko@328
   170
	SourceHook stroes the "ignored vfnptr" and makes CVfnPtr::FindIface return NULL if the CVfnPtr instance
pavolmarko@328
   171
	corresponds to the ignored vfnptr. This way the hook manager thinks that the instance isn't hooked, and calls
pavolmarko@328
   172
	the original function. Everything works fine. This works even for VP hooks.
pavolmarko@163
   173
*/
pavolmarko@163
   174
pavolmarko@380
   175
#include "sourcehook_impl_cproto.h"
pavolmarko@418
   176
#include "sourcehook_impl_chookmaninfo.h"
pavolmarko@380
   177
#include "sourcehook_impl_chook.h"
pavolmarko@380
   178
#include "sourcehook_impl_ciface.h"
pavolmarko@380
   179
#include "sourcehook_impl_cvfnptr.h"
pavolmarko@380
   180
#include "sourcehook_impl_chookidman.h"
pavolmarko@380
   181
pavolmarko@1
   182
namespace SourceHook
pavolmarko@1
   183
{
pavolmarko@1
   184
	/**
pavolmarko@380
   185
	*	@brief The SourceHook implementation
pavolmarko@1
   186
	*/
pavolmarko@163
   187
pavolmarko@380
   188
	namespace Impl
pavolmarko@380
   189
	{
pavolmarko@380
   190
		struct CHookContext : IHookContext
pavolmarko@117
   191
		{
pavolmarko@380
   192
			enum State
pavolmarko@117
   193
			{
pavolmarko@380
   194
				State_Born,
pavolmarko@380
   195
				State_Pre,
pavolmarko@380
   196
				State_PreVP,
pavolmarko@380
   197
				State_Post,
pavolmarko@380
   198
				State_PostVP,
pavolmarko@380
   199
				State_OrigCall,
pavolmarko@380
   200
				State_Dead,
pavolmarko@117
   201
pavolmarko@380
   202
				// Special
pavolmarko@380
   203
				State_Ignore,
pavolmarko@380
   204
				State_Recall_Pre,
pavolmarko@380
   205
				State_Recall_PreVP,
pavolmarko@380
   206
				State_Recall_Post,
pavolmarko@380
   207
				State_Recall_PostVP
pavolmarko@117
   208
			};
pavolmarko@117
   209
pavolmarko@380
   210
			int m_State;
pavolmarko@380
   211
			List<CHook>::iterator m_Iter;
pavolmarko@163
   212
pavolmarko@380
   213
			CVfnPtr *pVfnPtr;
pavolmarko@380
   214
			CIface *pIface;
pavolmarko@380
   215
			
pavolmarko@128
   216
			META_RES *pStatus;
pavolmarko@128
   217
			META_RES *pPrevRes;
pavolmarko@128
   218
			META_RES *pCurRes;
pavolmarko@128
   219
pavolmarko@380
   220
			void *pThisPtr;
pavolmarko@128
   221
			const void *pOrigRet;
pavolmarko@162
   222
			void *pOverrideRet;
pavolmarko@380
   223
			void *pIfacePtr;
pavolmarko@1
   224
pavolmarko@380
   225
			bool m_CallOrig;
pavolmarko@1
   226
pavolmarko@380
   227
			void SkipPaused(List<CHook>::iterator &iter, List<CHook> &list)
pavolmarko@380
   228
			{
pavolmarko@380
   229
				while (iter != list.end() && iter->IsPaused())
pavolmarko@380
   230
					++iter;
pavolmarko@380
   231
			}
pavolmarko@380
   232
		public:
pavolmarko@380
   233
			void HookRemoved(List<CHook>::iterator oldhookiter, List<CHook>::iterator nexthookiter);
pavolmarko@380
   234
			void IfaceRemoved(CIface *iface);
pavolmarko@380
   235
			void VfnPtrRemoved(CVfnPtr *vfnptr);
pavolmarko@58
   236
pavolmarko@380
   237
			ISHDelegate *GetNext();
pavolmarko@380
   238
			void *GetOverrideRetPtr();
pavolmarko@380
   239
			const void *GetOrigRetPtr();
pavolmarko@380
   240
			bool ShouldCallOrig();
pavolmarko@380
   241
		};
pavolmarko@1
   242
pavolmarko@418
   243
		class CVfnPtrList : public List<CVfnPtr>
pavolmarko@418
   244
		{
pavolmarko@418
   245
		public:
pavolmarko@418
   246
			CVfnPtr &GetVfnPtr(void *p);
pavolmarko@418
   247
		};
pavolmarko@418
   248
pavolmarko@380
   249
		typedef CStack<CHookContext> HookContextStack;
pavolmarko@418
   250
		
pavolmarko@1
   251
pavolmarko@380
   252
		class CSourceHookImpl : public ISourceHook
pavolmarko@380
   253
		{
pavolmarko@380
   254
		private:
pavolmarko@418
   255
			CHookManList m_HookManList;
pavolmarko@418
   256
			CVfnPtrList m_VfnPtrs;
pavolmarko@380
   257
			CHookIDManager m_HookIDMan;
pavolmarko@380
   258
			HookContextStack m_ContextStack;
pavolmarko@1
   259
pavolmarko@380
   260
			bool SetHookPaused(int hookid, bool paused);
pavolmarko@418
   261
			CHookManList::iterator RemoveHookManager(CHookManList::iterator iter);
pavolmarko@380
   262
		public:
pavolmarko@380
   263
			CSourceHookImpl();
pavolmarko@380
   264
			virtual ~CSourceHookImpl();
pavolmarko@41
   265
pavolmarko@380
   266
			/**
pavolmarko@380
   267
			*	@brief Returns the interface version
pavolmarko@380
   268
			*/
pavolmarko@380
   269
			int GetIfaceVersion();
pavolmarko@41
   270
pavolmarko@380
   271
			/**
pavolmarko@380
   272
			*	@brief Returns the implemnetation version
pavolmarko@380
   273
			*/
pavolmarko@380
   274
			int GetImplVersion();
pavolmarko@1
   275
pavolmarko@380
   276
			int AddHook(Plugin plug, AddHookMode mode, void *iface, int thisptr_offs, HookManagerPubFunc myHookMan,
pavolmarko@380
   277
				ISHDelegate *handler, bool post);
pavolmarko@8
   278
pavolmarko@380
   279
			bool RemoveHook(Plugin plug, void *iface, int thisptr_offs, HookManagerPubFunc myHookMan,
pavolmarko@380
   280
				ISHDelegate *handler, bool post);
pavolmarko@380
   281
pavolmarko@380
   282
			bool RemoveHookByID(int hookid);
pavolmarko@8
   283
pavolmarko@380
   284
			bool PauseHookByID(int hookid);
pavolmarko@380
   285
			bool UnpauseHookByID(int hookid);
pavolmarko@1
   286
pavolmarko@380
   287
			void SetRes(META_RES res);				//!< Sets the meta result
pavolmarko@380
   288
			META_RES GetPrevRes();					//!< Gets the meta result of the
pavolmarko@380
   289
													//!<  previously calledhandler
pavolmarko@380
   290
			META_RES GetStatus();					//!< Gets the highest meta result
pavolmarko@380
   291
			const void *GetOrigRet();				//!< Gets the original result.
pavolmarko@380
   292
													//!<  If not in post function, undefined
pavolmarko@380
   293
			const void *GetOverrideRet();			//!< Gets the override result.
pavolmarko@380
   294
													//!<  If none is specified, NULL
pavolmarko@380
   295
			void *GetIfacePtr();					//!< Gets the interface pointer
pavolmarko@157
   296
pavolmarko@380
   297
			void *GetOverrideRetPtr();				//!< Used for setting the override return value
pavolmarko@163
   298
pavolmarko@380
   299
			/**
pavolmarko@380
   300
			*	@brief Make sure that a plugin is not used by any other plugins anymore, and unregister all its hook managers
pavolmarko@380
   301
			*/
pavolmarko@380
   302
			void UnloadPlugin(Plugin plug);
pavolmarko@162
   303
pavolmarko@380
   304
			void RemoveHookManager(Plugin plug, HookManagerPubFunc pubFunc);
pavolmarko@380
   305
pavolmarko@380
   306
			void SetIgnoreHooks(void *vfnptr);
pavolmarko@380
   307
			void ResetIgnoreHooks(void *vfnptr);
pavolmarko@324
   308
pavolmarko@380
   309
			void DoRecall();
pavolmarko@380
   310
pavolmarko@380
   311
			IHookContext *SetupHookLoop(IHookManagerInfo *hi, void *vfnptr, void *thisptr, void **origentry, META_RES *statusPtr,
pavolmarko@380
   312
				META_RES *prevResPtr, META_RES *curResPtr, const void *origRetPtr, void *overrideRetPtr);
pavolmarko@380
   313
pavolmarko@380
   314
			void EndContext(IHookContext *pCtx);
pavolmarko@380
   315
pavolmarko@386
   316
			void *GetOrigVfnPtrEntry(void *vfnptr);
pavolmarko@386
   317
pavolmarko@380
   318
			/**
pavolmarko@380
   319
			*	@brief Shut down the whole system, unregister all hook managers
pavolmarko@380
   320
			*/
pavolmarko@380
   321
			void CompleteShutdown();
pavolmarko@324
   322
pavolmarko@380
   323
			/**
pavolmarko@380
   324
			*	@brief Pauses all hooks of a plugin
pavolmarko@380
   325
			*
pavolmarko@380
   326
			*	@param plug The unique identifier of the plugin
pavolmarko@380
   327
			*/
pavolmarko@380
   328
			void PausePlugin(Plugin plug);
pavolmarko@328
   329
pavolmarko@380
   330
			/**
pavolmarko@380
   331
			*	@brief Unpauses all hooks of a plugin
pavolmarko@380
   332
			*
pavolmarko@380
   333
			*	@param plug The unique identifier of the plugin
pavolmarko@380
   334
			*/
pavolmarko@380
   335
			void UnpausePlugin(Plugin plug);
pavolmarko@380
   336
		};
pavolmarko@380
   337
	}
pavolmarko@1
   338
}
pavolmarko@1
   339
dvander@34
   340
#endif