Flummi/amxmodx
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Update include files documentation (#360)

Browse Source 
* Update include files documentation

* Fix inconcistencies with spaces/tabs, some changes

* Update fun, nvault, vector

* Update sqlx.inc
This commit is contained in:
KliPPy 2017-12-09 00:22:43 +01:00 committed by Vincent Herbet
parent 5632420827
commit 7b3646a012
7 changed files with 1508 additions and 381 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

311
plugins/include/float.inc
View File

@ -13,7 +13,11 @@
#endif
#define _float_included
/* Different methods of rounding */
#pragma rational Float
/**
* Different methods of rounding
*/
enum floatround_method {
floatround_round = 0,
floatround_floor,
@ -21,19 +25,242 @@ enum floatround_method {
floatround_tozero
};
/**
* Different units of measurement for angles
*/
enum anglemode {
radian = 0,
degrees,
grades
};
/* Convert an integer into a floating point value */
/**
* Converts an integer into a floating point value.
*
* @param value Value to be converted
*
* @return Converted value
*/
native Float:float(value);
/* Convert a string into a floating point value */
/**
* Converts a string into a floating point value.
*
* @param string Input string to be converted
*
* @return Converted value
*/
native Float:floatstr(const string[]);
/* Multiple two floats together */
/**
* Returns the fractional part of a floating point value
*
* @param string Floating point value to get the fractional part from
*
* @return The fractional part
*/
native Float:floatfract(Float:value);
/**
* Rounds a floating point value to an integer value
*
* @note For the list of available rounding methods look at
* floatround_method enumeration.
*
* @param value Floating point value to be rounded
* @param method Rounding method
*
* @return Converted value
*/
native floatround(Float:value, floatround_method:method=floatround_round);
/**
* Compares two floating point values.
*
* @param fOne First value to be compared
* @param fTwo Second value to be compared
*
* @return If arguments are equal, returns 0.
* If the first one is greater, returns 1.
* If the second one is greater, returns -1.
*/
native floatcmp(Float:fOne, Float:fTwo);
/**
* Returns the square root of a floating point value
*
* @note Same as floatpower(value, 0.5)
*
* @param value Floating point value to get square root from
*
* @return Square root of the input value
*/
native Float:floatsqroot(Float:value);
/**
* Returns the value raised to the power of the exponent
*
* @param value Floating point value to be raised
* @param exponent The exponent
*
* @return Value raised to the power of the exponent
*/
native Float:floatpower(Float:value, Float:exponent);
/**
* Returns the logarithm of value
*
* @param value Floating point value to calculate the logarithm for
* @param base The optional logarithmic base to use.
* Defaults to 10, or the natural logarithm
*
* @return Square root of the input value
*/
native Float:floatlog(Float:value, Float:base=10.0);
/**
* Returns the sine of a given angle
*
* @note For available units of measurements(modes) look at the anglemode enum
*
* @param value The angle to calculate the sine from
* @param mode What unit of measurement is the angle specified in
* Defaults to radians
*
* @return The sine of a given angle
*/
native Float:floatsin(Float:value, anglemode:mode=radian);
/**
* Returns the cosine of a given angle
*
* @note For available units of measurements(modes) look at the anglemode enum
*
* @param value The angle to calculate the cosine from
* @param mode What unit of measurement is the angle specified in
* Defaults to radians
*
* @return The cosine of a given angle
*/
native Float:floatcos(Float:value, anglemode:mode=radian);
/**
* Returns the tangent of a given angle
*
* @note For available units of measurements(modes) look at the anglemode enum
*
* @param value The angle to calculate the tangent from
* @param mode What unit of measurement is the angle specified in
* Defaults to radians
*
* @return The tangent of a given angle
*/
native Float:floattan(Float:value, anglemode:mode=radian);
/**
* Returns the hyperbolic sine of a given angle
*
* @note For available units of measurements(modes) look at the anglemode enum
*
* @param value The angle to calculate the hyperbolic sine from
* @param mode What unit of measurement is the angle specified in
* Defaults to radians
*
* @return The hyperbolic sine of a given angle
*/
native Float:floatsinh(Float:angle, anglemode:mode=radian);
/**
* Returns the hyperbolic cosine of a given angle
*
* @note For available units of measurements(modes) look at the anglemode enum
*
* @param value The angle to calculate the hyperbolic cosine from
* @param mode What unit of measurement is the angle specified in
* Defaults to radians
*
* @return The hyperbolic cosine of a given angle
*/
native Float:floatcosh(Float:angle, anglemode:mode=radian);
/**
* Returns the hyperbolic tangent of a given angle
*
* @note For available units of measurements(modes) look at the anglemode enum
*
* @param value The angle to calculate the hyperbolic tangent from
* @param mode What unit of measurement is the angle specified in
* Defaults to radians
*
* @return The hyperbolic tangent of a given angle
*/
native Float:floattanh(Float:angle, anglemode:mode=radian);
/**
* Returns the absolute value of a floating point value
*
* @param value The floating point value to get the absolute value from
*
* @return The absolute value
*/
native Float:floatabs(Float:value);
/* Return the angle of a sine, cosine or tangent.
* The output angle may be in radians, degrees, or grades. */
/**
* Returns the angle of the given tangent
*
* @note For available units of measurements(modes) look at the anglemode enum
*
* @param value The tangent to calculate the angle from
* @param mode What unit of measurement should the output angle be in
*
* @return The angle of a tangent
*/
native Float:floatatan(Float:angle, {anglemode,_}:radix);
/**
* Returns the angle of the given cosine
*
* @note For available units of measurements(modes) look at the anglemode enum
*
* @param value The cosine to calculate the angle from
* @param mode What unit of measurement should the output angle be in
*
* @return The angle of a cosine
*/
native Float:floatacos(Float:angle, {anglemode,_}:radix);
/**
* Returns the angle of the given sine
*
* @note For available units of measurements(modes) look at the anglemode enum
*
* @param value The sine to calculate the angle from
* @param mode What unit of measurement should the output angle be in
*
* @return The angle of a sine
*/
native Float:floatasin(Float:angle, {anglemode,_}:radix);
/**
* Computes the principal value of arctangent of y/x
*
* @note Someone should verify this native, not sure what it actually does.
* @note For available units of measurements(modes) look at the anglemode enum
*
* @param x Value representing the proportion of the x-coordinate.
* @param y Value representing the proportion of the x-coordinate.
* @param mode What unit of measurement should the output angle be in
*
* @return Arctangent of y/x
*/
native Float:floatatan2(Float:x, Float:y, {anglemode,_}:radix);
/* Multiply two floats together */
native Float:floatmul(Float:oper1, Float:oper2);
/* Divide the dividend float by the divisor float */
@ -45,50 +272,6 @@ native Float:floatadd(Float:dividend, Float:divisor);
/* Subtract oper2 float from oper1 float */
native Float:floatsub(Float:oper1, Float:oper2);
/* Return the fractional part of a float */
native Float:floatfract(Float:value);
/* Round a float into a integer value */
native floatround(Float:value, floatround_method:method=floatround_round);
/* Compare two integers. If the two elements are equal, return 0.
* If the first argument is greater than the second argument, return 1,
* If the first argument is less than the second argument, return -1. */
native floatcmp(Float:fOne, Float:fTwo);
/* Return the square root of the input value, same as floatpower(value, 0.5) */
native Float:floatsqroot(Float:value);
/* Return the value raised to the power of the exponent */
native Float:floatpower(Float:value, Float:exponent);
/* Return the logarithm */
native Float:floatlog(Float:value, Float:base=10.0);
/* Return the sine, cosine or tangent.
* The input angle may be in radians, degrees or grades. */
native Float:floatsin(Float:value, anglemode:mode=radian);
native Float:floatcos(Float:value, anglemode:mode=radian);
native Float:floattan(Float:value, anglemode:mode=radian);
/* Return the hyperbolic sine, cosine or tangent.
* The input angle may be in radians, degrees or grades. */
native Float:floatsinh(Float:angle, anglemode:mode=radian);
native Float:floatcosh(Float:angle, anglemode:mode=radian);
native Float:floattanh(Float:angle, anglemode:mode=radian);
/* Return the absolute value */
native Float:floatabs(Float:value);
/* Return the angle of a sine, cosine or tangent.
* The output angle may be in radians, degrees, or grades. */
native Float:floatatan(Float:angle, {anglemode,_}:radix);
native Float:floatacos(Float:angle, {anglemode,_}:radix);
native Float:floatasin(Float:angle, {anglemode,_}:radix);
native Float:floatatan2(Float:x, Float:y, {anglemode,_}:radix);
#pragma rational Float
/* user defined operators */
native Float:operator*(Float:oper1, Float:oper2) = floatmul;
native Float:operator/(Float:oper1, Float:oper2) = floatdiv;
@ -171,14 +354,22 @@ stock bool:operator<=(oper1, Float:oper2)
return floatcmp(float(oper1), oper2) <= 0;
stock bool:operator!(Float:oper)
return (_:oper & ((-1)/2)) == 0; /* -1 = all bits to 1; /2 = remove most significant bit (sign)
works on both 32bit and 64bit systems; no constant required */
return (_:oper & ((-1)/2)) == 0; /* -1 = all bits to 1; /2 = remove most significant bit (sign)
works on both 32bit and 64bit systems; no constant required */
/* forbidden operations */
forward operator%(Float:oper1, Float:oper2);
forward operator%(Float:oper1, oper2);
forward operator%(oper1, Float:oper2);
/**
* Returns whichever value is the smaller one
*
* @param ValueA The first value
* @param ValueB The second value
*
* @return ValueA if it is smaller than ValueB, and vice versa
*/
stock Float:floatmin(Float:ValueA, Float:ValueB)
{
if (ValueA<=ValueB)
@ -189,6 +380,14 @@ stock Float:floatmin(Float:ValueA, Float:ValueB)
return ValueB;
}
/**
* Returns whichever value is the greater one
*
* @param ValueA The first value
* @param ValueB The second value
*
* @return ValueA if it is greater than ValueB, and vice versa
*/
stock Float:floatmax(Float:ValueA, Float:ValueB)
{
if (ValueA>=ValueB)
@ -198,6 +397,16 @@ stock Float:floatmax(Float:ValueA, Float:ValueB)
return ValueB;
}
/**
* Clamps a value between a minimum and a maximum floating point value
*
* @param Value The value to be clamped
* @param MinValue Minimum value
* @param MaxValue Maximum value
*
* @return The Value clamped between MinValue and MaxValue
*/
stock Float:floatclamp(Float:Value, Float:MinValue, Float:MaxValue)
{
if (Value<=MinValue)
@ -210,4 +419,4 @@ stock Float:floatclamp(Float:Value, Float:MinValue, Float:MaxValue)
}
return Value;
}
}

