Buffers

IN 'Faucet Networking v1.4.1' HELP.PDF ~ BUFFERS
 
Buffers typically contain data that has been received or should be sent.
Handing an invalid buffer handle to a buffer function will cause the function to behave as if it was called on a constantly empty buffer. Some of these functions will act on a socket¡¯s send or receive buffer if a socket handle is passed to them. The parameter names socketReceiveBuf and socketSendBuf indicate which of the two buffers the parameter refers to.
 

Functions

buffer_create() : buffer
Create a new, empty buffer.

buffer_destroy(buffer) : void
Destroy a buffer and release its handle. This function should be called on all buffers that are no longer needed to release the memory allocated to them.

buffer_clear(buffer) : void
Remove all content from the buffer, so that it behaves exactly like a buffer that has only just been created.

buffer_size(buffer) : size
Returns the number of bytes in the buffer.

buffer_bytes_left(buffer | socketReceiveBuf) : size
Returns the number of bytes that can still be read from the buffer.

buffer_set_readpos(buffer | socketReceiveBuf, pos) : void
Set the read pointer of the buffer to a new position (given in bytes). The given position will be clipped to the beginning or the end of the buffer if it is below 0 or above buffer_size(buffer). There is no corresponding buffer_get_readpos(), if you really need this you can calculate it as buffer_size(buffer)-buffer_bytes_left(buffer).

write_[xxx](buffer | socketSendBuf, real) : void
Append the given value to the end of the buffer, or to the socket¡¯s send buffer. The following functions are supported:
write_ubyte 8 bit unsigned integer
write_byte 8 bit signed integer
write_ushort 16 bit unsigned integer
write_short 16 bit signed integer
write_uint 32 bit unsigned integer
write_int 32 bit signed integer
write_float 32 bit floating point value
write_double 64 bit floating point value
The value of the provided real will be clipped to fit the range of the target type. For example, attempting to write anything above 127 as a (signed) byte will always write 127.
When converting the real to an integer type, the value is rounded to the nearest integer, with the halfway point being rounded away from 0.
To give some examples of this: write_short(buffer, 42.5) and write_short(buffer, 43.499) will both write 43, and write_short(buffer, -2.5) will write -3.

write_string(buffer | socketSendBuf, string) : void
Append a string in Game Maker¡¯s 8 bit character encoding to the buffer, or to the socket¡¯s send buffer. This will only write the raw characters, no length information or delimiter is included, so you will want to do that yourself.

write_buffer(target, source) : void
Append entire source buffer to the end of target. Both source and target may be either sockets or buffers. If target is a socket, it refers to the socket¡¯s send buffer. If source is a socket, it refers to the socket¡¯s receive buffer. This operation doesn¡¯t affect the buffers¡¯ read positions and always copies the entire buffer content.

write_buffer_part(target, source, size) : size
Append size bytes from the source buffer to the end of target. Both source and target may be either sockets or buffers. If target is a socket, it refers to the socket¡¯s send buffer. If source is a socket, it refers to the socket¡¯s receive buffer.
In contrast to write_buffer, this function starts reading from the source at the current read position, and advances the read position accordingly. If less than size bytes are left to read in the source buffer, only the remaining data is appended to the target buffer.
The number of bytes actually copied is returned.

read_[xxx](buffer | socketReceiveBuf) : real
Read a value of the expected type from the buffer, starting at its current read position.
The read position will be advanced to the next byte after the read value. If there are not enough bytes left in the buffer, the returned value is undefined and the read position is set to the end of the buffer. If the buffer does not exist, 0 is returned. See write_[xxx] for possible types.

read_string(buffer | socketReceiveBuf, size) : string
Read the given number of characters from the buffer and return them as a string. The reading starts at the buffer¡¯s current read position. The read position will be advanced to the next byte after the read characters. If there are not enough bytes left in the buffer, the returned string will be shorter than requested and the read position is set to the end of the buffer. If size is negative, an empty string is returned and the buffer¡¯s read position will be unchanged.