[Half-Life AMXX] / include / hamsandwich.inc Repository:
ViewVC logotype

Annotation of /include/hamsandwich.inc

Parent Directory Parent Directory | Revision Log Revision Log


Revision 17 - (view) (download)

1 : ian 17 /**
2 :     * Ham Sandwich module include file.
3 :     * (c) 2007, The AMX Mod X Development Team
4 :     *
5 :     * -
6 :     * This program is free software; you can redistribute it and/or modify it
7 :     * under the terms of the GNU General Public License as published by the
8 :     * Free Software Foundation; either version 2 of the License, or (at
9 :     * your option) any later version.
10 :     *
11 :     * This program is distributed in the hope that it will be useful, but
12 :     * WITHOUT ANY WARRANTY; without even the implied warranty of
13 :     * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 :     * General Public License for more details.
15 :     *
16 :     * You should have received a copy of the GNU General Public License
17 :     * along with this program; if not, write to the Free Software Foundation,
18 :     * Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
19 :     *
20 :     * In addition, as a special exception, the author gives permission to
21 :     * link the code of this program with the Half-Life Game Engine ("HL
22 :     * Engine") and Modified Game Libraries ("MODs") developed by Valve,
23 :     * L.L.C ("Valve"). You must obey the GNU General Public License in all
24 :     * respects for all of the code used other than the HL Engine and MODs
25 :     * from Valve. If you modify this file, you may extend this exception
26 :     * to your version of the file, but you are not obligated to do so. If
27 :     * you do not wish to do so, delete this exception statement from your
28 :     * version.
29 :     */
30 :    
31 :     /**
32 :     * Ham Sandwich is a module that is used to hook and call virtual functions of
33 :     * entities.
34 :     * Virtual functions are mod-specific functions. This means that in order
35 :     * for this to work on a mod, it needs to be configured with the hamdata.ini
36 :     * file.
37 :     * Be very careful with parameter passing to these functions.
38 :     */
39 :    
40 :     #if defined _hamsandwich_included
41 :     #endinput
42 :     #endif
43 :     #define _hamsandwich_included
44 :    
45 :     #include <ham_const>
46 :    
47 :     #if AMXX_VERSION_NUM >= 175
48 :     #pragma reqlib hamsandwich
49 :     #if !defined AMXMODX_NOAUTOLOAD
50 :     #pragma loadlib hamsandwich
51 :     #endif
52 :     #else
53 :     #pragma library hamsandwich
54 :     #endif
55 :    
56 :     /**
57 :     * Hooks the virtual table for the specified entity class.
58 :     * An example would be: RegisterHam(Ham_TakeDamage, "player", "player_hurt");
59 :     * Look at the Ham enum for parameter lists.
60 :     *
61 :     * @param function The function to hook.
62 :     * @param EntityClass The entity classname to hook.
63 :     * @param callback The forward to call.
64 :     * @param post Whether or not to forward this in post.
65 :     * @return Returns a handle to the forward. Use EnableHamForward/DisableHamForward to toggle the forward on or off.
66 :     */
67 :     native HamHook:RegisterHam(Ham:function, const EntityClass[], const Callback[], Post=0);
68 :    
69 :     /**
70 :     * Hooks the virtual table for the specified entity's class.
71 :     * An example would be: RegisterHam(Ham_TakeDamage, id, "player_hurt");
72 :     * Look at the Ham enum for parameter lists.
73 :     * Note: This will cause hooks for the entire internal class that the entity is
74 :     * not exclusively for the provided entity.
75 :     *
76 :     * @param function The function to hook.
77 :     * @param EntityId The entity classname to hook.
78 :     * @param callback The forward to call.
79 :     * @param post Whether or not to forward this in post.
80 :     * @return Returns a handle to the forward. Use EnableHamForward/DisableHamForward to toggle the forward on or off.
81 :     */
82 :     native HamHook:RegisterHamFromEntity(Ham:function, EntityId, const Callback[], Post=0);
83 :    
84 :    
85 :     /**
86 :     * Stops a ham forward from triggering.
87 :     * Use the return value from RegisterHam as the parameter here!
88 :     *
89 :     * @param fwd The forward to stop.
90 :     */
91 :     native DisableHamForward(HamHook:fwd);
92 :    
93 :     /**
94 :     * Starts a ham forward back up.
95 :     * Use the return value from RegisterHam as the parameter here!
96 :     *
97 :     * @param fwd The forward to re-enable.
98 :     */
99 :     native EnableHamForward(HamHook:fwd);
100 :    
101 :     /**
102 :     * Executes the virtual function on the entity.
103 :     * Look at the Ham enum for parameter lists.
104 :     *
105 :     * @param function The function to call.
106 :     * @param id The id of the entity to execute it on.
107 :     */
108 :     native ExecuteHam(Ham:function, this, any:...);
109 :    
110 :     /**
111 :     * Executes the virtual function on the entity, this will trigger all hooks on that function.
112 :     * Be very careful about recursion!
113 :     * Look at the Ham enum for parameter lists.
114 :     *
115 :     * @param function The function to call.
116 :     * @param id The id of the entity to execute it on.
117 :     */
118 :     native ExecuteHamB(Ham:function, this, any:...);
119 :    
120 :     /**
121 :     * Gets the return status of the current hook.
122 :     * This is useful to determine what return natives to use.
123 :     *
124 :     * @return The current status of the hook (such as HAM_SUPERCEDE).
125 :     */
126 :     native GetHamReturnStatus();
127 :    
128 :     /**
129 :     * Gets the return value of a hook for hooks that return integers or booleans.
130 :     *
131 :     * @param output The variable to store the value in.
132 :     */
133 :     native GetHamReturnInteger(&output);
134 :    
135 :     /**
136 :     * Gets the return value of a hook for hooks that return float.
137 :     *
138 :     * @param output The variable to store the value in.
139 :     */
140 :     native GetHamReturnFloat(&Float:output);
141 :    
142 :     /**
143 :     * Gets the return value of a hook for hooks that return Vectors.
144 :     *
145 :     * @param output The variable to store the value in.
146 :     */
147 :     native GetHamReturnVector(Float:output[3]);
148 :    
149 :     /**
150 :     * Gets the return value of a hook for hooks that return entities.
151 :     *
152 :     * @param output The variable to store the value in. Will be -1 on null.
153 :     */
154 :     native GetHamReturnEntity(&output);
155 :    
156 :     /**
157 :     * Gets the return value of a hook for hooks that return strings.
158 :     *
159 :     * @param output The buffer to store the string in.
160 :     * @param size The string size of the buffer.
161 :     */
162 :     native GetHamReturnString(output[], size);
163 :    
164 :     /**
165 :     * Gets the original return value of a hook for hooks that return integers or booleans.
166 :     *
167 :     * @param output The variable to store the value in.
168 :     */
169 :     native GetOrigHamReturnInteger(&output);
170 :    
171 :     /**
172 :     * Gets the original return value of a hook for hooks that return floats.
173 :     *
174 :     * @param output The variable to store the value in.
175 :     */
176 :     native GetOrigHamReturnFloat(&Float:output);
177 :    
178 :     /**
179 :     * Gets the original return value of a hook for hooks that return Vectors.
180 :     *
181 :     * @param output The variable to store the value in.
182 :     */
183 :     native GetOrigHamReturnVector(Float:output[3]);
184 :    
185 :     /**
186 :     * Gets the original return value of a hook for hooks that return entities.
187 :     *
188 :     * @param output The variable to store the value in. -1 on null.
189 :     */
190 :     native GetOrigHamReturnEntity(&output);
191 :    
192 :     /**
193 :     * Gets the original return value of a hook for hooks that return strings.
194 :     *
195 :     * @param output The buffer to store the string in.
196 :     * @param size The size of the buffer.
197 :     */
198 :     native GetOrigHamReturnString(output[], size);
199 :    
200 :    
201 :     /**
202 :     * Sets the return value of a hook that returns an integer or boolean.
203 :     * This needs to be used in conjunction with HAM_OVERRIDE or HAM_SUPERCEDE.
204 :     *
205 :     * @param value The value to set the return to.
206 :     */
207 :     native SetHamReturnInteger(value);
208 :    
209 :     /**
210 :     * Sets the return value of a hook that returns a float.
211 :     * This needs to be used in conjunction with HAM_OVERRIDE or HAM_SUPERCEDE.
212 :     *
213 :     * @param value The value to set the return to.
214 :     */
215 :     native SetHamReturnFloat(Float:value);
216 :    
217 :     /**
218 :     * Sets the return value of a hook that returns a Vector.
219 :     * This needs to be used in conjunction with HAM_OVERRIDE or HAM_SUPERCEDE.
220 :     *
221 :     * @param value The value to set the return to.
222 :     */
223 :     native SetHamReturnVector(const Float:value[3]);
224 :    
225 :     /**
226 :     * Sets the return value of a hook that returns an entity. Set to -1 for null.
227 :     * This needs to be used in conjunction with HAM_OVERRIDE or HAM_SUPERCEDE.
228 :     *
229 :     * @param value The value to set the return to.
230 :     */
231 :     native SetHamReturnEntity(value);
232 :    
233 :     /**
234 :     * Sets the return value of a hook that returns a string.
235 :     * This needs to be used in conjunction with HAM_OVERRIDE or HAM_SUPERCEDE.
236 :     *
237 :     * @param value The value to set the return to.
238 :     */
239 :     native SetHamReturnString(const value[]);
240 :    
241 :    
242 :     /**
243 :     * Sets a parameter on the fly of the current hook. This has no effect in post hooks.
244 :     * Use this on parameters that are integers.
245 :     *
246 :     * @param which Which parameter to change. Starts at 1, and works up from the left to right. 1 is always "this".
247 :     * @param value The value to change it to.
248 :     */
249 :     native SetHamParamInteger(which, value);
250 :    
251 :     /**
252 :     * Sets a parameter on the fly of the current hook. This has no effect in post hooks.
253 :     * Use this on parameters that are floats.
254 :     *
255 :     * @param which Which parameter to change. Starts at 1, and works up from the left to right. 1 is always "this".
256 :     * @param value The value to change it to.
257 :     */
258 :     native SetHamParamFloat(which, Float:value);
259 :    
260 :     /**
261 :     * Sets a parameter on the fly of the current hook. This has no effect in post hooks.
262 :     * Use this on parameters that are Vectors.
263 :     *
264 :     * @param which Which parameter to change. Starts at 1, and works up from the left to right. 1 is always "this".
265 :     * @param value The value to change it to.
266 :     */
267 :     native SetHamParamVector(which, const Float:value[3]);
268 :    
269 :     /**
270 :     * Sets a parameter on the fly of the current hook. This has no effect in post hooks.
271 :     * Use this on parameters that are entities.
272 :     *
273 :     * @param which Which parameter to change. Starts at 1, and works up from the left to right. 1 is always "this".
274 :     * @param value The value to change it to.
275 :     */
276 :     native SetHamParamEntity(which, value);
277 :    
278 :     /**
279 :     * Sets a parameter on the fly of the current hook. This has no effect in post hooks.
280 :     * Use this on parameters that are strings.
281 :     *
282 :     * @param which Which parameter to change. Starts at 1, and works up from the left to right. 1 is always "this".
283 :     * @param value The value to change it to.
284 :     */
285 :     native SetHamParamString(which, const output[]);
286 :    
287 :     /**
288 :     * Sets a parameter on the fly of the current hook. This has no effect in post hooks.
289 :     * Use this on parameters that are trace result handles.
290 :     *
291 :     * @param which Which parameter to change. Starts at 1, and works up from the left to right. 1 is always "this".
292 :     * @param value The value to change it to.
293 :     */
294 :     native SetHamParamTraceResult(which, tr_handle);
295 :    
296 :    
297 :     /**
298 :     * Returns whether or not the function for the specified Ham is valid.
299 :     * Things that would make it invalid would be bounds (an older module version
300 :     * may not have all of the functions), and the function not being found in
301 :     * the mod's hamdata.ini file.
302 :     *
303 :     * @param function The function to look up.
304 :     * @return true if the function is valid, false otherwise.
305 :     */
306 :     native bool:IsHamValid(Ham:function);
307 :    
308 :     /**
309 :     * This is used to compliment fakemeta's {get,set}_pdata_{int,float,string}.
310 :     * This requires the mod to have the pev and base fields set in hamdata.ini.
311 :     * Note this dereferences memory! Improper use of this will crash the server.
312 :     * This will return an index of the corresponding cbase field in private data.
313 :     * Returns -1 on a null entry.
314 :     *
315 :     * @param id The entity to examine the private data.
316 :     * @param offset The windows offset of the data.
317 :     * @param linuxdiff The linux difference of the data.
318 :     * @return The index of the corresponding pdata field. -1 for none set.
319 :     */
320 :     native get_pdata_cbase(id, offset, linuxdiff=5);
321 :    
322 :     /**
323 :     * This is used to compliment fakemeta's {get,set}_pdata_{int,float,string}.
324 :     * This requires the mod to have the pev and base fields set in hamdata.ini.
325 :     * This will set the corresponding cbase field in private data with the index.
326 :     * Pass -1 to null the entry.
327 :     *
328 :     * @param id The entity to examine the private data.
329 :     * @param offset The windows offset of the data.
330 :     * @param value The index to store, -1 for invalid
331 :     * @param linuxdiff The linux difference of the data.
332 :     */
333 :     native set_pdata_cbase(id, offset, value, linuxdiff=5);
334 :    
335 :     /**
336 :     * This is similar to the get_pdata_cbase, however it does not dereference memory.
337 :     * This is many times slower than get_pdata_cbase, and this should only be used
338 :     * for testing and finding of offsets, not actual release quality plugins.
339 :     * This will return an index of the corresponding cbase field in private data.
340 :     * Returns -1 on a null entry. -2 on an invalid entry.
341 :     *
342 :     * @param id Entry to examine the private data.
343 :     * @param offset The windows offset of the data.
344 :     * @param linuxdiff The linux difference of the data.
345 :     * @return The index of the corresponding pdata field, -1 for null, -2 for invalid.
346 :     */
347 :     native get_pdata_cbase_safe(id, offset, linuxdiff=5);
348 :    
349 :    
350 :    
351 :    
352 :     // This is the callback from the module, this handles any fatal errors.
353 :     // This will in turn call the "HamFilter(Ham:id, HamError:err, const reason[])" public, if it exists.
354 :     // Return PLUGIN_HANDLED from within the HamFilter to stop the plugin from failing.
355 :     // Any other return value will fail the plugin.
356 :     // You do not need to have a HamFilter, if there is none, all fatal errors will fail the plugin.
357 :     // Do not modify this!
358 :     public __fatal_ham_error(Ham:id, HamError:err, const reason[])
359 :     {
360 :    
361 :     new func=get_func_id("HamFilter", -1);
362 :     new bool:fail=true;
363 :    
364 :     if (func != -1 && callfunc_begin_i(func, -1)==1)
365 :     {
366 :     callfunc_push_int(_:id);
367 :     callfunc_push_int(_:err);
368 :     callfunc_push_str(reason, false);
369 :     if (callfunc_end()==PLUGIN_HANDLED)
370 :     {
371 :     fail=false;
372 :     }
373 :     }
374 :     if (fail)
375 :     {
376 :     set_fail_state(reason);
377 :     }
378 :    
379 :     }

Contact
ViewVC Help
Powered by ViewVC 1.0.4