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.