From 9674e13cfb78e862c64583467840a10280337022 Mon Sep 17 00:00:00 2001 From: Javivi Date: Mon, 12 Oct 2015 00:32:56 +0200 Subject: [PATCH] Update docs and fix AMBuild Updated documentation following the guidelines --- modules/sockets/AMBuilder | 6 +- plugins/include/sockets.inc | 161 ++++++++++++++++++++++++++++++------ 2 files changed, 142 insertions(+), 25 deletions(-) diff --git a/modules/sockets/AMBuilder b/modules/sockets/AMBuilder index f14c8512..1057c769 100644 --- a/modules/sockets/AMBuilder +++ b/modules/sockets/AMBuilder @@ -8,9 +8,13 @@ binary.sources = [ 'sockets.cpp', ] +binary.compiler.defines += [ + 'HAVE_STDINT_H', +] + if builder.target_platform == 'windows': binary.sources += ['version.rc'] - + if builder.target_platform == 'windows': binary.compiler.postlink += ['wsock32.lib', 'ws2_32.lib'] diff --git a/plugins/include/sockets.inc b/plugins/include/sockets.inc index 42bd4d9c..7c2af53d 100755 --- a/plugins/include/sockets.inc +++ b/plugins/include/sockets.inc @@ -3,9 +3,6 @@ // AMX Mod X, based on AMX Mod by Aleksander Naszko ("OLO"). // Copyright (C) The AMX Mod X Development Team. // -// Codebase from Ivan, -g-s-ivan@web.de (AMX 0.9.3) -// Modification by Olaf Reusch, kenterfie@hlsw.de (AMXX 0.16, AMX 0.96) -// // 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 @@ -24,43 +21,159 @@ #pragma loadlib sockets #endif -// Use SOCKET_TCP for TCP Socket connections +// Backwards compatibility and error reporting +#define ERROR_CREATE_SOCKET 1 // Couldn't create a socket +#define ERROR_SERVER_UNKNOWN 2 // Server unknown +#define ERROR_WHILE_CONNECTING 3 // Error while connecting +#define DISABLE_LIBC_ERRORS 0 // Old, default error reporting +#define ENABLE_LIBC_ERRORS 1 // Enable libc error reporting + +// Use SOCKET_TCP for TCP Socket connections #define SOCKET_TCP 1 // Use SOCKET_UDP for UDP Socket connections - #define SOCKET_UDP 2 -/* Opens a new connection to hostname:port via protocol (either SOCKET_TCP or SOCKET_UDP), - * returns a socket (positive) or negative or zero on error. - * States of error: - * 0 - no error - * 1 - error while creating socket - * 2 - couldn't resolve hostname - * 3 - couldn't connect to given hostname:port +/** + * Connects to the given node and service via TCP/UDP. + * + * @note There's 2 types of error reporting on this function that you can use, for backwards compatibility reasons libc errors are disabled by default + * @note Old, default error codes: + * 0 - No error + * 1 - Error while creating socket + * 2 - Couldn't resolve hostname + * 3 - Couldn't connect + * @note New, libc error codes: + * https://www.gnu.org/software/libc/manual/html_node/Error-Codes.html + * https://github.com/torvalds/linux/blob/master/include/uapi/asm-generic/errno.h + * https://msdn.microsoft.com/en-us/library/ms740668.aspx + * + * @param _hostname Node to connect to + * @param _port Service to connect to + * @param _protocol Connect via SOCKET_TCP or SOCKET_UDP + * @param _error Set an error code here if anything goes wrong + * @param _libc_errors Optional parameter that defaults to DISABLE_LIBC_ERRORS. If set to ENABLE_LIBC_ERRORS the new libc errors will be set on _error instead of the old, made up ones + * + * @return A socket descriptor (a positive integer) on success + * -1 on failure */ +native socket_open(const _hostname[], _port, _protocol = SOCKET_TCP, &_error, _libc_errors = DISABLE_LIBC_ERRORS); -native socket_open(const _hostname[], _port, _protocol = SOCKET_TCP, &_error); +/** + * Connects on nonblocking mode to the given node and service via TCP/UDP. + * + * @note _hostname should be numeric to avoid calling the name resolution server and potentially blocking the call + * @note The returned socket descriptor may be still connecting, further checks should be done with socket_is_writable() + * @note Unlike in socket_open() libc error codes are used. They can be found at: + * https://www.gnu.org/software/libc/manual/html_node/Error-Codes.html + * https://github.com/torvalds/linux/blob/master/include/uapi/asm-generic/errno.h + * https://msdn.microsoft.com/en-us/library/ms740668.aspx + * + * @param _hostname Node to connect to + * @param _port Service to connect to + * @param _protocol Connect via SOCKET_TCP or SOCKET_UDP + * @param _error Set an error code here if anything goes wrong -/* Closes a Socket */ + * @return A socket descriptor (a positive integer) on success + * -1 on failure +*/ +native socket_open_nb(const _hostname[], _port, _protocol = SOCKET_TCP, &_error); +/** + * Closes a socket + * + * @param _socket Socket descriptor + * + * @return 1 on success + * -1 on failure + */ native socket_close(_socket); -/* Recieves Data to string with the given length */ - +/** + * Receives data. + * + * @note The ammount of bytes than you end up receiving can be less than the one you expected + * + * @param _socket Socket descriptor + * @param _data Array to save the data + * @param _length Length of the array + * + * @return Ammount of bytes received + * 0 if the peer closed the connection + * -1 on failure + */ native socket_recv(_socket, _data[], _length); -/* Sends data to the Socket */ - +/** + * Sends data. + * + * @note The ammount of bytes than you end up sending can be less than expected, you're responsible of sending the rest later + * + * @param _socket Socket descriptor + * @param _data Array with the data to send + * @param _length Length of the array + * + * @return Ammount of bytes sent + * -1 on failure + */ native socket_send(_socket, const _data[], _length); -/* Same as socket_send but Data can contain null bytes */ - +/** + * Sends data that can contain null bytes. + * + * @note The ammount of bytes than you end up sending can be less than expected, you're responsible of sending the rest later + * + * @param _socket Socket descriptor + * @param _data Array with the data to send + * @param _length Length of the array + * + * @return Ammount of bytes sent + * -1 on failure + */ native socket_send2(_socket, const _data[], _length); -/* This function will return true if the state (buffer content) have changed within the last recieve or -* the timeout, where timeout is a value in µSeconds, (1 sec =1000000 µsec). -* Use to check if new data is in your socket. */ +/** + * Check if a socket is marked as readable. + * + * @note You can use this function to make sure there's something on the socket and avoiding a blocking call + * @note Set _timeout to 0 avoid blocking the call + * @note A socket will become readable if there's any data or an EOF + * + * @param _socket Socket descriptor + * @param _timeout Ammount of time to block the call waiting for the socket to be marked as readable or for the timeout to expire, in µSeconds (1 sec = 1000000 µsec) + * + * @return 1 if the socket is marked as readable + * -1 otherwise + */ +native socket_change(_socket, _timeout = 100000); -native socket_change(_socket, _timeout=100000); +/** + * Check if a socket is marked as readable. + * + * @note You can use this function to make sure there's something on the socket and avoiding a blocking call + * @note Set _timeout to 0 avoid blocking the call + * @note A socket will become readable if there's any data or an EOF + * + * @param _socket Socket descriptor + * @param _timeout Ammount of time to block the call waiting for the socket to be marked as readable or for the timeout to expire, in µSeconds (1 sec = 1000000 µsec) + * + * @return 1 if the socket is marked as readable + * -1 otherwise + */ +native socket_is_readable(_socket, _timeout = 100000); + +/** + * Check if a socket is marked as writable. + * + * @note Use this function to check if a nonblocking socket is ready to be used + * @note Set _timeout to 0 avoid blocking the call + * @note An UDP socket is always writable + * + * @param _socket Socket descriptor + * @param _timeout Ammount of time to block the call waiting for the socket to be marked as writable or for the timeout to expire, in µSeconds (1 sec = 1000000 µsec) + * + * @return 1 if the socket is marked as writable + * -1 otherwise + */ +native socket_is_writable(_socket, _timeout = 100000);