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

datapack: Tabs->spaces, consistency, nuke IsPackReadable

Browse Source
This commit is contained in:
Valentin Grünbacher 2015-02-24 22:16:36 +01:00
parent 828d9971a4
commit 950f3f97c1
1 changed files with 76 additions and 62 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

132
plugins/include/datapack.inc
View File

@ -13,9 +13,16 @@
#define _datapack_included #define _datapack_included
/** /**
* DataPacks are a way to store and move around various types of data in AMX Mod X Scripting. * Datapack tag declaration
* Since some things are not possible in AMX Mod X, such as a function consuming a String, *
* DataPacks help us get these Strings and other items where they need to go. * @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.
*/ */
enum DataPack enum DataPack
@ -24,115 +31,122 @@ enum DataPack
}; };
/** /**
* Creates a new data pack. * Creates a new datapack.
* *
* @return A Handle to the data pack. * @return New datapack handle, which must be freed via DestroyDataPack().
*/ */
native DataPack:CreateDataPack(); native DataPack:CreateDataPack();
/** /**
* Packs a normal cell into a data pack. * Packs a cell value into a datapack.
*
* @param pack Datapack handle
* @param cell Cell value to pack
* *
* @param pack Handle to the data pack.
* @param cell Cell to add.
* @noreturn * @noreturn
* @error Invalid handle. * @error If an invalid handle is provided, an error will be thrown.
*/ */
native WritePackCell(DataPack:pack, any:cell); native WritePackCell(DataPack:pack, any:cell);
/** /**
* Packs a float into a data pack. * Packs a float value into a datapack.
*
* @param pack Datapack handle
* @param val Float value to pack
* *
* @param pack Handle to the data pack.
* @param val Float to add.
* @noreturn * @noreturn
* @error Invalid handle. * @error If an invalid handle is provided, an error will be thrown.
*/ */
native WritePackFloat(DataPack:pack, Float:val); native WritePackFloat(DataPack:pack, Float:val);
/** /**
* Packs a string into a data pack. * Packs a string into a datapack.
* *
* @param pack Handle to the data pack. * @param pack Datapack handle
* @param str String to add. * @param str String to pack
* @return Length of copied string. *
* @error Invalid handle. * @return Length of copied string
* @error If an invalid handle is provided, an error will be thrown.
*/ */
native WritePackString(DataPack:pack, const str[]); native WritePackString(DataPack:pack, const str[]);
/** /**
* Reads a cell from a data pack. * Reads a cell from a Datapack.
* *
* @param pack Handle to the data pack. * @param pack Datapack handle
* @return Cell value. *
* @error Invalid handle, or bounds error. * @return Cell value
* @error If an invalid handle is provided, or not enough data is left
* in the datapack, an error will be thrown.
*/ */
native any:ReadPackCell(DataPack:pack); native any:ReadPackCell(DataPack:pack);
/** /**
* Reads a float from a data pack. * Reads a float from a datapack.
* *
* @param pack Handle to the data pack. * @param pack Datapack handle
* @return Float value. *
* @error Invalid handle, or bounds error. * @return Float value
* @error If an invalid handle is provided, or not enough data is left
* in the datapack, an error will be thrown.
*/ */
native Float:ReadPackFloat(DataPack:pack); native Float:ReadPackFloat(datapack:pack);
/** /**
* Reads a string from a data pack. * Reads a string from a Datapack.
* *
* @param pack Handle to the data pack. * @param pack Datapack handle
* @param buffer Destination string buffer. * @param buffer Buffer to copy string to
* @param maxlen Maximum length of output string buffer. * @param maxlen Maximum size of buffer
* @return Length of output string. *
* @error Invalid handle, or bounds error. * @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.
*/ */
native ReadPackString(DataPack:pack, buffer[], maxlen); native ReadPackString(DataPack:pack, buffer[], maxlen);
/** /**
* Resets the position in a data pack. * Resets the datapack read/write position to the start.
*
* @param pack Datapack handle
* @param clear If true, clears the contained data
* *
* @param pack Handle to the data pack.
* @param clear If true, clears the contained data.
* @noreturn * @noreturn
* @error Invalid handle. * @error If an invalid handle is provided, an error will be thrown.
*/ */
native ResetPack(DataPack:pack, bool:clear=false); native ResetPack(DataPack:pack, bool:clear = false);
/** /**
* Returns the read or write position in a data pack. * Returns the datapack read/write position.
* *
* @param pack Handle to the data pack. * @param pack Datapack handle
* @return Numerical position in the data pack. *
* @error Invalid handle. * @return Position in the datapack
* @error If an invalid handle is provided, an error will be thrown.
*/ */
native GetPackPosition(DataPack:pack); native GetPackPosition(DataPack:pack);
/** /**
* Sets the read/write position in a data 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
* *
* @param pack Handle to the data pack.
* @param position New position to set.
* @noreturn * @noreturn
* @error Invalid handle, or position is beyond the pack bounds. * @error If an invalid handle is provided, or the new position is
* out of datapack bounds, an error will be thrown.
*/ */
native SetPackPosition(DataPack:pack, position); native SetPackPosition(DataPack:pack, position);
/** /**
* Returns whether or not a specified number of bytes from the data pack * Destroys the datapack and frees its memory.
* position to the end can be read.
* *
* @param pack Handle to the data pack. * @param pack Datapack handle
* @param bytes Number of bytes to simulate reading.
* @return True if can be read, false otherwise.
* @error Invalid handle.
*/
native bool:IsPackReadable(DataPack:pack, bytes);
/**
* Disposes of a data pack.
* *
* @param pack Handle to the data pack. * @return True if disposed, false otherwise
* @return True if disposed, false otherwise.
*/ */
native DestroyDataPack(&DataPack:pack); native DestroyDataPack(&DataPack:pack);