273
plugins/include/fun.inc
View File

@ -21,81 +21,284 @@
#pragma loadlib fun
#endif
/* Returns 1 if receiver hears sender via voice communication. */
/**
* Tells whether receiver hears sender via voice communication.
*
* @param receiver Receiver
* @param sender Sender
*
* @return 1 if receiver hears the sender, 0 otherwise.
* @error If receiver or sender are not connected or not
* within the range of 1 to MaxClients.
*/
native get_client_listen(receiver, sender);
/* Sets who can listen who. Function returns 0
* if for some reasons this setting can't be done. */
/**
* Sets who can listen who.
*
* @param receiver Receiver
* @param sender Sender
* @param listen 1 if receiver should be able to hear sender, 0 if not
*
* @return 0 if the setting can't be done for some reason.
* @error If receiver or sender are not connected or not
* within the range of 1 to MaxClients.
*/
native set_client_listen(receiver, sender, listen);
/* Sets player godmode. If you want to disable godmode set only first parameter. */
/**
* Sets player's godmode
*
* @param index Client index
* @param godmode 1 to enable godmode, 0 to disable
*
* @noreturn
* @error If player is not connected or not within the range
* of 1 to MaxClients.
*/
native set_user_godmode(index, godmode = 0);
/* Returns 1 if godmode is set. */
/**
* Tells whether a player has godmode on
*
* @param index Client index
*
* @return 1 if player has godmode on, 0 if not
* @error If player is not connected or not within the range
* of 1 to MaxClients.
*/
native get_user_godmode(index);
/* Sets player armor. */
/**
* Sets player's armor amount
*
* @param index Client index
* @param armor The armor amount to set
*
* @noreturn
* @error If player is not connected or not within the range
* of 1 to MaxClients.
*/
native set_user_armor(index, armor);
/* Sets player health. */
/**
* Sets player's health amount
*
* @param index Client index
* @param health The health amount to set
*
* @noreturn
* @error If player is not connected or not within the range
* of 1 to MaxClients.
*/
native set_user_health(index, health);
/* Move player to origin. */
/**
* Moves a player to the given origin
*
* @param index Client index
* @param origin Origin to move a player to
*
* @noreturn
* @error If player is not connected or not within the range
* of 1 to MaxClients.
*/
native set_user_origin(index, const origin[3]);
/* Sets player rendering mode. */
/**
* Sets player's rendering mode
*
* @note A really useful render modes reference:
* https://sites.google.com/site/svenmanor/rendermodes
*
* @param index Client index
* @param fx Rendering effects. One of kRenderFx* constants.
* @param r The amount of red color (0 to 255)
* @param g The amount of green color (0 to 255)
* @param b The amount of blue color (0 to 255)
* @param render Render mode. One of kRender* constants.
* @param amount Render amount (0 to 255)
*
* @noreturn
* @error If player is not connected or not within the range
* of 1 to MaxClients.
*/
native set_user_rendering(index, fx = kRenderFxNone, r = 0, g = 0, b = 0, render = kRenderNormal, amount = 0);
/* Gives item to player, name of item can start
* with weapon_, ammo_ and item_. This event
* is announced with proper message to all players. */
/**
* Gives an item to a player.
*
* @param index Client index
* @param item Classname of the item to give. Should start with either
* "weapon_", "ammo_", "item_" or "tf_weapon_".
*
* @noreturn
* @error If player is not connected or not within the range
* of 1 to MaxClients or item creation fails.
*/
native give_item(index, const item[]);
/* Sets hit zones for player.
* Parts of body are as bits:
* 1 - generic
* 2 - head
* 4 - chest
* 8 - stomach
* 16 - left arm
* 32 - right arm
* 64 - left leg
* 128 - right leg */
/**
* Sets (adds, removes) hit zones for a player.
*
* @note This actually set rules of how any player can hit any other. Example:
* set_user_hitzones(id, target, 2);
* makes @id be able to hit @target only in the head.
*
* @param index Client index
* @param target The target player
* @param body A bitsum of the body parts that can/can't be shot.
* 1 generic
* 2 - head
* 4 - chest
* 8 - stomach
* 16 - left arm
* 32 - right arm
* 64 - left leg
* 128 - right leg
*
* @noreturn
* @error If player is not connected or not within the range
* of 1 to MaxClients.
*/
native set_user_hitzones(index = 0, target = 0, body = 255);
/* Get user hitzones. */
/**
* Gets the set of hit zone "rules" between @index and @target players.
*
* @note For the body part bitsum take a look at the set_user_hitzones() native.
*
* @param index Client index
* @param target The target player
*
* @return The bitsum of @target's body parts @index is able to hit
* @error If player is not connected or not within the range
* of 1 to MaxClients.
*/
native get_user_hitzones(index, target);
/* Sets users max. speed. */
/**
* Sets player's maximum movement speed
*
* @param index Client index
* @param speed The maximum speed player will be able to run at
*
* @noreturn
* @error If player is not connected or not within the range
* of 1 to MaxClients.
*/
native set_user_maxspeed(index, Float:speed = -1.0);
/* Returns users max. speed. */
/**
* Gets player's maximum movement speed
*
* @param index Client index
*
* @return Player's maximum movement speed
* @error If player is not connected or not within the range
* of 1 to MaxClients.
*/
native Float:get_user_maxspeed(index);
/* Sets users gravity. */
/**
* Sets player's gravity
*
* @param index Client index
* @param gravity Gravity value to set, 1.0 being normal gravity (800)
*
* @noreturn
* @error If player is not connected or not within the range
* of 1 to MaxClients.
*/
native set_user_gravity(index, Float:gravity = 1.0);
/* Returns users gravity. */
/**
* Gets player's gravity
*
* @param index Client index
*
* @return Player's gravity value, 1.0 being normal gravity (800)
* @error If player is not connected or not within the range
* of 1 to MaxClients.
*/
native Float:get_user_gravity(index);
/* Spawns entity. */
/**
* Spawns an entity
*
* @param index Entity index
*
* @noreturn
* @error If player is not connected or not within the range
* of 1 to MaxClients.
*/
native spawn(index);
/* Sets player noclip. If you want to disable noclip set only first parameter. */
/**
* Sets player's noclip
*
* @param index Client index
* @param noclip 1 to enable noclip, 0 to disable
*
* @noreturn
* @error If player is not connected or not within the range
* of 1 to MaxClients.
*/
native set_user_noclip(index, noclip = 0);
/* Returns 1 if noclip is set. */
/**
* Gets player's noclip
*
* @param index Client index
*
* @return 1 if noclip is enabled, 0 if disabled
* @error If player is not connected or not within the range
* of 1 to MaxClients.
*/
native get_user_noclip(index);
/* Returns 1 if player has silent footsteps, 0 if footsteps are set to normal */
/**
* Tells whether a player has silent footsteps
*
* @param index Client index
*
* @return 1 if silent footsteps are enabled, 0 if not
* @error If player is not connected or not within the range
* of 1 to MaxClients.
*/
native get_user_footsteps(index);
/* Gives player silent footsteps.
* if set = 0 it will return footsteps to normal */
/**
* Sets player's silent footsteps
*
* @param index Client index
* @param set 1 if player should have silent footsteps, 0 otherwise
*
* @noreturn
* @error If player is not connected or not within the range
* of 1 to MaxClients.
*/
native set_user_footsteps(id, set = 1);
/* Strips all weapons from user. */
/**
* Strips all weapons from a player, including their knife.
*
* @param index Client index
*
* @noreturn
* @error If player is not connected or not within the range
* of 1 to MaxClients.
*/
native strip_user_weapons(index);
/* Sets player frags. */
/**
* Sets player's frags amount
*
* @param index Client index
* @param frags The amount of frags to set
*
* @noreturn
* @error If player is not connected or not within the range
* of 1 to MaxClients.
*/
native set_user_frags(index, frags);

