amxmodx/plugins/include/datapack.inc

152 lines
4.3 KiB
SourcePawn
Raw Normal View History

// vim: set ts=4 sw=4 tw=99 noet:
//
// AMX Mod X, based on AMX Mod by Aleksander Naszko ("OLO").
// Copyright (C) The AMX Mod X Development Team.
//
// This software is licensed under the GNU General Public License, version 3 or higher.
// Additional exceptions apply. For full license details, see LICENSE.txt or visit:
// https://alliedmods.net/amxmodx-license
2014-04-12 00:57:42 +04:00
#if defined _datapack_included
2015-02-25 00:51:36 +03:00
#endinput
2014-04-12 00:57:42 +04:00
#endif
#define _datapack_included
2014-04-12 00:57:42 +04:00
/**
* Datapack tag declaration
*
* @note Datapacks provide a way to store and move around arbitrary amounts (and
* types) of data in AMX Mox X. Data is packed into a single cell value -
* the DataPack handle. This handle can be passed around more easily, can
* be returned by functions and can simulate advanced concepts like string
* consummation.
* @note Plugins are responsible for freeing all datapack handles they acquire.
* Failing to free handles will result in the plugin and AMXX leaking
* memory.
2014-04-12 00:57:42 +04:00
*/
enum DataPack
{
2015-02-25 00:51:36 +03:00
Invalid_DataPack = 0
2014-04-12 00:57:42 +04:00
};
/**
* Creates a new datapack.
2014-04-12 00:57:42 +04:00
*
* @return New datapack handle, which must be freed via DestroyDataPack().
2014-04-12 00:57:42 +04:00
*/
native DataPack:CreateDataPack();
/**
* Packs a cell value into a datapack.
*
* @param pack Datapack handle
* @param cell Cell value to pack
2014-04-12 00:57:42 +04:00
*
* @noreturn
* @error If an invalid handle is provided, an error will be thrown.
2014-04-12 00:57:42 +04:00
*/
native WritePackCell(DataPack:pack, any:cell);
2014-04-12 00:57:42 +04:00
/**
* Packs a float value into a datapack.
*
* @param pack Datapack handle
* @param val Float value to pack
2014-04-12 00:57:42 +04:00
*
* @noreturn
* @error If an invalid handle is provided, an error will be thrown.
2014-04-12 00:57:42 +04:00
*/
native WritePackFloat(DataPack:pack, Float:val);
/**
* Packs a string into a datapack.
*
* @param pack Datapack handle
* @param str String to pack
2014-04-12 00:57:42 +04:00
*
* @return Length of copied string
* @error If an invalid handle is provided, an error will be thrown.
2014-04-12 00:57:42 +04:00
*/
native WritePackString(DataPack:pack, const str[]);
/**
* Reads a cell from a Datapack.
2014-04-12 00:57:42 +04:00
*
* @param pack Datapack handle
*
* @return Cell value
* @error If an invalid handle is provided, or not enough data is left
* in the datapack, an error will be thrown.
2014-04-12 00:57:42 +04:00
*/
native any:ReadPackCell(DataPack:pack);
2014-04-12 00:57:42 +04:00
/**
* Reads a float from a datapack.
*
* @param pack Datapack handle
2014-04-12 00:57:42 +04:00
*
* @return Float value
* @error If an invalid handle is provided, or not enough data is left
* in the datapack, an error will be thrown.
2014-04-12 00:57:42 +04:00
*/
native Float:ReadPackFloat(datapack:pack);
2014-04-12 00:57:42 +04:00
/**
* Reads a string from a Datapack.
*
* @param pack Datapack handle
* @param buffer Buffer to copy string to
* @param maxlen Maximum size of buffer
2014-04-12 00:57:42 +04:00
*
* @return Number of cells written to buffer
* @error If an invalid handle is provided, or not enough data is left
* in the datapack, an error will be thrown.
2014-04-12 00:57:42 +04:00
*/
native ReadPackString(DataPack:pack, buffer[], maxlen);
/**
* Resets the datapack read/write position to the start.
*
* @param pack Datapack handle
* @param clear If true, clears the contained data
2014-04-12 00:57:42 +04:00
*
* @noreturn
* @error If an invalid handle is provided, an error will be thrown.
2014-04-12 00:57:42 +04:00
*/
native ResetPack(DataPack:pack, bool:clear = false);
2014-04-12 00:57:42 +04:00
/**
* Returns the datapack read/write position.
*
* @param pack Datapack handle
2014-04-12 00:57:42 +04:00
*
* @return Position in the datapack
* @error If an invalid handle is provided, an error will be thrown.
2014-04-12 00:57:42 +04:00
*/
native GetPackPosition(DataPack:pack);
/**
* Sets the datapack read/write position.
*
* @note This should only ever be used with (known to be valid) positions
* returned by GetPackPosition(). It is not possible for plugins to safely
* compute datapack positions.
*
* @param pack Datapack handle
* @param position New position to set
2014-04-12 00:57:42 +04:00
*
* @noreturn
* @error If an invalid handle is provided, or the new position is
* out of datapack bounds, an error will be thrown.
2014-04-12 00:57:42 +04:00
*/
native SetPackPosition(DataPack:pack, position);
/**
* Destroys the datapack and frees its memory.
2014-04-12 00:57:42 +04:00
*
* @param pack Datapack handle
2014-04-12 00:57:42 +04:00
*
* @return True if disposed, false otherwise
2014-04-12 00:57:42 +04:00
*/
native DestroyDataPack(&DataPack:pack);