sourcehook/sourcehook_impl.h
branchhookman_autogen
changeset 531 0180319136ba
parent 479 b43ebc944319
child 532 9729de2d7551
     1.1 --- a/sourcehook/sourcehook_impl.h	Sun Nov 25 01:22:41 2007 +0000
     1.2 +++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.3 @@ -1,340 +0,0 @@
     1.4 -/* ======== SourceHook ========
     1.5 -* Copyright (C) 2004-2007 Metamod:Source Development Team
     1.6 -* No warranties of any kind
     1.7 -*
     1.8 -* License: zlib/libpng
     1.9 -*
    1.10 -* Author(s): Pavol "PM OnoTo" Marko
    1.11 -* ============================
    1.12 -*/
    1.13 -
    1.14 -#ifndef __SOURCEHOOK_IMPL_H__
    1.15 -#define __SOURCEHOOK_IMPL_H__
    1.16 -
    1.17 -#include "sourcehook.h"
    1.18 -#include "sh_memory.h"
    1.19 -#include "sh_list.h"
    1.20 -#include "sh_vector.h"
    1.21 -#include "sh_tinyhash.h"
    1.22 -#include "sh_stack.h"
    1.23 -
    1.24 -/*
    1.25 -
    1.26 -IMPLEMENTATION INFO
    1.27 -
    1.28 ----------------------------------------
    1.29 - :TODO: update ???
    1.30 -
    1.31 -Protos ("Prototypes")
    1.32 -	The purpose of protos is to provide the amount of type information about a function
    1.33 -	which is required to be able to execute a function call without corrupting the stack.
    1.34 -	Our protos do not fully do this, but they provide the size of the return value, the number of
    1.35 -	parameters, and the size of each parameter, which is enough for most situations.
    1.36 -
    1.37 -	There are two version of protos:
    1.38 -	OLD:
    1.39 -		C-Style strings.
    1.40 -
    1.41 -		0_void:
    1.42 -		"attrib"
    1.43 -		1_void:
    1.44 -		"attrib|param1_type"
    1.45 -		2_void:
    1.46 -		"attrib|param1_type|param2_type
    1.47 -		0:
    1.48 -		"attrib|ret_type"
    1.49 -		1:
    1.50 -		"attrib|ret_type|param1_type"
    1.51 -		2:
    1.52 -		"attrib|ret_type|param2_type"
    1.53 -
    1.54 -		Old protos are deprecated.
    1.55 -
    1.56 -	NEW:
    1.57 -		New protos are in fact pointers to the ProtoInfo structure (see sourcehook.h)
    1.58 -
    1.59 -	Old protos begin with a non-zero byte, new protos begin with a zero byte.
    1.60 -
    1.61 -	Protos are usually stored in a CProto instance.
    1.62 -
    1.63 ----------------------------------------
    1.64 -Hook managers and hook manager containers
    1.65 -	Each hookman container is tied to _one_ proto/vtable index/vtable offset info.
    1.66 -	Hookman containers then contain a list of hook managers provided by plugins, sorted by version.
    1.67 -	(higher versions come first)
    1.68 -
    1.69 -	Duplicate hook managers are ignored (ie. hook managers where proto, vtable index, vtable offset,
    1.70 -	plugin, version are the same as in an already exisiting hook manager)
    1.71 -
    1.72 -	A new hook manager is always added to the end of the version group in the corresponding
    1.73 -	hook container. 
    1.74 -
    1.75 -	If the new hook manager was added to the beginning of the container (which only happens if
    1.76 -	it is the first one or if it has a higher version than the previously first hook manager),
    1.77 -	the now second hook manager is shut down and the new hook manager takes its job.
    1.78 -
    1.79 -	A "hook manager container id" (HMCI) consits of three values: proto, vtbl index, vtbl offset.
    1.80 ----------------------------------------
    1.81 -Hooks 
    1.82 -	When adding a hook, first the proposed hook manager is added to the corresponding
    1.83 -	hook manager container as described above.
    1.84 -
    1.85 -	Then the first hook manager in the the manhook container is chosen to handle the function.
    1.86 -
    1.87 -	Removing a hook does not neccessarily unreigster the plugin's hook manager. In order to do this,
    1.88 -	use RemoveHookManager or UnloadPlugin/
    1.89 -
    1.90 -	Hooks can be paused - they remain in memory but they are not called. In SH, the hook iterator
    1.91 -	classes handle pausing transparently.
    1.92 -
    1.93 -	The hook loop is supposed to call ShouldContinue before each iteration. This makes hook handlers
    1.94 -	able to remove themselves.
    1.95 -
    1.96 ----------------------------------------
    1.97 -Call classes
    1.98 -
    1.99 -	!! deprecated !!   - see below (new SH_CALL)
   1.100 -
   1.101 -	Call classes are identified by a this pointer and an instance size
   1.102 -
   1.103 -	We use the instance size because a derived class instance and a base class instance could
   1.104 -	have the same this pointers, and we want to avoid that the derived class
   1.105 -	(which could be bigger) gets the same callclass as the base class (mainly if the
   1.106 -	base class' callclass was requested first).
   1.107 -
   1.108 -	Call classes are reference counted.
   1.109 -
   1.110 -	The original function pointers are stored in a vector (in order to allow fast random access).
   1.111 -	These vectors are stored as the value type of a hash. The key type is int and represents the
   1.112 -	vtable offset.
   1.113 -
   1.114 -	If the hash key doesn't exist or the vtblidx is out of range or the corresponding element in the
   1.115 -	vector is NULL, there is no hook on that function.
   1.116 -
   1.117 ----------------------------------------
   1.118 -Recalls
   1.119 -	Recalls are used for the META_RETURN_(VALUE_)NEWPARAMS macros, ie. to change the parameters
   1.120 -	in the hook loop on the fly.
   1.121 -	
   1.122 -	First, the macro calls DoRecall(), then it calls the function the hook is attached to -> it 
   1.123 -	calls the hookfunc. SourceHook makes sure that the newly invoked hook loop starts where the last
   1.124 -	one left off and that status variables like status, previous result, override return are kept.
   1.125 -	When this recurisvely called hookfunc returns, the macro returns what it returned
   1.126 -	(using MRES_SUPERCEDE). CSourceHookImpl returns false from ShouldContinue so the original hook loop
   1.127 -	is abandonned.
   1.128 -
   1.129 -Post Recalls
   1.130 -	People wanted to be able to use META_RETURN_(VALUE_)NEWPARAMS from post hooks as well. Crazy people!
   1.131 -	Anyway, for this, we have to know where a hook handler is. Is it executing pre or post hooks at the moment?
   1.132 -	The only way we can know this is watching when it calls CHookList::GetIter(). So CHookList gets a new variable:
   1.133 -	m_RequestedFlag. It also gets two new functions: RQFlagReset() and RQFlagGet().
   1.134 -	HookLoopBegin() calls RQFlagReset on both hooklists of the iface; then DoRecall() checks whether the postlist's 
   1.135 -	RQ flag is set. if yes, the hook loop is in post mode.
   1.136 -
   1.137 -	So, what a about a recall in post mode? The first ShouldContinue returns false and sets Status to supercede. 
   1.138 -	This way the pre hooks and the function call will be skipped. Then, then next ShouldContinue returns true, so we get
   1.139 -	into the post hooks. HA!
   1.140 -
   1.141 -Return Values in Post Recalls
   1.142 -	The easy case is when we already have an override return value. In this case, the status register gets transferred,
   1.143 -	and so does the override return pointer. So, basically, everything is ok.
   1.144 -
   1.145 -	However, what happens if we don't? ie. the status register is on MRES_IGNORED? In this case we'd have to transfer the
   1.146 -	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.
   1.147 -	So, we emulate it. GetOrigRet will return the orig ret pointer from the old hook loop. If still no one overrides it,
   1.148 -	we'd have to return it. BUT! HOW TO DO THIS? Check out SH_RETURN(). First calls HookLoopEnd(), then decides whether
   1.149 -	to return the override retval or the orig retval. But it doesn't ask for a new override return. So we give the function
   1.150 -	the last orig return value as its new override return value; but leave status where it is so everything works, and in
   1.151 -	HookLoopEnd we make sure that status is high enough so that the override return will be returned. crazy.
   1.152 -
   1.153 -	All this stuff could be much less complicated if I didn't try to preserve binary compatibility :)
   1.154 -
   1.155 -VP Hooks
   1.156 -	VP hooks are hooks which are called on a vfnptr, regardless of the this pointer with which it was called. They are
   1.157 -	implemented as a special CIface instance with m_Ptr = NULL. All Hook Lists have a new "ListCatIterator" which
   1.158 -	virtually concatenates the NULL-interface-hook-list with their normal hook list.
   1.159 -
   1.160 -
   1.161 -	I'm afraid that with the addition of Recalls and VP Hooks, SourceHook is now a pretty complex and hacked-together
   1.162 -	binary compatible beast which is pretty hard to maintain unless you've written it :)
   1.163 -
   1.164 -New SH_CALL
   1.165 -	The addition of VP hooks messed up the Call Classes concept (see above) - call classes are bound to an
   1.166 -	instance pointer; they only work on one of the hooked instances. But VP hooks are called on all instances.
   1.167 -	
   1.168 -	That's why now, SH_CALL takes an instance pointer instead of a callclass pointer. It basically does this:
   1.169 -	1) call SH_GLOB_PTR->SetIgnoreHooks(vfnptr)
   1.170 -	2) call this->*mfp
   1.171 -	3) call SH_GLOB_PTR->ResetIgnoreHooks(vfnptr)
   1.172 -
   1.173 -	SourceHook stroes the "ignored vfnptr" and makes CVfnPtr::FindIface return NULL if the CVfnPtr instance
   1.174 -	corresponds to the ignored vfnptr. This way the hook manager thinks that the instance isn't hooked, and calls
   1.175 -	the original function. Everything works fine. This works even for VP hooks.
   1.176 -*/
   1.177 -
   1.178 -#include "sourcehook_impl_cproto.h"
   1.179 -#include "sourcehook_impl_chookmaninfo.h"
   1.180 -#include "sourcehook_impl_chook.h"
   1.181 -#include "sourcehook_impl_ciface.h"
   1.182 -#include "sourcehook_impl_cvfnptr.h"
   1.183 -#include "sourcehook_impl_chookidman.h"
   1.184 -
   1.185 -namespace SourceHook
   1.186 -{
   1.187 -	/**
   1.188 -	*	@brief The SourceHook implementation
   1.189 -	*/
   1.190 -
   1.191 -	namespace Impl
   1.192 -	{
   1.193 -		struct CHookContext : IHookContext
   1.194 -		{
   1.195 -			enum State
   1.196 -			{
   1.197 -				State_Born,
   1.198 -				State_Pre,
   1.199 -				State_PreVP,
   1.200 -				State_Post,
   1.201 -				State_PostVP,
   1.202 -				State_OrigCall,
   1.203 -				State_Dead,
   1.204 -
   1.205 -				// Special
   1.206 -				State_Ignore,
   1.207 -				State_Recall_Pre,
   1.208 -				State_Recall_PreVP,
   1.209 -				State_Recall_Post,
   1.210 -				State_Recall_PostVP
   1.211 -			};
   1.212 -
   1.213 -			int m_State;
   1.214 -			List<CHook>::iterator m_Iter;
   1.215 -
   1.216 -			CVfnPtr *pVfnPtr;
   1.217 -			CIface *pIface;
   1.218 -			
   1.219 -			META_RES *pStatus;
   1.220 -			META_RES *pPrevRes;
   1.221 -			META_RES *pCurRes;
   1.222 -
   1.223 -			void *pThisPtr;
   1.224 -			const void *pOrigRet;
   1.225 -			void *pOverrideRet;
   1.226 -			void *pIfacePtr;
   1.227 -
   1.228 -			bool m_CallOrig;
   1.229 -
   1.230 -			void SkipPaused(List<CHook>::iterator &iter, List<CHook> &list)
   1.231 -			{
   1.232 -				while (iter != list.end() && iter->IsPaused())
   1.233 -					++iter;
   1.234 -			}
   1.235 -		public:
   1.236 -			void HookRemoved(List<CHook>::iterator oldhookiter, List<CHook>::iterator nexthookiter);
   1.237 -			void IfaceRemoved(CIface *iface);
   1.238 -			void VfnPtrRemoved(CVfnPtr *vfnptr);
   1.239 -
   1.240 -			ISHDelegate *GetNext();
   1.241 -			void *GetOverrideRetPtr();
   1.242 -			const void *GetOrigRetPtr();
   1.243 -			bool ShouldCallOrig();
   1.244 -		};
   1.245 -
   1.246 -		class CVfnPtrList : public List<CVfnPtr>
   1.247 -		{
   1.248 -		public:
   1.249 -			CVfnPtr &GetVfnPtr(void *p);
   1.250 -		};
   1.251 -
   1.252 -		typedef CStack<CHookContext> HookContextStack;
   1.253 -		
   1.254 -
   1.255 -		class CSourceHookImpl : public ISourceHook
   1.256 -		{
   1.257 -		private:
   1.258 -			CHookManList m_HookManList;
   1.259 -			CVfnPtrList m_VfnPtrs;
   1.260 -			CHookIDManager m_HookIDMan;
   1.261 -			HookContextStack m_ContextStack;
   1.262 -
   1.263 -			bool SetHookPaused(int hookid, bool paused);
   1.264 -			CHookManList::iterator RemoveHookManager(CHookManList::iterator iter);
   1.265 -		public:
   1.266 -			CSourceHookImpl();
   1.267 -			virtual ~CSourceHookImpl();
   1.268 -
   1.269 -			/**
   1.270 -			*	@brief Returns the interface version
   1.271 -			*/
   1.272 -			int GetIfaceVersion();
   1.273 -
   1.274 -			/**
   1.275 -			*	@brief Returns the implemnetation version
   1.276 -			*/
   1.277 -			int GetImplVersion();
   1.278 -
   1.279 -			int AddHook(Plugin plug, AddHookMode mode, void *iface, int thisptr_offs, HookManagerPubFunc myHookMan,
   1.280 -				ISHDelegate *handler, bool post);
   1.281 -
   1.282 -			bool RemoveHook(Plugin plug, void *iface, int thisptr_offs, HookManagerPubFunc myHookMan,
   1.283 -				ISHDelegate *handler, bool post);
   1.284 -
   1.285 -			bool RemoveHookByID(int hookid);
   1.286 -
   1.287 -			bool PauseHookByID(int hookid);
   1.288 -			bool UnpauseHookByID(int hookid);
   1.289 -
   1.290 -			void SetRes(META_RES res);				//!< Sets the meta result
   1.291 -			META_RES GetPrevRes();					//!< Gets the meta result of the
   1.292 -													//!<  previously calledhandler
   1.293 -			META_RES GetStatus();					//!< Gets the highest meta result
   1.294 -			const void *GetOrigRet();				//!< Gets the original result.
   1.295 -													//!<  If not in post function, undefined
   1.296 -			const void *GetOverrideRet();			//!< Gets the override result.
   1.297 -													//!<  If none is specified, NULL
   1.298 -			void *GetIfacePtr();					//!< Gets the interface pointer
   1.299 -
   1.300 -			void *GetOverrideRetPtr();				//!< Used for setting the override return value
   1.301 -
   1.302 -			/**
   1.303 -			*	@brief Make sure that a plugin is not used by any other plugins anymore, and unregister all its hook managers
   1.304 -			*/
   1.305 -			void UnloadPlugin(Plugin plug);
   1.306 -
   1.307 -			void RemoveHookManager(Plugin plug, HookManagerPubFunc pubFunc);
   1.308 -
   1.309 -			void SetIgnoreHooks(void *vfnptr);
   1.310 -			void ResetIgnoreHooks(void *vfnptr);
   1.311 -
   1.312 -			void DoRecall();
   1.313 -
   1.314 -			IHookContext *SetupHookLoop(IHookManagerInfo *hi, void *vfnptr, void *thisptr, void **origentry, META_RES *statusPtr,
   1.315 -				META_RES *prevResPtr, META_RES *curResPtr, const void *origRetPtr, void *overrideRetPtr);
   1.316 -
   1.317 -			void EndContext(IHookContext *pCtx);
   1.318 -
   1.319 -			void *GetOrigVfnPtrEntry(void *vfnptr);
   1.320 -
   1.321 -			/**
   1.322 -			*	@brief Shut down the whole system, unregister all hook managers
   1.323 -			*/
   1.324 -			void CompleteShutdown();
   1.325 -
   1.326 -			/**
   1.327 -			*	@brief Pauses all hooks of a plugin
   1.328 -			*
   1.329 -			*	@param plug The unique identifier of the plugin
   1.330 -			*/
   1.331 -			void PausePlugin(Plugin plug);
   1.332 -
   1.333 -			/**
   1.334 -			*	@brief Unpauses all hooks of a plugin
   1.335 -			*
   1.336 -			*	@param plug The unique identifier of the plugin
   1.337 -			*/
   1.338 -			void UnpausePlugin(Plugin plug);
   1.339 -		};
   1.340 -	}
   1.341 -}
   1.342 -
   1.343 -#endif