122
plugins/include/nvault.inc
View File

@ -21,43 +21,131 @@
#pragma loadlib nvault
#endif
/* All timestamps are in UNIX epoch form. */
/**
* @global All timestamps are in UNIX epoch form.
*/
/* Opens a vault by name (such as "myvault")
* Returns a vault id, INVALID_HANDLE otherwise (-1)
/**
* Opens a vault by name. Creates a vault if it doesn't exist yet.
*
* @param name Name of the vault. The vault will be created in
* ${amxx_datadir}/vault directory.
*
* @return The vault handle to be used in other natives.
* INVALID_HANDLE (-1) if not successfully opened.
*/
native nvault_open(const name[]);
/* Gets a vault value by returning an int
* setting a byref float or setting a string + maxlength
/**
* Retrieves a value from the given key
*
* @note An example of retrieving a string:
* nvault_get(vaultHandle, "myKey", myString, charsmax(myString));
*
* @param vault A vault handle returned from nvault_open()
* @param key A key to get the value from
* @param ... If three argument are given, gets a float value and
* puts it in the third argument by reference.
* If four arguments are given, gets a string from the
* vault and copies it to the third argument, up to
* 4th argument characters.
*
* @noreturn
* @error On invalid vault handle.
*/
native nvault_get(vault, const key[], any:...);
/* Looks up a vault value for full information
* Returns 0 if the entry is not found
/**
* Retrieves full information about a vault entry
*
* @param vault A vault handle returned from nvault_open()
* @param key A key to get information from
* @param value A string where the value should be stored
* @param maxlen Maximum length of the @value string
* @param timestamp The timestamp of the entry
*
* @return 1 if an entry was found, 0 otherwise.
* @error On invalid vault handle.
*/
native nvault_lookup(vault, const key[], value[], maxlen, &timestamp);
/* Sets a vault value (with current timestamp) */
/**
* Sets value of a vault entry and updates the timestamp.
*
* @note A new entry is created if one with the given key doesn't exist.
*
* @param vault A vault handle returned from nvault_open()
* @param key A key to set the value for
* @param value A value to set
*
* @noreturn
* @error On invalid vault handle.
*/
native nvault_set(vault, const key[], const value[]);
/* Sets a permanent vault value (no timestamp) */
/**
* Sets value of a vault entry and makes it permanent (non-erasable with nvault_prune()).
*
* @note A new entry is created if one with the given key doesn't exist.
* @note Permanent entries have no timestamp.
*
* @param vault A vault handle returned from nvault_open()
* @param key A key to set the permanent value for
* @param value A permanent value to set
*
* @noreturn
* @error On invalid vault handle.
*/
native nvault_pset(vault, const key[], const value[]);
/* Prunes the vault for entries that are within the given timestamps.
* This will not erase values set with pset
/**
* Prunes the vault for entries that are within the given timestamps.
*
* @note This will not erase values set with nvault_pset().
* @note An example of pruning all entries that are older than 24 hours:
* nvault_prune(vaultHandle, 0, get_systime() - (60 * 60 * 24));
*
* @param vault A vault handle returned from nvault_open()
* @param start The timestamp to start erasing from
* @param end The timestamp to erase to
*
* @noreturn
* @error On invalid vault handle.
*/
native nvault_prune(vault, start, end);
/* Closes a vault */
/**
* Closes a vault.
*
* @param vault A vault handle returned from nvault_open()
*
* @noreturn
* @error On invalid vault handle.
*/
native nvault_close(vault);
/* Removes a key from the vault */
/**
* Removes an entry from the vault by its key.
*
* @param vault A vault handle returned from nvault_open()
* @param key The key to remove from the vault
*
* @noreturn
* @error On invalid vault handle.
*/
native nvault_remove(vault, const key[]);
/* "Touches" a key to update its timestamp value.
* If stamp is -1 (default), it will use the current time.
* Like the unix command "touch," it will create an empty key
* if the value does not exist.
/**
* "Touches" an entry in the vault, updating its timestamp.
*
* @note If timestamp is equal to -1, it will use the current time.
* @note An empty entry is created if one with the given key doesn't exist.
*
* @param vault A vault handle returned from nvault_open()
* @param key The key to search for
* @param timestamp Update an entry's timestamp to this one. Default is -1.
*
* @noreturn
* @error On invalid vault handle.
*/
native nvault_touch(vault, const key[], timestamp=-1);

