core/sourcehook/sourcehook_impl.h
changeset 539 db914129ae01
parent 523 6f1630519b81
child 733 2365240861a2
     1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/core/sourcehook/sourcehook_impl.h	Fri Nov 14 04:04:02 2008 -0600
     1.3 @@ -0,0 +1,340 @@
     1.4 +/* ======== SourceHook ========
     1.5 +* Copyright (C) 2004-2008 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