Uh.
1 /* ======== SourceHook ========
2 * Copyright (C) 2004-2005 Metamod:Source Development Team
3 * No warranties of any kind
7 * Author(s): Pavol "PM OnoTo" Marko
8 * ============================
11 #ifndef __SOURCEHOOK_IMPL_H__
12 #define __SOURCEHOOK_IMPL_H__
14 #include "sourcehook.h"
16 #include "sh_vector.h"
17 #include "sh_tinyhash.h"
24 ---------------------------------------
26 The purpose of protos is to provide the amount of type information about a function
27 which is required to be able to execute a function call without corrupting the stack.
28 Our protos do not fully do this, but they provide the size of the return value, the amount of
29 parameters, and the size of each parameter, which is enough for most situations,
31 There are two version of protos:
40 "attrib|param1_type|param2_type
44 "attrib|ret_type|param1_type"
46 "attrib|ret_type|param2_type"
48 Old protos are deprecated.
51 New protos are in fact pointers to the ProtoInfo structure (see sourcehook.h)
53 Old protos begin with a non-zero byte, new protos begin with a zero byte.
55 Protos are usually stored in a CProto instance.
57 ---------------------------------------
58 Hook managers and hook manager containers
59 Each hookman container is tied to _one_ proto/vtable index/vtable offset info.
60 Hookman containers then contain a list of hook managers provided by plugins, sorted by version.
61 (higher versions come first)
63 Duplicate hook managers are ignored (ie. hook managers where proto, vtable index, vtable offset,
64 plugin, version are the same as in an already exisiting hook manager)
66 A new hook manager is always added to the end of the version group in the corresponding
69 If the new hook manager was added to the beginning of the container (which only happens if
70 it is the first one or if it has a higher version than the previously first hook manager),
71 the now second hook manager is shut down and the new hook manager takes its job.
73 A "hook manager container id" (HMCI) consits of three values: proto, vtbl index, vtbl offset.
74 ---------------------------------------
76 When adding a hook, first the proposed hook manager is added to the corresponding
77 hook manager container as described above.
79 Then the first hook manager in the the manhook container is chosen to handle the function.
81 Removing a hook does not neccessarily unreigster the plugin's hook manager. In order to do this,
82 use RemoveHookManager or UnloadPlugin/
84 Hooks can be paused - they remain in memory but they are not called. In SH, the hook iterator
85 classes handle pausing transparently.
87 The hook loop is supposed to call ShouldContinue before each iteration. This makes hook handlers
88 able to remove themselves.
90 ---------------------------------------
92 Call classes are identified by a this pointer and an instance size
94 We use the instance size because a derived class instance and a base class instance could
95 have the same this pointers, and we want to avoid that the derived class
96 (which could be bigger) gets the same callclass as the base class (mainly if the
97 base class' callclass was requested first).
99 Call classes are reference counted.
101 The original function pointers are stored in a vector (in order to allow fast random access).
102 These vectors are stored as the value type of a hash. The key type is int and represents the
105 If the hash key doesn't exist or the vtblidx is out of range or the corresponding element in the
106 vector is NULL, there is no hook on that function.
108 ---------------------------------------
110 Recalls are used for the META_RETURN_(VALUE_)NEWPARAMS macros, ie. to change the parameters
111 in the hook loop on the fly.
113 First, the macro calls DoRecall(), then it calls the function the hook is attached to -> it
114 calls the hookfunc. SourceHook makes sure that the newly invoked hook loop starts where the last
115 one left off and that status variables like status, previous result, override return are kept.
116 When this recurisvely called hookfunc returns, the macro returns what it returned
117 (using MRES_SUPERCEDE). CSourceHookImpl returns false from ShouldContinue so the original hook loop
124 * @brief The SourceHook implementation class
126 class CSourceHookImpl : public ISourceHook
133 static bool Equal(const char *p1, const char *p2);
135 CProto(const char *szProto) : m_Proto(szProto)
139 CProto(const CProto &other) : m_Proto(other.m_Proto)
143 void operator = (const char *szProto)
147 void operator = (const CProto &other)
149 m_Proto = other.m_Proto;
152 bool operator == (const char *szProto) const
154 return Equal(szProto, m_Proto);
156 bool operator == (const CProto &other) const
158 return Equal(other.m_Proto, m_Proto);
164 * @brief A hook can be removed if you have this information
166 struct RemoveHookInfo
168 RemoveHookInfo(Plugin pplug, void *piface, int tpo, HookManagerPubFunc phookman,
169 ISHDelegate *phandler, bool ppost)
170 : plug(pplug), iface(piface), thisptr_offs(tpo),
171 hookman(phookman), handler(phandler), post(ppost)
178 HookManagerPubFunc hookman;
179 ISHDelegate *handler;
183 struct RemoveHookManInfo
185 RemoveHookManInfo(Plugin pplug, HookManagerPubFunc phookman)
186 : plug(pplug), hookman(phookman)
191 HookManagerPubFunc hookman;
196 ISHDelegate *handler; //!< Pointer to the handler
197 bool paused; //!< If true, the hook should not be executed
198 Plugin plug; //!< The owner plugin
199 int thisptr_offs; //!< This pointer offset
202 class CHookList : public IHookList
205 List<HookInfo> m_List;
209 class CIter : public IHookList::IIter
211 friend class CHookList;
218 List<HookInfo>::iterator m_Iter;
220 CIter(CHookList *pList);
225 void Set(CIter *pOther);
229 ISHDelegate *Handler();
234 CIter *m_pNext; // When stored in m_FreeIters and m_UsedIters
235 CIter *m_pPrev; // Only used when stored in m_UsedIters
239 CIter *m_UsedIters; // The last returned and not-yet-released iter is always m_UsedIters
244 void SetRecallState(); // Sets the list into a state where the next returned
245 // iterator (from GetIter) will be a copy of the last
246 // returned iterator, incremented by one. This is used in Recalls.
247 // The hook resets this state automatically on:
248 // GetIter, ReleaseIter
251 CHookList(const CHookList &other);
252 virtual ~CHookList();
254 void operator=(const CHookList &other);
257 void ReleaseIter(IIter *pIter);
260 // I know, data hiding... But I'm a lazy bastard!
262 class CIface : public IIface
266 CHookList m_PreHooks;
267 CHookList m_PostHooks;
273 IHookList *GetPreHooks();
274 IHookList *GetPostHooks();
276 bool operator==(void *ptr)
282 class CVfnPtr : public IVfnPtr
285 typedef List<CIface> IfaceList;
286 typedef IfaceList::iterator IfaceListIter;
298 void *GetOrigEntry();
300 virtual IIface *FindIface(void *ptr);
302 bool operator==(void *ptr)
308 class CHookManagerInfo : public IHookManagerInfo
311 typedef List<CVfnPtr> VfnPtrList;
312 typedef VfnPtrList::iterator VfnPtrListIter;
315 HookManagerPubFunc m_Func;
320 void *m_HookfuncVfnptr;
322 VfnPtrList m_VfnPtrs;
324 int m_HookManVersion;
327 virtual ~CHookManagerInfo();
329 IVfnPtr *FindVfnPtr(void *vfnptr);
331 void SetInfo(int vtbl_offs, int vtbl_idx, const char *proto);
332 void SetHookfuncVfnptr(void *hookfunc_vfnptr);
334 void SetVersion(int version);
336 bool operator < (const CHookManagerInfo &other)
338 return m_HookManVersion < other.m_HookManVersion;
343 Descriptor(Plugin pplug, HookManagerPubFunc ppubFunc) : plug(pplug), pubFunc(ppubFunc)
348 HookManagerPubFunc pubFunc;
351 bool operator == (const Descriptor desc)
353 return m_Func == desc.pubFunc && m_Plug == desc.plug;
357 typedef List<CHookManagerInfo> HookManInfoList;
359 class CHookManagerContainer : public HookManInfoList
362 // HMCI (Hook Manager Container Identification)
369 HMCI(const char *proto, int vtbloffs, int vtblidx) :
370 m_Proto(proto), m_VtableOffset(vtbloffs), m_VtableIndex(vtblidx)
377 bool operator==(const HMCI &other) const
380 other.m_VtableIndex == m_VtableIndex &&
381 other.m_Proto == m_Proto &&
382 other.m_VtableOffset == m_VtableOffset;
385 const CProto &GetProto() const
389 int GetVtableOffset() const
391 return m_VtableOffset;
393 int GetVtableIndex() const
395 return m_VtableIndex;
401 CHookManagerContainer(const HMCI &hmci) : m_HCMI(hmci)
404 bool operator == (const HMCI &other) const
406 return m_HCMI == other;
408 void AddHookManager(Plugin plug, const CHookManagerInfo &hookman);
411 class CCallClassImpl : public GenericCallClass
415 typedef SourceHook::CVector<void*> OrigFuncs;
416 typedef SourceHook::THash<int, OrigFuncs> OrigVTables;
418 void *m_Ptr; //!< Pointer to the actual object
419 size_t m_ObjSize; //!< Size of the instance
420 OrigVTables m_VT; //!< Info about vtables & functions
424 CCallClassImpl(void *ptr, size_t size);
425 virtual ~CCallClassImpl();
427 bool operator==(void *other)
429 return m_Ptr == other;
433 void *GetOrigFunc(int vtbloffs, int vtblidx);
435 void ApplyCallClassPatch(int vtbl_offs, int vtbl_idx, void *orig_entry);
436 void RemoveCallClassPatch(int vtbl_offs, int vtbl_idx);
440 * @brief A list of CallClass structures
442 typedef List<CCallClassImpl> Impl_CallClassList;
444 Impl_CallClassList m_CallClasses; //!< A list of already generated callclasses
447 * @brief A list of CHookManagerContainers
449 typedef List<CHookManagerContainer> HookManContList;
451 HookManContList m_HookMans; //!< A list of hook managers
460 bool recall; //!< True if we're in a recall, eh.
463 const void *pOrigRet;
467 typedef CStack<HookLoopInfo> HookLoopInfoStack;
469 void ApplyCallClassPatches(CCallClassImpl &cc);
470 void ApplyCallClassPatches(void *ifaceptr, int vtbl_offs, int vtbl_idx, void *orig_entry);
471 void RemoveCallClassPatches(void *ifaceptr, int vtbl_offs, int vtbl_idx);
473 void SetPluginPaused(Plugin plug, bool paused);
475 HookLoopInfoStack m_HLIStack;
478 virtual ~CSourceHookImpl();
481 * @brief Returns the interface version
483 int GetIfaceVersion();
486 * @brief Returns the implemnetation version
488 int GetImplVersion();
491 * @brief Make sure that a plugin is not used by any other plugins anymore, and unregister all its hook managers
493 void UnloadPlugin(Plugin plug);
496 * @brief Shut down the whole system, unregister all hook managers
498 void CompleteShutdown();
503 * @return True if the function succeeded, false otherwise
505 * @param plug The unique identifier of the plugin that calls this function
506 * @param iface The interface pointer
507 * @param ifacesize The size of the class iface points to
508 * @param myHookMan A hook manager function that should be capable of handling the function
509 * @param handler A pointer to a FastDelegate containing the hook handler
510 * @param post Set to true if you want a post handler
512 bool AddHook(Plugin plug, void *iface, int thisptr_offs, HookManagerPubFunc myHookMan, ISHDelegate *handler, bool post);
515 * @brief Removes a hook.
517 * @return True if the function succeeded, false otherwise
519 * @param plug The unique identifier of the plugin that calls this function
520 * @param iface The interface pointer
521 * @param thisptr_offs This pointer adjuster
522 * @param myHookMan A hook manager function that should be capable of handling the function
523 * @param handler A pointer to a FastDelegate containing the hook handler
524 * @param post Set to true if you want a post handler
526 bool RemoveHook(Plugin plug, void *iface, int thisptr_offs, HookManagerPubFunc myHookMan, ISHDelegate *handler, bool post);
529 * @brief Removes a hook.
531 * @ return True if the function succeeded, false otherwise
533 * @param info A RemoveHookInfo structure, describing the hook
535 bool RemoveHook(RemoveHookInfo info);
538 * @brief Checks whether a plugin has (a) hook manager(s) that is/are currently used by other plugins
540 * @param plug The unique identifier of the plugin in question
542 bool IsPluginInUse(Plugin plug);
545 * @brief Pauses all hooks of a plugin
547 * @param plug The unique identifier of the plugin
549 void PausePlugin(Plugin plug);
552 * @brief Unpauses all hooks of a plugin
554 * @param plug The unique identifier of the plugin
556 void UnpausePlugin(Plugin plug);
559 * @brief Return a pointer to a callclass. Generate a new one if required.
561 * @param iface The interface pointer
562 * @param size Size of the class instance
564 GenericCallClass *GetCallClass(void *iface, size_t size);
567 * @brief Release a callclass
569 * @param ptr Pointer to the callclass
571 virtual void ReleaseCallClass(GenericCallClass *ptr);
573 virtual void SetRes(META_RES res); //!< Sets the meta result
574 virtual META_RES GetPrevRes(); //!< Gets the meta result of the previously called handler
575 virtual META_RES GetStatus(); //!< Gets the highest meta result
576 virtual const void *GetOrigRet(); //!< Gets the original result. If not in post function, undefined
577 virtual const void *GetOverrideRet(); //!< Gets the override result. If none is specified, NULL
578 virtual void *GetIfacePtr(); //!< Gets the interface pointer
580 //////////////////////////////////////////////////////////////////////////
582 void HookLoopBegin(IIface *pIface); //!< Should be called when a hook loop begins
583 void HookLoopEnd(); //!< Should be called when a hook loop exits
584 void SetCurResPtr(META_RES *mres); //!< Sets pointer to the current meta result
585 void SetPrevResPtr(META_RES *mres); //!< Sets pointer to previous meta result
586 void SetStatusPtr(META_RES *mres); //!< Sets pointer to the status variable
587 void SetIfacePtrPtr(void **pp); //!< Sets pointer to the interface this pointer
588 void SetOrigRetPtr(const void *ptr); //!< Sets the original return pointer
589 void SetOverrideRetPtr(void *ptr); //!< Sets the override result pointer
590 bool ShouldContinue(); //!< Returns false if the hook loop should exit
593 * @brief Remove a hook manager. Auto-removes all hooks attached to it from plugin plug.
595 * @param plug The owner of the hook manager
596 * @param pubFunc The hook manager's info function
598 virtual void RemoveHookManager(Plugin plug, HookManagerPubFunc pubFunc);
599 virtual void RemoveHookManager(RemoveHookManInfo info);
601 virtual void DoRecall(); //!< Initiates a recall sequence
602 virtual void *GetOverrideRetPtr(); //!< Returns the pointer set by SetOverrideRetPtr
604 virtual void *SetupHookLoop(META_RES *statusPtr, META_RES *prevResPtr, META_RES *curResPtr,
605 void **ifacePtrPtr, const void *origRetPtr, void *overrideRetPtr);