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