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