-
Notifications
You must be signed in to change notification settings - Fork 19
Pawn natives
native bool:pawn_native_exists(const function[]);Returns true if the specified native function exists (i.e. provided by a module), false otherwise.
native bool:pawn_native_imported(const function[]);Returns true if the specified native function is used by the current script, false otherwise.
native bool:pawn_public_exists(const function[]);Returns true if the specified public function is defined in the current script, false otherwise.
native pawn_call_native(const function[], const format[], AnyTag:...);You can use this function to call a native function specified by its name. The native function doesn't have to be used in the script. format accepts the same specifiers as CallLocalFunction, but enhanced with a couple of new ones. This function raises an error if the function cannot be found or if the call resulted in an error.
Additional specifiers are S, which can be used for dynamic strings, v for passing a variant, l for passing a list of variants as the argument list, and L for passing a list of variants preceded by their formats.
The type of the variant determines whether it is to be passed by value or by reference. If the variant is a single cell, its value is passed directly to the function. If it is an array variant, the array will be copied to the AMX machine and its address passed to the function. Using *, a or s as the specifier will pass directly the reference to the variable to the native function, and thus doesn't need any length after it.
If + is the last specifier, the remaining arguments are passed directly to the function.
native pawn_call_public(const function[], const format[], AnyTag:...);This function calls a public function in the current script. Its behaviour is otherwise same as pawn_call_native.
native amx_err:pawn_try_call_native(const function[], &result, const format[], AnyTag:...);Similar to pawn_call_native, but any AMX error raised in the native function will be caught and returned.
native amx_err:pawn_try_call_native_msg(const function[], &result, msg[], msg_size=sizeof(msg), const format[]="", AnyTag:...);
native amx_err:pawn_try_call_native_msg_s(const function[], &result, &StringTag:msg, const format[], AnyTag:...);Like pawn_try_call_native but also stores the error message in msg.
native amx_err:pawn_try_call_public(const function[], &result, const format[], AnyTag:...);Similar to pawn_call_public, but any AMX error raised in the public function will be caught and returned.
native pawn_create_callback(const callback[], Expression:action);Creates a new callback (public function) in the current script and returns its index (suitable for amx_encode_public. When the callback is called, action is executed and given the arguments to the public function. The result of the expression is returned from the callback.
If the callback already exists, its existing index is returned. The new callback can be the target of pawn_register_callback.
native CallbackHandler:pawn_register_callback(const callback[], const handler[], handler_flags:flags=handler_default, const additional_format[]="", AnyTag:...);Registers a new handler for a callback specified by its name. The handler must be a public function, which will be called every time before callback is to be called in the script. Additional parameters may be prepended to the parameters of the callback, which could be used to keep a "state" together with the handler instance.
flags specify how the function should be handled. handler_return will place an additional by-ref parameter before the callback parameters to specify what should be returned from the callback. Specifying handler_args will allow the handler to modify the original arguments to the function on the stack, even if they are not by-ref.
In addition to common CallLocalFunction specifiers, additional_format also supports a (array, its size is implied as the next argument), and e (the new event ID, the same that the function returns).
If the handler returns a non-zero value, the base callback will not be executed (and the value will be returned from it if handler_return was not used). The base callback must be always present in the script.
native pawn_unregister_callback(CallbackHandler:id);Removes the handler specified by its ID so it will not be triggered anymore.
native NativeHook:pawn_add_hook(const function[], const format[], const handler[], const additional_format[]="", AnyTag:...);Dynamically hooks a native function with a custom handler. When the native function is called (in any script), handler will be called with the arguments passed according to format. The handler may call the original function with modified arguments, or return a new value without even calling the original function.
native NativeHook:pawn_add_filter(const function[], const format[], const handler[], filter_type:type=filter_in, const additional_format[]="", AnyTag:...);Registers a filter (a special type of hook) for a given native function. The type of the filter can be either filter_in (pre-hook) or filter_out (post-hook). The filter will be called every time the function is called (either before the call or after the call).
A by-ref argument is placed before the actual function arguments, which are also turned to by-ref to allow modifications. If the handler returns true, inner handlers or hooks (or the native function itself) will not be called, but outer output handlers may be still executed (depending on the order of registration).
native pawn_remove_hook(NativeHook:id);Removes a hook or a filter.
native List:pawn_get_args(const format[], bool:byref=false, level=0);Returns the arguments provided to the function at the given level (current if level is 0) as a heterogenous list of values based on the format. If byref is specified, the arguments will be read as references instead of values.
#define pawn_nameof(%0) ((tagof(%0)),_:_PP@REMOVE_COLON:(#%0))A macro that obtains the name of a symbol and checks its existence, e.g. pawn_nameof(OnPlayerConnect) resolves to "OnPlayerConnect", if the function exists. A tag name followed by a colon (:) is also allowed, in which case the colon is removed from the result.
#define pawn_cast<%0>(%1) (%0:_PP@TMP2=(%1))A generic macro that uses the implicit tag conversion operator on a value. pawn_cast<Float>(1) produces a value that is equal to the result of assigning 1 to a Float: variable.
#define pawn_ref<%0>(%1) (Ref<%0>:_pp_fake_cast(_:_PP@CAST[%0](%1)))A helper macro to create a Ref<T>: value from a T: value. These references are ignored by functions that invoke the aquire or release operations on them.
#define pawn_unref<%0>(%1) (%0:_pp_fake_cast(_:_PP@CAST[Ref<%0>](%1)))A helper macro to create a T: value from a Ref<T>: value.
native ArgTag:[2]pawn_arg_pack(AnyTag:value, tag_id=tagof(value));An auxiliary function used to implement heterogenous variadic functions like list_new_args. Combines value and tag_id into a single array which is returned directly. This way, when an argument is encapsulated in a call to this function, its tag is not lost.
native Guard:pawn_guard(AnyTag:value, tag_id=tagof(value));Creates a new guard for a specific resource. The guard is deleted when the context in which it was created is destroyed, usually when the current public function ends.
Since guards are attached to the current context, they are not freed if a task is being awaited, because the context is saved and restored when the task is completed. Guards cannot be used in a threaded block, because it has no context.
native Guard:pawn_guard_arr(AnyTag:value[], size=sizeof(value), tag_id=tagof(value));Creates a new guard for an array of resources (passed by value). Semantics akin to pawn_guard.
native bool:pawn_guard_valid(Guard:guard);Returns true if the guard is valid, or false otherwise.
native pawn_guard_free(Guard:guard);Deletes the guard and frees the resource.