4
plugins/include/sockets.inc
View File

@ -96,6 +96,10 @@ native socket_close(_socket);
*
* @note The amount of bytes than you end up receiving can be less than the one you expected.
*
* @note This function will completely block the server until some data arrives
* to the given socket. Use this only if you are sure there is some data
* to be retrieved. You can do that by polling with socket_is_readable().
*
* @param _socket Socket descriptor
* @param _data Array to save the data
* @param _length Length of the array

404
plugins/include/sqlx.inc
View File

@ -30,33 +30,49 @@ enum Handle
};
/**
* Creates a connection information tuple.
* This tuple must be passed into connection routines.
* Freeing the tuple is not necessary, but is a good idea if you
* create many of them. You can cache these handles globally.
* !!NOTE!! I have seen most people think that this connects to the DB.
* Nowhere does it say this, and in fact it does not. It only caches
* the connection information, the host/user/pass/etc.
*
* The optional timeout parameter specifies how long connections should wait before
* giving up. If 0, the default (which is undefined) is used.
*
* Creates a connection information tuple. This tuple must be passed
* into connection routines.
*
* @note Freeing the tuple is not necessary, but is a good idea if you create
* many of them. You can cache these handles globally.
* @note This does not connect to the DB; it only caches the connection information.
*
* @param host Database host
* @param user Database user
* @param pass Database password
* @param db Database name to use
* @param timeout Specifies how long connections should wait before giving up.
* If <= 0, the default of 60s is used.
*
* @return A newly created tuple handle to be used in connection routines.
*/
native Handle:SQL_MakeDbTuple(const host[], const user[], const pass[], const db[], timeout=0);
/**
* Frees an SQL handle.
* The handle can be to anything (tuple, connection, query, results, etc).
* If you free a database connection, it closes the connection as well.
*
* @note The handle can be to anything (tuple, connection, query, results, etc).
* @note If you free the database connection handle, it closes the connection as well.
*
* @param h Handle to be freed.
*
* @noreturn
*/
native SQL_FreeHandle(Handle:h);
/**
* Opens a database connection.
* Returns an SQL handle, which must be freed.
* Returns Empty_Handle on failure.
*
* @param cn_tuple Tuple handle, returned from SQL_MakeDbTuple().
* @param errcode An error code set by reference.
* @param error String where error string will be stored.
* @param maxlength Maximum length of the error buffer.
*
* @return Returns an SQL connection handle, which must be freed.
* Returns Empty_Handle on failure.
* @error Invalid info tuple handle.
*/
native Handle:SQL_Connect(Handle:cn_tuple, &errcode, error[], maxlength);
@ -65,38 +81,48 @@ native Handle:SQL_Connect(Handle:cn_tuple, &errcode, error[], maxlength);
* Sets the character set of the current connection.
* Like SET NAMES .. in mysql, but stays after connection problems.
*
* If a connection tuple is supplied, this should be called before SQL_Connect or SQL_ThreadQuery.
* Also note the change will remain until you call this function with another value.
* This native does nothing in SQLite.
* @note If a connection tuple is supplied, this should be called before SQL_Connect or SQL_ThreadQuery.
* @note The change will remain until you call this function with another value.
* @note This native does nothing in SQLite.
*
* Example: "utf8", "latin1"
*
* @param h Database or connection tuple Handle.
* @param charset The character set string to change to.
* @return True, if character set was changed, false otherwise.
* @param h Database or connection tuple Handle.
* @param charset The character set string to change to.
*
* @return True, if character set was changed, false otherwise.
*/
native bool:SQL_SetCharset(Handle:h, const charset[]);
/**
* Prepares a query.
* The query must always be freed.
* This does not actually do the query!
*
* @note This does not actually do a query!
*
* @param db Connection handle, returned from SQL_Connect().
* @param fmt Query string. Can be formated with format specifiers.
* @param ... Additional format specifiers used to format the query.
*
* @return Returns an SQL query handle, which must always be freed.
* Returns Empty_Handle on failure.
*/
native Handle:SQL_PrepareQuery(Handle:db, const fmt[], any:...);
/**
* Back-quotes characters in a string for database querying.
* Note: The buffer's maximum size should be 2*strlen(string) to catch
* all scenarios.
*
* @note The buffer's maximum size should be 2*strlen(string) to catch all scenarios.
*
* @param db Database handle for localization, or Empty_Handle
* for when a handle is not available.
* @param buffer Buffer to copy to.
* @param buflen Maximum size of the buffer.
* @param string String to backquote (should not overlap buffer).
* @return Length of new string, or -1 on failure.
* @param db Database handle for localization, or Empty_Handle
* for when a handle is not available.
* @param buffer Buffer to copy to.
* @param buflen Maximum size of the buffer.
* @param string String to backquote (should not overlap buffer).
*
* @return Length of new string, or -1 on failure.
* @error Invalid database handle.
*/
native SQL_QuoteString(Handle:db, buffer[], buflen, const string[]);
@ -105,171 +131,275 @@ native SQL_QuoteString(Handle:db, buffer[], buflen, const string[]);
* Note: The buffer's maximum size should be 2*strlen(string) to catch
* all scenarios.
*
* @param db Database handle for localization, or Empty_Handle
* for when a handle is not available.
* @param buffer Buffer to copy to.
* @param buflen Maximum size of the buffer.
* @param fmt Format of string to backquote (should not overlap buffer).
* @param ... Format arguments.
* @return Length of new string, or -1 on failure.
* @param db Database handle for localization, or Empty_Handle
* for when a handle is not available.
* @param buffer Buffer to copy to.
* @param buflen Maximum size of the buffer.
* @param fmt Format of string to backquote (should not overlap buffer).
* @param ... Format arguments.
*
* @return Length of new string, or -1 on failure.
*/
native SQL_QuoteStringFmt(Handle:db, buffer[], buflen, const fmt[], any:...);
/**
* Threaded query states. Used to check the state of a complete threaded query.
*/
#define TQUERY_CONNECT_FAILED -2
#define TQUERY_QUERY_FAILED -1
#define TQUERY_SUCCESS 0
/**
* Prepares and executes a threaded query.
* This will not interrupt gameplay in the event of a poor/lossed
* connection, however, the interface is more complicated and
* asynchronous. Furthermore, a new connection/disconnection is
* made for each query to simplify driver support.
* The handler should look like:
* @note The handler should look like:
* public QueryHandler(failstate, Handle:query, error[], errnum, data[], size, Float:queuetime)
* failstate - One of the three TQUERY_ defines.
* query - Handle to the query, do not free it.
* error - An error message, if any.
* errnum - An error code, if any.
* data - Data array you passed in.
* size - Size of the data array you passed in.
* queuetime - Amount of gametime that passed while the query was resolving.
* @note This will not interrupt gameplay in the event of a poor/lossed
* connection, however, the interface is more complicated and
* asynchronous. Furthermore, a new connection/disconnection is
* made for each query to simplify driver support.
* @note The handle does not need to be freed.
*
* @param failstate - One of the three TQUERY_ defines.
* @param query - Handle to the query, do not free it.
* @param error - An error message, if any.
* @param errnum - An error code, if any.
* @param data - Data array you passed in.
* @param size - Size of the data array you passed in.
* @param queuetime - Amount of gametime that passed while the query was resolving.
*
* public QueryHandler(failstate, Handle:query, error[], errnum, data[], size, Float:queuetime)
* @param db_tuple Tuple handle, returned from SQL_MakeDbTuple().
* @param handler A function to be called when the query finishes. It has to be public.
* @param query The query string.
* @param data Additional data array that will be passed to the handler function.
* @param dataSize The size of the additional data array.
*
* Note! The handle you pass in is a DB Tuple, NOT an active connection!
* Note! The handle does not need to be freed.
* Also note: This function is not guaranteed to be in another thread
* (in fact - it's not). You're seeing data "after the fact",
* and as such to execute another query you should run
* SQL_ThreadQuery again with new data.
* @noreturn
* @error Thread worker was unable to start.
* Invalid info tuple handle.
* Handler function not found.
*/
native SQL_ThreadQuery(Handle:db_tuple, const handler[], const query[], const data[]="", dataSize=0);
/**
* Executes a query.
* Returns 1 if the query succeeded.
* Returns 0 if the query failed.
* NOTE: You can call this multiple times as long as its parent
* connection is kept open. Each time the result set will be freed
* from the previous call.
* Executes an already prepared query.
*
* @note You can call this multiple times as long as its parent connection is kept open.
* Each time the result set from the previous call will be freed.
*
* @param query Handle of a prepared query to be executed.
*
* @return 1 if the query succeeded, 0 if the query failed.
* @error Invalid query handle.
*/
native SQL_Execute(Handle:query);
/**
* Gets information about a failed query error.
* Returns the errorcode.
*
* @param query Handle of a query to extract the error from.
* @param error Buffer where to store the error string.
* @param maxlength The maximum length of the output buffer.
*
* @return The error code.
*/
native SQL_QueryError(Handle:query, error[], maxlength);
/**
* Returns 1 if there are more results to be read,
* 0 otherwise.
* Checks whether there are more results to be read.
*
* @param query Handle of a query to check.
*
* @return 1 if there are more results, 0 otherwise.
* @error Invalid query handle.
*/
native SQL_MoreResults(Handle:query);
/**
* Tells whether a specific column in the current row
* is NULL or not.
* Tells whether a specific column in the current row is NULL or not.
*
* @param query Handle of a query to check.
* @param column Which column to check for NULL.
*
* @return 1 if the column is NULL, 0 otherwise.
* @error Invalid query handle.
* No result set in this query.
* Invalid column.
*/
native SQL_IsNull(Handle:query, column);
/**
* Retrieves the current result.
* A successful query starts at the first result,
* so you should not call SQL_NextRow() first.
* Passing no extra params - return int
* Passing one extra param - return float in 1st extra arg
* Passing two extra params - return string in 1st arg, max length in 2nd
* Example:
* new num = SQL_ReadResult(query, 0)
* new Float:num2
* new str[32]
* SQL_ReadResult(query, 1, num2)
* SQL_ReadResult(query, 2, str, 31)
*
* @note A successful query starts at the first result, so you should not call
* SQL_NextRow() first.
*
* @note Example how to get different types of values:
* new num = SQL_ReadResult(query, 0)
* new Float:num2
* new string[32]
* SQL_ReadResult(query, 1, num2)
* SQL_ReadResult(query, 2, string, charsmax(string))
*
* @param query Handle of a query to read results from.
* @param column Which column to get the value from.
* @param ... Passing no extra arguments - returns an integer.
* Passing one extra argument - returns a float in the first extra argument
* Passing two extra params - returns a string in the first argument
* with a maximum string length in the second argument.
*
* @return If no extra arguments are passed, returns an integer value.
* @error Invalid query handle.
*/
native SQL_ReadResult(Handle:query, column, any:...);
/**
* Advances to the next result (return value should be ignored).
* Advances to the next result (row).
*
* @param query Handle of a query.
*
* @noreturn
* @error Invalid query handle.
* No result set in this query.
*/
native SQL_NextRow(Handle:query);
/**
* Returns the number of affected rows.
/**
* Returns the number of affected rows by a query.
*
* @param query Handle of a query to check.
*
* @return The number of affected rows.
* @error Invalid query handle.
*/
native SQL_AffectedRows(Handle:query);
/**
* Returns the number of rows total.
* The number of retrieved rows (results) after a query.
*
* @param query Handle of a query to check.
*
* @return The number of retrieved rows by the query.
* @error Invalid query handle.
*/
native SQL_NumResults(Handle:query);
/**
* Returns the number of columns total.
* Returns the total number of columns.
*
* @param query Handle of a query to check.
*
* @return The number of retrieved columns by the query.
* @error Invalid query handle.
* No result set in this query.
*/
native SQL_NumColumns(Handle:query);
/**
* Returns the name of a column.
* Errors on a bad field number.
/**
* Retrieves the name of a column by its index.
*
* @param query Handle of a query.
* @param num The number (index) of a column to retrieve the name from.
* @param name Buffer where to store the column's name.
* @param maxlength Maximum length of the output buffer.
*
* @noreturn
* @error Invalid query handle.
* No result set in this query.
* Invalid column index.
*/
native SQL_FieldNumToName(Handle:query, num, name[], maxlength);
/**
* Returns the number of a named column, or -1 if not found.
* Retrieves the number of a named column.
*
* @param query Handle of a query.
* @param name Name to search for.
*
* @return Column index if found (>= 0); -1 otherwise.
* @error Invalid query handle.
* No result set in this query.
*/
native SQL_FieldNameToNum(Handle:query, const name[]);
/**
* Rewinds a result set to the first row.
*
* @param query Handle of a query to rewind the result set of.
*
* @noreturn
* @error Invalid query handle.
* No result set in this query.
*/
native SQL_Rewind(Handle:query);
/**
* Returns the insert id of the last INSERT query.
* Returns 0 otherwise.
* Retrieves the instert ID of the latest INSERT query.
*
* @param query Handle of a query.
*
* @return The insert ID of the latest INSERT query.
* @error Invalid query handle.
*/
native SQL_GetInsertId(Handle:query);
/**
* Returns which driver this plugin is currently bound to.
* Retrieves which driver is this plugin currently bound to.
*
* @param driver Buffer to store the driver name in.
* @param maxlen Maximum length of the output buffer.
*
* @noreturn
*/
native SQL_GetAffinity(driver[], maxlen);
/**
* Sets driver affinity. You can use this to force a particular
* driver implementation. This will automatically change all SQL
* natives in your plugin to be "bound" to the module in question.
* If no such module is found, it will return 0. This isn't necessarily bad -
* the user might have typed the wrong driver. Unless your plugin is built
* to handle different driver types at once, you should let this error pass.
* Note, that using this while you have open handles to another database
* type will cause problems. I.e., you cannot open a handle, switch
* affinity, then close the handle with a different driver.
* Switching affinity is an O(n*m) operation, where n is the number of
* SQL natives and m is the number of used natives in total.
* Intuitive programmers will note that this causes problems for threaded queries.
* You will have to either force your script to work under one affinity, or to
* pack the affinity type into the query data, check it against the current, then
* set the new affinity if necessary. Then, restore the old for safety.
* Sets driver affinity. You can use this to force a particular driver implementation.
* This will automatically change all SQL natives in your plugin to be "bound" to
* the module in question.
*
* @note Using this while you have open handles to another database type will
* cause problems. I.e., you cannot open a handle, switch affinity,
* then close the handle with a different driver.
* @note Switching affinity is an O(n * m) operation, where n is the number of
* SQL natives and m is the number of used natives in total.
* @note Intuitive programmers will note that this causes problems for
* threaded queries. You will have to either force your script to work
* under one affinity, or to pack the affinity type into the query data,
* check it against the current, then set the new affinity if necessary.
* Then, restore the old one for safety.
*
* @param driver The name of a driver to use.
*
* @return If no module with the given name is found, returns 0.
* Unless your plugin is bult to handle different driver
* types at once, you should let this error pass.
*/
native SQL_SetAffinity(const driver[]);
/**
* Returns the original query string that a query handle used.
*
* @param query Handle of a query.
* @param buffer Buffer where to put the query string in.
* @param maxlength The maximum length of the output buffer.
*
* @noreturn
* @error Invalid query handle.
*/
native SQL_GetQueryString(Handle:query, buffer[], maxlength);
@ -278,18 +408,26 @@ native SQL_GetQueryString(Handle:query, buffer[], maxlength);
* result set if one is available. Otherwise, the current result set is
* destroyed and will no longer be accessible.
*
* This function will always return false on SQLite, and when using threaded
* queries in MySQL. Nonetheless, it has the same effect of removing the last
* result set.
* @note This function will always return false on SQLite, and when using threaded
* queries in MySQL. Nonetheless, it has the same effect of removing the last
* result set.
*
* @param query Query Handle.
* @return True on success, false on failure.
* @param query Query Handle.
*
* @return True on success, false on failure.
* @error Invalid query handle.
* No result set in this query.
*/
native bool:SQL_NextResultSet(Handle:query);
/**
* This function can be used to find out if a table in a Sqlite database exists.
* (updated for newer API)
* This function can be used to find out if a table in a SQLite database exists.
*
* @param db Connection handle returned from SQL_Connect().
* @param table The table name to check for.
*
* @return True if it exists, false otherwise.
*/
stock bool:sqlite_TableExists(Handle:db, const table[])
{
@ -311,7 +449,14 @@ stock bool:sqlite_TableExists(Handle:db, const table[])
/**
* Use this for executing a query where you don't care about the result.
* Returns 0 on failure, 1 on success
*
* @param db Connection handle returned from SQL_Connect().
* @param query The query string.
* @param error If an error occurs, it will be placed into this buffer.
* @param maxlength Maximum length of the error buffer.
* @param rows Optional. If put, retrieves the number of rows the query returned.
*
* @return 1 on success, 0 on failure.
*/
stock SQL_SimpleQuery(Handle:db, const query[], error[]="", maxlength=0, &rows=0)
{
@ -331,9 +476,20 @@ stock SQL_SimpleQuery(Handle:db, const query[], error[]="", maxlength=0, &rows=0
return 1;
}
/**
* Use this for executing a query where you don't care about the result.
* Returns 0 on failure, 1 on success
*
* @note Differs from SQL_SimpleQuery() because the query can be formated.
*
* @param db Connection handle returned from SQL_Connect().
* @param error If an error occurs, it will be placed into this buffer.
* @param maxlength The maximum length of the error buffer.
* @param rows Optional. If put, retrieves the number of rows the query returned.
* @param fmt The query string that can be formated with format specifiers.
* @param ... Additional arguments for formating the query.
*
* @return 1 on success, 0 on failure.
*/
stock SQL_SimpleQueryFmt(Handle:db, error[]="", maxlength=0, &rows=0, const fmt[], any:...)
{
@ -358,7 +514,13 @@ stock SQL_SimpleQueryFmt(Handle:db, error[]="", maxlength=0, &rows=0, const fmt[
/**
* Use this for executing a query and not caring about the error.
* Returns -1 on error, >=0 on success (with number of affected rows)
*
* @param db A connection handle returned from SQL_Connect().
* @param queryfmt The query string that can be formated with format specifiers.
* @pram ... Additional arguments for formating the query.
*
* @return 1 on error.
* >= 0 on success (with the number of affected rows).
*/
stock SQL_QueryAndIgnore(Handle:db, const queryfmt[], any:...)
{
@ -382,6 +544,14 @@ stock SQL_QueryAndIgnore(Handle:db, const queryfmt[], any:...)
return ret;
}
/**
* Use this for making a standard DB Tuple, using AMXX's database info cvars.
*
* @param timeout Specifies how long connections should wait before giving up.
* If 0, the value is read from "amx_sql_timeout" cvar.
*
* @return A newly created tuple handle to be used in connection routines.
*/
stock Handle:SQL_MakeStdTuple(timeout = 0)
{
static host[64], user[32], pass[32], db[128];

88
plugins/include/vector.inc
View File

@ -16,34 +16,93 @@
#endif
#define _corevector_included
/* Used for angle_vector() */
/**
* Used for angle_vector()
*/
#define ANGLEVECTOR_FORWARD 1
#define ANGLEVECTOR_RIGHT 2
#define ANGLEVECTOR_UP 3
/* Returns distance between two vectors. */
/**
* Calculates the distance between two input vectors.
*
* @param origin1 The first vector
* @param origin2 The second vector
*
* @return The distance between two input vectors
*/
native get_distance(const origin1[3], const origin2[3]);
/* Gets distance between two origins (float). */
/**
* Calculates the distance between two input float vectors.
*
* @param origin1 The first vector
* @param origin2 The second vector
*
* @return The distance between two input vectors
*/
native Float:get_distance_f(const Float:Origin1[3], const Float:Origin2[3]);
/* Gives you a velocity in the direction a player is looking, iVelocity is the multiplier. */
/**
* Calculates velocity in the direction player is looking.
*
* @param iIndex Client index
* @param iVelocity Multiply vRetValue length by this much
* @param vRetValue Store the calculated velocity in this vector.
*
* @noreturn
* @error If client is not connected or client index is not
* within the range of 1 to MaxClients.
*/
native velocity_by_aim(iIndex, iVelocity, Float:vRetValue[3]);
/* Changes a vector into an angle vector. */
/**
* Changes a vector into an angle vector.
*
* @param fVector Input vector
* @param vReturn Output angle vector
*
* @noreturn
*/
native vector_to_angle(const Float:fVector[3], Float:vReturn[3]);
/* Changes an angle vector into a vector. */
/**
* Changes an angle vector into a vector.
*
* @param vector Input angle vector
* @param FRU One of the ANGLEVECTOR_* constants
* @param ret Output vector
*
* @noreturn
*/
native angle_vector(const Float:vector[3], FRU, Float:ret[3]);
/* Gets the length of a vector (float[3]). */
/**
* Calculates the length of a vector.
*
* @param vVector Input vector
*
* @return Length of the input vector
*/
native Float:vector_length(const Float:vVector[3]);
/* Gets the distance between 2 vectors (float[3]). */
/**
* Calculates the distance between two vectors.
*
* @param vVector The first vector
* @param vVector2 The second vector
*
* @return Distance between two input vectors
*/
native Float:vector_distance(const Float:vVector[3], const Float:vVector2[3]);
/* Changes an integer vec to a floating vec
* This is not a for loop because that's slower
/**
* Converts an integer vector to a floating point vector.
*
* @param IVec Input integer vector
* @param FVec Output float vector
*
* @noreturn
*/
stock IVecFVec(const IVec[3], Float:FVec[3])
{
@ -54,7 +113,14 @@ stock IVecFVec(const IVec[3], Float:FVec[3])
return 1;
}
/* Changes a float vec to an integer vec */
/**
* Converts a floating point vector into an integer vector.
*
* @param FVec Input float vector
* @param IVec Output integer vector
*
* @noreturn
*/
stock FVecIVec(const Float:FVec[3], IVec[3])
{
IVec[0] = floatround(FVec[0]);

687
plugins/include/xs.inc
View File

File diff suppressed because it is too large Load Diff