mirror of
https://github.com/SFML/CSFML.git
synced 2026-10-27 05:26:13 +01:00
Improved API documentation (copied from SFML)
This commit is contained in:
Laurent Gomila committed
1 parent
c84a787d0a
commit
d734c9df5c
50 files changed
+1606
-1478
No files matched your search
+155
-95
@@ -35,7 +35,8 @@
|
||||
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Enumerate all the FTP file transfer modes
|
||||
/// \brief Enumeration of transfer modes
|
||||
///
|
||||
////////////////////////////////////////////////////////////
|
||||
enum sfFtpTransferMode
|
||||
{
|
||||
@@ -46,8 +47,8 @@ enum sfFtpTransferMode
|
||||
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Enumerate all the valid status codes returned in
|
||||
/// a FTP response
|
||||
/// \brief Status codes possibly returned by a FTP response
|
||||
///
|
||||
////////////////////////////////////////////////////////////
|
||||
enum sfFtpStatus
|
||||
{
|
||||
@@ -113,28 +114,30 @@ enum sfFtpStatus
|
||||
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Destroy an existing Ftp listing response
|
||||
/// \brief Destroy a FTP listing response
|
||||
///
|
||||
/// \param ftpListingResponse : Ftp listing response to destroy
|
||||
/// \param ftpListingResponse Ftp listing response to destroy
|
||||
///
|
||||
////////////////////////////////////////////////////////////
|
||||
CSFML_API void sfFtpListingResponse_Destroy(sfFtpListingResponse* ftpListingResponse);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Convenience function to check if the response status code
|
||||
/// means a success
|
||||
/// \brief Check if a FTP listing response status code means a success
|
||||
///
|
||||
/// \param ftpListingResponse : Ftp listing response
|
||||
/// This function is defined for convenience, it is
|
||||
/// equivalent to testing if the status code is < 400.
|
||||
///
|
||||
/// \return sfTrue if status is success (code < 400)
|
||||
/// \param ftpListingResponse Ftp listing response
|
||||
///
|
||||
/// \return sfTrue if the status is a success, sfFalse if it is a failure
|
||||
///
|
||||
////////////////////////////////////////////////////////////
|
||||
CSFML_API sfBool sfFtpListingResponse_IsOk(const sfFtpListingResponse* ftpListingResponse);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Get the response status code
|
||||
/// \brief Get the status code of a FTP listing response
|
||||
///
|
||||
/// \param ftpListingResponse : Ftp listing response
|
||||
/// \param ftpListingResponse Ftp listing response
|
||||
///
|
||||
/// \return Status code
|
||||
///
|
||||
@@ -142,9 +145,9 @@ CSFML_API sfBool sfFtpListingResponse_IsOk(const sfFtpListingResponse* ftpListin
|
||||
CSFML_API sfFtpStatus sfFtpListingResponse_GetStatus(const sfFtpListingResponse* ftpListingResponse);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Get the full message contained in the response
|
||||
/// \brief Get the full message contained in a FTP listing response
|
||||
///
|
||||
/// \param ftpListingResponse : Ftp listing response
|
||||
/// \param ftpListingResponse Ftp listing response
|
||||
///
|
||||
/// \return The response message
|
||||
///
|
||||
@@ -152,49 +155,51 @@ CSFML_API sfFtpStatus sfFtpListingResponse_GetStatus(const sfFtpListingResponse*
|
||||
CSFML_API const char* sfFtpListingResponse_GetMessage(const sfFtpListingResponse* ftpListingResponse);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Get the number of filenames in the listing
|
||||
/// \brief Return the number of filenames contained in a FTP listing response
|
||||
///
|
||||
/// \param ftpListingResponse : Ftp listing response
|
||||
/// \param ftpListingResponse Ftp listing response
|
||||
///
|
||||
/// \return Total number of filenames
|
||||
/// \return Total number of filenames available
|
||||
///
|
||||
////////////////////////////////////////////////////////////
|
||||
CSFML_API size_t sfFtpListingResponse_GetCount(const sfFtpListingResponse* ftpListingResponse);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Get the Index-th filename in the directory
|
||||
/// \brief Return a filename contained in a FTP listing response
|
||||
///
|
||||
/// \param ftpListingResponse : Ftp listing response
|
||||
/// \param index : Index of the filename to get
|
||||
/// \param ftpListingResponse Ftp listing response
|
||||
/// \param index Index of the filename to get (in range [0 .. GetCount])
|
||||
///
|
||||
/// \return Index-th filename
|
||||
/// \return Array containing the requested filenames
|
||||
///
|
||||
////////////////////////////////////////////////////////////
|
||||
CSFML_API const char* sfFtpListingResponse_GetFilename(const sfFtpListingResponse* ftpListingResponse, size_t index);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Destroy an existing Ftp directory response
|
||||
/// \brief Destroy a FTP directory response
|
||||
///
|
||||
/// \param ftpDirectoryResponse : Ftp directory response to destroy
|
||||
/// \param ftpDirectoryResponse Ftp directory response to destroy
|
||||
///
|
||||
////////////////////////////////////////////////////////////
|
||||
CSFML_API void sfFtpDirectoryResponse_Destroy(sfFtpDirectoryResponse* ftpDirectoryResponse);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Convenience function to check if the response status code
|
||||
/// means a success
|
||||
/// \brief Check if a FTP directory response status code means a success
|
||||
///
|
||||
/// \param ftpDirectoryResponse : Ftp directory response
|
||||
/// This function is defined for convenience, it is
|
||||
/// equivalent to testing if the status code is < 400.
|
||||
///
|
||||
/// \return sfTrue if status is success (code < 400)
|
||||
/// \param ftpDirectoryResponse Ftp directory response
|
||||
///
|
||||
/// \return sfTrue if the status is a success, sfFalse if it is a failure
|
||||
///
|
||||
////////////////////////////////////////////////////////////
|
||||
CSFML_API sfBool sfFtpDirectoryResponse_IsOk(const sfFtpDirectoryResponse* ftpDirectoryResponse);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Get the response status code
|
||||
/// \brief Get the status code of a FTP directory response
|
||||
///
|
||||
/// \param ftpDirectoryResponse : Ftp directory response
|
||||
/// \param ftpDirectoryResponse Ftp directory response
|
||||
///
|
||||
/// \return Status code
|
||||
///
|
||||
@@ -202,9 +207,9 @@ CSFML_API sfBool sfFtpDirectoryResponse_IsOk(const sfFtpDirectoryResponse* ftpDi
|
||||
CSFML_API sfFtpStatus sfFtpDirectoryResponse_GetStatus(const sfFtpDirectoryResponse* ftpDirectoryResponse);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Get the full message contained in the response
|
||||
/// \brief Get the full message contained in a FTP directory response
|
||||
///
|
||||
/// \param ftpDirectoryResponse : Ftp directory response
|
||||
/// \param ftpDirectoryResponse Ftp directory response
|
||||
///
|
||||
/// \return The response message
|
||||
///
|
||||
@@ -212,9 +217,9 @@ CSFML_API sfFtpStatus sfFtpDirectoryResponse_GetStatus(const sfFtpDirectoryRespo
|
||||
CSFML_API const char* sfFtpDirectoryResponse_GetMessage(const sfFtpDirectoryResponse* ftpDirectoryResponse);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Get the directory returned in the response
|
||||
/// \brief Get the directory returned in a FTP directory response
|
||||
///
|
||||
/// \param ftpDirectoryResponse : Ftp directory response
|
||||
/// \param ftpDirectoryResponse Ftp directory response
|
||||
///
|
||||
/// \return Directory name
|
||||
///
|
||||
@@ -223,28 +228,30 @@ CSFML_API const char* sfFtpDirectoryResponse_GetDirectory(const sfFtpDirectoryRe
|
||||
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Destroy an existing Ftp response
|
||||
/// \brief Destroy a FTP response
|
||||
///
|
||||
/// \param ftpResponse : Ftp response to destroy
|
||||
/// \param ftpResponse Ftp response to destroy
|
||||
///
|
||||
////////////////////////////////////////////////////////////
|
||||
CSFML_API void sfFtpResponse_Destroy(sfFtpResponse* ftpResponse);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Convenience function to check if the response status code
|
||||
/// means a success
|
||||
/// \brief Check if a FTP response status code means a success
|
||||
///
|
||||
/// \param ftpResponse : Ftp response
|
||||
/// This function is defined for convenience, it is
|
||||
/// equivalent to testing if the status code is < 400.
|
||||
///
|
||||
/// \return sfTrue if status is success (code < 400)
|
||||
/// \param ftpResponse Ftp response object
|
||||
///
|
||||
/// \return sfTrue if the status is a success, sfFalse if it is a failure
|
||||
///
|
||||
////////////////////////////////////////////////////////////
|
||||
CSFML_API sfBool sfFtpResponse_IsOk(const sfFtpResponse* ftpResponse);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Get the response status code
|
||||
/// \brief Get the status code of a FTP response
|
||||
///
|
||||
/// \param ftpResponse : Ftp response
|
||||
/// \param ftpResponse Ftp response object
|
||||
///
|
||||
/// \return Status code
|
||||
///
|
||||
@@ -252,9 +259,9 @@ CSFML_API sfBool sfFtpResponse_IsOk(const sfFtpResponse* ftpResponse);
|
||||
CSFML_API sfFtpStatus sfFtpResponse_GetStatus(const sfFtpResponse* ftpResponse);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Get the full message contained in the response
|
||||
/// \brief Get the full message contained in a FTP response
|
||||
///
|
||||
/// \param ftpResponse : Ftp response
|
||||
/// \param ftpResponse Ftp response object
|
||||
///
|
||||
/// \return The response message
|
||||
///
|
||||
@@ -262,28 +269,37 @@ CSFML_API sfFtpStatus sfFtpResponse_GetStatus(const sfFtpResponse* ftpResponse);
|
||||
CSFML_API const char* sfFtpResponse_GetMessage(const sfFtpResponse* ftpResponse);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Construct a new Ftp
|
||||
/// \brief Create a new Ftp object
|
||||
///
|
||||
/// \return Pointer to the new Ftp
|
||||
/// \return A new sfFtp object
|
||||
///
|
||||
////////////////////////////////////////////////////////////
|
||||
CSFML_API sfFtp* sfFtp_Create(void);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Destroy an existing Ftp
|
||||
/// \brief Destroy a Ftp object
|
||||
///
|
||||
/// \param ftp : Ftp to destroy
|
||||
/// \param ftp Ftp object to destroy
|
||||
///
|
||||
////////////////////////////////////////////////////////////
|
||||
CSFML_API void sfFtp_Destroy(sfFtp* ftp);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Connect to the specified FTP server
|
||||
/// \brief Connect to the specified FTP server
|
||||
///
|
||||
/// \param ftp : Ftp instance
|
||||
/// \param server : FTP server to connect to
|
||||
/// \param port : Port used for connection (21 by default, standard FTP port)
|
||||
/// \param timeout : Maximum time to wait, in milliseconds (0 to use no timeout)
|
||||
/// The port should be 21, which is the standard
|
||||
/// port used by the FTP protocol. You shouldn't use a different
|
||||
/// value, unless you really know what you do.
|
||||
/// This function tries to connect to the server so it may take
|
||||
/// a while to complete, especially if the server is not
|
||||
/// reachable. To avoid blocking your application for too long,
|
||||
/// you can use a timeout. Using 0 means that the
|
||||
/// system timeout will be used (which is usually pretty long).
|
||||
///
|
||||
/// \param ftp Ftp object
|
||||
/// \param server Name or address of the FTP server to connect to
|
||||
/// \param port Port used for the connection
|
||||
/// \param timeout Maximum time to wait, in milliseconds
|
||||
///
|
||||
/// \return Server response to the request
|
||||
///
|
||||
@@ -291,9 +307,12 @@ CSFML_API void sfFtp_Destroy(sfFtp* ftp);
|
||||
CSFML_API sfFtpResponse* sfFtp_Connect(sfFtp* ftp, sfIpAddress server, unsigned short port, sfUint32 timeout);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Log in using anonymous account
|
||||
/// \brief Log in using an anonymous account
|
||||
///
|
||||
/// \param ftp : Ftp instance
|
||||
/// Logging in is mandatory after connecting to the server.
|
||||
/// Users that are not logged in cannot perform any operation.
|
||||
///
|
||||
/// \param ftp Ftp object
|
||||
///
|
||||
/// \return Server response to the request
|
||||
///
|
||||
@@ -301,11 +320,14 @@ CSFML_API sfFtpResponse* sfFtp_Connect(sfFtp* ftp, sfIpAddress server, unsigned
|
||||
CSFML_API sfFtpResponse* sfFtp_LoginAnonymous(sfFtp* ftp);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Log in using a username and a password
|
||||
/// \brief Log in using a username and a password
|
||||
///
|
||||
/// \param ftp : Ftp instance
|
||||
/// \param userName : User name
|
||||
/// \param password : Password
|
||||
/// Logging in is mandatory after connecting to the server.
|
||||
/// Users that are not logged in cannot perform any operation.
|
||||
///
|
||||
/// \param ftp Ftp object
|
||||
/// \param name User name
|
||||
/// \param password Password
|
||||
///
|
||||
/// \return Server response to the request
|
||||
///
|
||||
@@ -313,9 +335,9 @@ CSFML_API sfFtpResponse* sfFtp_LoginAnonymous(sfFtp* ftp);
|
||||
CSFML_API sfFtpResponse* sfFtp_Login(sfFtp* ftp, const char* userName, const char* password);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Close the connection with FTP server
|
||||
/// \brief Close the connection with the server
|
||||
///
|
||||
/// \param ftp : Ftp instance
|
||||
/// \param ftp Ftp object
|
||||
///
|
||||
/// \return Server response to the request
|
||||
///
|
||||
@@ -323,9 +345,12 @@ CSFML_API sfFtpResponse* sfFtp_Login(sfFtp* ftp, const char* userName, const cha
|
||||
CSFML_API sfFtpResponse* sfFtp_Disconnect(sfFtp* ftp);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Send a null command just to prevent from being disconnected
|
||||
/// \brief Send a null command to keep the connection alive
|
||||
///
|
||||
/// \param ftp : Ftp instance
|
||||
/// This command is useful because the server may close the
|
||||
/// connection automatically if no command is sent.
|
||||
///
|
||||
/// \param ftp Ftp object
|
||||
///
|
||||
/// \return Server response to the request
|
||||
///
|
||||
@@ -333,9 +358,12 @@ CSFML_API sfFtpResponse* sfFtp_Disconnect(sfFtp* ftp);
|
||||
CSFML_API sfFtpResponse* sfFtp_KeepAlive(sfFtp* ftp);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Get the current working directory
|
||||
/// \brief Get the current working directory
|
||||
///
|
||||
/// \param ftp : Ftp instance
|
||||
/// The working directory is the root path for subsequent
|
||||
/// operations involving directories and/or filenames.
|
||||
///
|
||||
/// \param ftp Ftp object
|
||||
///
|
||||
/// \return Server response to the request
|
||||
///
|
||||
@@ -343,11 +371,15 @@ CSFML_API sfFtpResponse* sfFtp_KeepAlive(sfFtp* ftp);
|
||||
CSFML_API sfFtpDirectoryResponse* sfFtp_GetWorkingDirectory(sfFtp* ftp);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Get the contents of the given directory
|
||||
/// (subdirectories and files)
|
||||
/// \brief Get the contents of the given directory
|
||||
///
|
||||
/// \param ftp : Ftp instance
|
||||
/// \param directory : Directory to list ("" by default, the current one)
|
||||
/// This function retrieves the sub-directories and files
|
||||
/// contained in the given directory. It is not recursive.
|
||||
/// The \a directory parameter is relative to the current
|
||||
/// working directory.
|
||||
///
|
||||
/// \param ftp Ftp object
|
||||
/// \param directory Directory to list
|
||||
///
|
||||
/// \return Server response to the request
|
||||
///
|
||||
@@ -355,10 +387,12 @@ CSFML_API sfFtpDirectoryResponse* sfFtp_GetWorkingDirectory(sfFtp* ftp);
|
||||
CSFML_API sfFtpListingResponse* sfFtp_GetDirectoryListing(sfFtp* ftp, const char* directory);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Change the current working directory
|
||||
/// \brief Change the current working directory
|
||||
///
|
||||
/// \param ftp : Ftp instance
|
||||
/// \param directory : New directory, relative to the current one
|
||||
/// The new directory must be relative to the current one.
|
||||
///
|
||||
/// \param ftp Ftp object
|
||||
/// \param directory New working directory
|
||||
///
|
||||
/// \return Server response to the request
|
||||
///
|
||||
@@ -366,9 +400,9 @@ CSFML_API sfFtpListingResponse* sfFtp_GetDirectoryListing(sfFtp* ftp, const char
|
||||
CSFML_API sfFtpResponse* sfFtp_ChangeDirectory(sfFtp* ftp, const char* directory);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Go to the parent directory of the current one
|
||||
/// \brief Go to the parent directory of the current one
|
||||
///
|
||||
/// \param ftp : Ftp instance
|
||||
/// \param ftp Ftp object
|
||||
///
|
||||
/// \return Server response to the request
|
||||
///
|
||||
@@ -376,10 +410,13 @@ CSFML_API sfFtpResponse* sfFtp_ChangeDirectory(sfFtp* ftp, const char* directory
|
||||
CSFML_API sfFtpResponse* sfFtp_ParentDirectory(sfFtp* ftp);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Create a new directory
|
||||
/// \brief Create a new directory
|
||||
///
|
||||
/// \param ftp : Ftp instance
|
||||
/// \param name : Name of the directory to create
|
||||
/// The new directory is created as a child of the current
|
||||
/// working directory.
|
||||
///
|
||||
/// \param ftp Ftp object
|
||||
/// \param name Name of the directory to create
|
||||
///
|
||||
/// \return Server response to the request
|
||||
///
|
||||
@@ -387,10 +424,15 @@ CSFML_API sfFtpResponse* sfFtp_ParentDirectory(sfFtp* ftp);
|
||||
CSFML_API sfFtpResponse* sfFtp_CreateDirectory(sfFtp* ftp, const char* name);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Remove an existing directory
|
||||
/// \brief Remove an existing directory
|
||||
///
|
||||
/// \param ftp : Ftp instance
|
||||
/// \param name : Name of the directory to remove
|
||||
/// The directory to remove must be relative to the
|
||||
/// current working directory.
|
||||
/// Use this function with caution, the directory will
|
||||
/// be removed permanently!
|
||||
///
|
||||
/// \param ftp Ftp object
|
||||
/// \param name Name of the directory to remove
|
||||
///
|
||||
/// \return Server response to the request
|
||||
///
|
||||
@@ -398,11 +440,14 @@ CSFML_API sfFtpResponse* sfFtp_CreateDirectory(sfFtp* ftp, const char* name);
|
||||
CSFML_API sfFtpResponse* sfFtp_DeleteDirectory(sfFtp* ftp, const char* name);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Rename a file
|
||||
/// \brief Rename an existing file
|
||||
///
|
||||
/// \param ftp : Ftp instance
|
||||
/// \param file : File to rename
|
||||
/// \param newName : New name
|
||||
/// The filenames must be relative to the current working
|
||||
/// directory.
|
||||
///
|
||||
/// \param ftp Ftp object
|
||||
/// \param file File to rename
|
||||
/// \param newName New name of the file
|
||||
///
|
||||
/// \return Server response to the request
|
||||
///
|
||||
@@ -410,10 +455,15 @@ CSFML_API sfFtpResponse* sfFtp_DeleteDirectory(sfFtp* ftp, const char* name);
|
||||
CSFML_API sfFtpResponse* sfFtp_RenameFile(sfFtp* ftp, const char* file, const char* newName);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Remove an existing file
|
||||
/// \brief Remove an existing file
|
||||
///
|
||||
/// \param ftp : Ftp instance
|
||||
/// \param name : File to remove
|
||||
/// The file name must be relative to the current working
|
||||
/// directory.
|
||||
/// Use this function with caution, the file will be
|
||||
/// removed permanently!
|
||||
///
|
||||
/// \param ftp Ftp object
|
||||
/// \param name File to remove
|
||||
///
|
||||
/// \return Server response to the request
|
||||
///
|
||||
@@ -421,12 +471,17 @@ CSFML_API sfFtpResponse* sfFtp_RenameFile(sfFtp* ftp, const char* file, const ch
|
||||
CSFML_API sfFtpResponse* sfFtp_DeleteFile(sfFtp* ftp, const char* name);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Download a file from the server
|
||||
/// \brief Download a file from a FTP server
|
||||
///
|
||||
/// \param ftp : Ftp instance
|
||||
/// \param distantFile : Path of the distant file to download
|
||||
/// \param destPath : Where to put to file on the local computer
|
||||
/// \param mode : Transfer mode (binary by default)
|
||||
/// The filename of the distant file is relative to the
|
||||
/// current working directory of the server, and the local
|
||||
/// destination path is relative to the current directory
|
||||
/// of your application.
|
||||
///
|
||||
/// \param ftp Ftp object
|
||||
/// \param remoteFile Filename of the distant file to download
|
||||
/// \param localPath Where to put to file on the local computer
|
||||
/// \param mode Transfer mode
|
||||
///
|
||||
/// \return Server response to the request
|
||||
///
|
||||
@@ -434,12 +489,17 @@ CSFML_API sfFtpResponse* sfFtp_DeleteFile(sfFtp* ftp, const char* name);
|
||||
CSFML_API sfFtpResponse* sfFtp_Download(sfFtp* ftp, const char* distantFile, const char* destPath, sfFtpTransferMode mode);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Upload a file to the server
|
||||
/// \brief Upload a file to a FTP server
|
||||
///
|
||||
/// \param ftp : Ftp instance
|
||||
/// \param localFile : Path of the local file to upload
|
||||
/// \param destPath : Where to put to file on the server
|
||||
/// \param mode : Transfer mode (binary by default)
|
||||
/// The name of the local file is relative to the current
|
||||
/// working directory of your application, and the
|
||||
/// remote path is relative to the current directory of the
|
||||
/// FTP server.
|
||||
///
|
||||
/// \param ftp Ftp object
|
||||
/// \param localFile Path of the local file to upload
|
||||
/// \param remotePath Where to put to file on the server
|
||||
/// \param mode Transfer mode
|
||||
///
|
||||
/// \return Server response to the request
|
||||
///
|
||||
|
||||
+107
-68
@@ -33,7 +33,8 @@
|
||||
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Enumerate the available HTTP methods for a request
|
||||
/// \brief Enumerate the available HTTP methods for a request
|
||||
///
|
||||
////////////////////////////////////////////////////////////
|
||||
enum sfHttpMethod
|
||||
{
|
||||
@@ -44,8 +45,8 @@ enum sfHttpMethod
|
||||
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Enumerate all the valid status codes returned in
|
||||
/// a HTTP response
|
||||
/// \brief Enumerate all the valid status codes for a response
|
||||
///
|
||||
////////////////////////////////////////////////////////////
|
||||
enum sfHttpStatus
|
||||
{
|
||||
@@ -80,175 +81,213 @@ enum sfHttpStatus
|
||||
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Construct a new Http request
|
||||
/// \brief Create a new HTTP request
|
||||
///
|
||||
/// \return Pointer to the new Http request
|
||||
/// \return A new sfHttpRequest object
|
||||
///
|
||||
////////////////////////////////////////////////////////////
|
||||
CSFML_API sfHttpRequest* sfHttpRequest_Create(void);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Destroy an existing Http request
|
||||
/// \brief Destroy a HTTP request
|
||||
///
|
||||
/// \param httpRequest : Http request to destroy
|
||||
/// \param httpRequest HTTP request to destroy
|
||||
///
|
||||
////////////////////////////////////////////////////////////
|
||||
CSFML_API void sfHttpRequest_Destroy(sfHttpRequest* httpRequest);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Set the value of a field; the field is added if it doesn't exist
|
||||
/// \brief Set the value of a header field of a HTTP request
|
||||
///
|
||||
/// \param httpRequest : Http request to modify
|
||||
/// \param field : Name of the field to set (case-insensitive)
|
||||
/// \param value : Value of the field
|
||||
/// The field is created if it doesn't exist. The name of
|
||||
/// the field is case insensitive.
|
||||
/// By default, a request doesn't contain any field (but the
|
||||
/// mandatory fields are added later by the HTTP client when
|
||||
/// sending the request).
|
||||
///
|
||||
/// \param httpRequest HTTP request
|
||||
/// \param field Name of the field to set
|
||||
/// \param value Value of the field
|
||||
///
|
||||
////////////////////////////////////////////////////////////
|
||||
CSFML_API void sfHttpRequest_SetField(sfHttpRequest* httpRequest, const char* field, const char* value);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Set the request method.
|
||||
/// This parameter is sfHttpGet by default
|
||||
/// \brief Set a HTTP request method
|
||||
///
|
||||
/// \param httpRequest : Http request to modify
|
||||
/// \param method : Method to use for the request
|
||||
/// See the sfHttpMethod enumeration for a complete list of all
|
||||
/// the availale methods.
|
||||
/// The method is sfHttpGet by default.
|
||||
///
|
||||
/// \param httpRequest HTTP request
|
||||
/// \param method Method to use for the request
|
||||
///
|
||||
////////////////////////////////////////////////////////////
|
||||
CSFML_API void sfHttpRequest_SetMethod(sfHttpRequest* httpRequest, sfHttpMethod method);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Set the target URI of the request.
|
||||
/// This parameter is "/" by default
|
||||
/// \brief Set a HTTP request URI
|
||||
///
|
||||
/// \param httpRequest : Http request to modify
|
||||
/// \param URI : URI to request, local to the host
|
||||
/// The URI is the resource (usually a web page or a file)
|
||||
/// that you want to get or post.
|
||||
/// The URI is "/" (the root page) by default.
|
||||
///
|
||||
/// \param httpRequest HTTP request
|
||||
/// \param uri URI to request, relative to the host
|
||||
///
|
||||
////////////////////////////////////////////////////////////
|
||||
CSFML_API void sfHttpRequest_SetUri(sfHttpRequest* httpRequest, const char* uri);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Set the HTTP version of the request.
|
||||
/// This parameter is 1.0 by default
|
||||
/// \brief Set the HTTP version of a HTTP request
|
||||
///
|
||||
/// \param httpRequest : Http request to modify
|
||||
/// \param major : Major version number
|
||||
/// \param minor : Minor version number
|
||||
/// The HTTP version is 1.0 by default.
|
||||
///
|
||||
/// \param httpRequest HTTP request
|
||||
/// \param major Major HTTP version number
|
||||
/// \param minor Minor HTTP version number
|
||||
///
|
||||
////////////////////////////////////////////////////////////
|
||||
CSFML_API void sfHttpRequest_SetHttpVersion(sfHttpRequest* httpRequest, unsigned int major, unsigned int minor);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Set the body of the request. This parameter is optional and
|
||||
/// makes sense only for POST requests.
|
||||
/// This parameter is empty by default
|
||||
/// \brief Set the body of a HTTP request
|
||||
///
|
||||
/// \param httpRequest : Http request to modify
|
||||
/// \param body : Content of the request body
|
||||
/// The body of a request is optional and only makes sense
|
||||
/// for POST requests. It is ignored for all other methods.
|
||||
/// The body is empty by default.
|
||||
///
|
||||
/// \param httpRequest HTTP request
|
||||
/// \param body Content of the body
|
||||
///
|
||||
////////////////////////////////////////////////////////////
|
||||
CSFML_API void sfHttpRequest_SetBody(sfHttpRequest* httpRequest, const char* body);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Destroy an existing Http response
|
||||
/// \brief Destroy a HTTP response
|
||||
///
|
||||
/// \param httpResponse : Http response to destroy
|
||||
/// \param httpResponse HTTP response to destroy
|
||||
///
|
||||
////////////////////////////////////////////////////////////
|
||||
CSFML_API void sfHttpResponse_Destroy(sfHttpResponse* httpResponse);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Get the value of a field; returns NULL if the field doesn't exist
|
||||
/// \brief Get the value of a field of a HTTP response
|
||||
///
|
||||
/// \param httpResponse : Http response
|
||||
/// \param field : Field to get
|
||||
/// If the field \a field is not found in the response header,
|
||||
/// the empty string is returned. This function uses
|
||||
/// case-insensitive comparisons.
|
||||
///
|
||||
/// \return Value of the field (NULL if it doesn't exist)
|
||||
/// \param httpResponse HTTP response
|
||||
/// \param field Name of the field to get
|
||||
///
|
||||
/// \return Value of the field, or empty string if not found
|
||||
///
|
||||
////////////////////////////////////////////////////////////
|
||||
CSFML_API const char* sfHttpResponse_GetField(const sfHttpResponse* httpResponse, const char* field);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Get the status of a response
|
||||
/// \brief Get the status code of a HTTP reponse
|
||||
///
|
||||
/// \param httpResponse : Http response
|
||||
/// The status code should be the first thing to be checked
|
||||
/// after receiving a response, it defines whether it is a
|
||||
/// success, a failure or anything else (see the sfHttpStatus
|
||||
/// enumeration).
|
||||
///
|
||||
/// \return Status of the response
|
||||
/// \param httpResponse HTTP response
|
||||
///
|
||||
/// \return Status code of the response
|
||||
///
|
||||
////////////////////////////////////////////////////////////
|
||||
CSFML_API sfHttpStatus sfHttpResponse_GetStatus(const sfHttpResponse* httpResponse);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Get the major HTTP version of a response
|
||||
/// \brief Get the major HTTP version number of a HTTP response
|
||||
///
|
||||
/// \param httpResponse : Http response
|
||||
/// \param httpResponse HTTP response
|
||||
///
|
||||
/// \return HTTP major version of the response
|
||||
/// \return Major HTTP version number
|
||||
///
|
||||
////////////////////////////////////////////////////////////
|
||||
CSFML_API unsigned int sfHttpResponse_GetMajorVersion(const sfHttpResponse* httpResponse);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Get the minor HTTP version of a response
|
||||
/// \brief Get the minor HTTP version number of a HTTP response
|
||||
///
|
||||
/// \param httpResponse : Http response
|
||||
/// \param httpResponse HTTP response
|
||||
///
|
||||
/// \return HTTP minor version of the response
|
||||
/// \return Minor HTTP version number
|
||||
///
|
||||
////////////////////////////////////////////////////////////
|
||||
CSFML_API unsigned int sfHttpResponse_GetMinorVersion(const sfHttpResponse* httpResponse);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Get the body of the response. The body can contain :
|
||||
/// - the requested page (for GET requests)
|
||||
/// - a response from the server (for POST requests)
|
||||
/// - nothing (for HEAD requests)
|
||||
/// - an error message (in case of an error)
|
||||
/// \brief Get the body of a HTTP response
|
||||
///
|
||||
/// \param httpResponse : Http response
|
||||
/// The body of a response may contain:
|
||||
/// \li the requested page (for GET requests)
|
||||
/// \li a response from the server (for POST requests)
|
||||
/// \li nothing (for HEAD requests)
|
||||
/// \li an error message (in case of an error)
|
||||
///
|
||||
/// \return Body of the response (empty string if no body)
|
||||
/// \param httpResponse HTTP response
|
||||
///
|
||||
/// \return The response body
|
||||
///
|
||||
////////////////////////////////////////////////////////////
|
||||
CSFML_API const char* sfHttpResponse_GetBody(const sfHttpResponse* httpResponse);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Construct a new Http object
|
||||
/// \brief Create a new Http object
|
||||
///
|
||||
/// \return Pointer to the new Http
|
||||
/// \return A new sfHttp object
|
||||
///
|
||||
////////////////////////////////////////////////////////////
|
||||
CSFML_API sfHttp* sfHttp_Create(void);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Destroy an existing Http object
|
||||
/// \brief Destroy a Http object
|
||||
///
|
||||
/// \param Http : Http to destroy
|
||||
/// \param http Http object to destroy
|
||||
///
|
||||
////////////////////////////////////////////////////////////
|
||||
CSFML_API void sfHttp_Destroy(sfHttp* http);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Set the target host of a Http server
|
||||
/// \brief Set the target host of a HTTP object
|
||||
///
|
||||
/// \param http : Http object
|
||||
/// \param host : Web server to connect to
|
||||
/// \param port : Port to use for connection (0 to use the standard port of the protocol used)
|
||||
/// This function just stores the host address and port, it
|
||||
/// doesn't actually connect to it until you send a request.
|
||||
/// If the port is 0, it means that the HTTP client will use
|
||||
/// the right port according to the protocol used
|
||||
/// (80 for HTTP, 443 for HTTPS). You should
|
||||
/// leave it like this unless you really need a port other
|
||||
/// than the standard one, or use an unknown protocol.
|
||||
///
|
||||
/// \param http Http object
|
||||
/// \param host Web server to connect to
|
||||
/// \param port Port to use for connection
|
||||
///
|
||||
////////////////////////////////////////////////////////////
|
||||
CSFML_API void sfHttp_SetHost(sfHttp* http, const char* host, unsigned short port);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Send a HTTP request and return the server's response.
|
||||
/// You must be connected to a host before sending requests.
|
||||
/// Any missing mandatory header field will be added with an appropriate value.
|
||||
/// Warning : this function waits for the server's response and may
|
||||
/// \brief Send a HTTP request and return the server's response.
|
||||
///
|
||||
/// You must have a valid host before sending a request (see sfHttp_SetHost).
|
||||
/// Any missing mandatory header field in the request will be added
|
||||
/// with an appropriate value.
|
||||
/// Warning: this function waits for the server's response and may
|
||||
/// not return instantly; use a thread if you don't want to block your
|
||||
/// application.
|
||||
/// application, or use a timeout to limit the time to wait. A value
|
||||
/// of 0 means that the client will use the system defaut timeout
|
||||
/// (which is usually pretty long).
|
||||
///
|
||||
/// \param http : Http object
|
||||
/// \param request : Request to send
|
||||
/// \param timeout : Maximum time to wait, in milliseconds (0 to use no timeout)
|
||||
/// \param http Http object
|
||||
/// \param request Request to send
|
||||
/// \param timeout Maximum time to wait, in milliseconds
|
||||
///
|
||||
/// \return Server's response, or NULL if request is invalid
|
||||
/// \return Server's response
|
||||
///
|
||||
////////////////////////////////////////////////////////////
|
||||
CSFML_API sfHttpResponse* sfHttp_SendRequest(sfHttp* http, const sfHttpRequest* request, sfUint32 timeout);
|
||||
|
||||
@@ -32,7 +32,8 @@
|
||||
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// sfIpAddress provides easy manipulation of IP v4 addresses
|
||||
/// \brief Encapsulate an IPv4 network address
|
||||
///
|
||||
////////////////////////////////////////////////////////////
|
||||
typedef struct
|
||||
{
|
||||
@@ -41,22 +42,30 @@ typedef struct
|
||||
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Construct an address from a string
|
||||
/// \brief Create an address from a string
|
||||
///
|
||||
/// \param string : IP address ("xxx.xxx.xxx.xxx") or network name
|
||||
/// Here \a address can be either a decimal address
|
||||
/// (ex: "192.168.1.56") or a network name (ex: "localhost").
|
||||
///
|
||||
/// \param address IP address or network name
|
||||
///
|
||||
/// \return Resulting address
|
||||
///
|
||||
////////////////////////////////////////////////////////////
|
||||
CSFML_API sfIpAddress sfIpAddress_FromString(const char* string);
|
||||
CSFML_API sfIpAddress sfIpAddress_FromString(const char* address);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Construct an address from 4 bytes
|
||||
/// \brief Create an address from 4 bytes
|
||||
///
|
||||
/// \param byte0 : First byte of the address
|
||||
/// \param byte1 : Second byte of the address
|
||||
/// \param byte2 : Third byte of the address
|
||||
/// \param byte3 : Fourth byte of the address
|
||||
/// Calling sfIpAddress_FromBytes(a, b, c, d) is equivalent
|
||||
/// to calling sfIpAddress_FromString("a.b.c.d"), but safer
|
||||
/// as it doesn't have to parse a string to get the address
|
||||
/// components.
|
||||
///
|
||||
/// \param byte0 First byte of the address
|
||||
/// \param byte1 Second byte of the address
|
||||
/// \param byte2 Third byte of the address
|
||||
/// \param byte3 Fourth byte of the address
|
||||
///
|
||||
/// \return Resulting address
|
||||
///
|
||||
@@ -64,55 +73,88 @@ CSFML_API sfIpAddress sfIpAddress_FromString(const char* string);
|
||||
CSFML_API sfIpAddress sfIpAddress_FromBytes(sfUint8 byte0, sfUint8 byte1, sfUint8 byte2, sfUint8 byte3);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Construct the address from a 32-bits integer
|
||||
/// \brief Construct an address from a 32-bits integer
|
||||
///
|
||||
/// \param address : 4 bytes of the address packed into a 32-bits integer
|
||||
/// This function uses the internal representation of
|
||||
/// the address directly. It should be used for optimization
|
||||
/// purposes, and only if you got that representation from
|
||||
/// sfIpAddress_ToInteger.
|
||||
///
|
||||
/// \param address 4 bytes of the address packed into a 32-bits integer
|
||||
///
|
||||
/// \return Resulting address
|
||||
///
|
||||
////////////////////////////////////////////////////////////
|
||||
CSFML_API sfIpAddress sfIpAddress_FromInteger(sfUint32 address);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Get a string representation of an address
|
||||
/// \brief Get a string representation of an address
|
||||
///
|
||||
/// \param address : Address to convert
|
||||
/// \param string : Char array to fill (size must be >= 16)
|
||||
/// The returned string is the decimal representation of the
|
||||
/// IP address (like "192.168.1.56"), even if it was constructed
|
||||
/// from a host name.
|
||||
///
|
||||
/// \param address Address object
|
||||
///
|
||||
/// \return String representation of the address
|
||||
///
|
||||
////////////////////////////////////////////////////////////
|
||||
CSFML_API void sfIpAddress_ToString(sfIpAddress address, char* string);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Get an integer representation of the address
|
||||
/// \brief Get an integer representation of the address
|
||||
///
|
||||
/// \param address : Address to convert
|
||||
/// The returned number is the internal representation of the
|
||||
/// address, and should be used for optimization purposes only
|
||||
/// (like sending the address through a socket).
|
||||
/// The integer produced by this function can then be converted
|
||||
/// back to a sfIpAddress with sfIpAddress_FromInteger.
|
||||
///
|
||||
/// \return 32-bits integer containing the 4 bytes of the address, in system endianness
|
||||
/// \param address Address object
|
||||
///
|
||||
/// \return 32-bits unsigned integer representation of the address
|
||||
///
|
||||
////////////////////////////////////////////////////////////
|
||||
CSFML_API sfUint32 sfIpAddress_ToInteger(sfIpAddress address);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Get the computer's local IP address (from the LAN point of view)
|
||||
/// \brief Get the computer's local address
|
||||
///
|
||||
/// \return Local IP address
|
||||
/// The local address is the address of the computer from the
|
||||
/// LAN point of view, i.e. something like 192.168.1.56. It is
|
||||
/// meaningful only for communications over the local network.
|
||||
/// Unlike sfIpAddress_GetPublicAddress, this function is fast
|
||||
/// and may be used safely anywhere.
|
||||
///
|
||||
/// \return Local IP address of the computer
|
||||
///
|
||||
////////////////////////////////////////////////////////////
|
||||
CSFML_API sfIpAddress sfIpAddress_GetLocalAddress(void);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Get the computer's public IP address (from the web point of view).
|
||||
/// \brief Get the computer's public address
|
||||
///
|
||||
/// The public address is the address of the computer from the
|
||||
/// internet point of view, i.e. something like 89.54.1.169.
|
||||
/// It is necessary for communications over the world wide web.
|
||||
/// The only way to get a public address is to ask it to a
|
||||
/// distant website ; as a consequence, this function may be
|
||||
/// very slow -- use it as few as possible !
|
||||
/// distant website; as a consequence, this function depends on
|
||||
/// both your network connection and the server, and may be
|
||||
/// very slow. You should use it as few as possible. Because
|
||||
/// this function depends on the network connection and on a distant
|
||||
/// server, you may use a time limit if you don't want your program
|
||||
/// to be possibly stuck waiting in case there is a problem; use
|
||||
/// 0 to deactivate this limit.
|
||||
///
|
||||
/// \param timeout : Maximum time to wait, in milliseconds (use 0 for no timeout)
|
||||
/// \param timeout Maximum time to wait, in milliseconds
|
||||
///
|
||||
/// \return Public IP address
|
||||
/// \return Public IP address of the computer
|
||||
///
|
||||
////////////////////////////////////////////////////////////
|
||||
CSFML_API sfIpAddress sfIpAddress_GetPublicAddress(sfUint32 timeout);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Get the computer's loopback address
|
||||
/// \brief Get the computer's loopback address
|
||||
///
|
||||
/// \return Local host IP address (127.0.0.1, or "localhost")
|
||||
///
|
||||
@@ -120,7 +162,7 @@ CSFML_API sfIpAddress sfIpAddress_GetPublicAddress(sfUint32 timeout);
|
||||
CSFML_API sfIpAddress sfIpAddress_LocalHost(void);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Get the empty/invalid address
|
||||
/// \brief Get the empty/invalid address
|
||||
///
|
||||
/// \return Empty object that represents invalid addresses
|
||||
///
|
||||
|
||||
@@ -34,7 +34,7 @@
|
||||
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Create a new empty packet
|
||||
/// \brief Create a new packet
|
||||
///
|
||||
/// \return A new sfPacket object
|
||||
///
|
||||
@@ -42,47 +42,52 @@
|
||||
CSFML_API sfPacket* sfPacket_Create(void);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Copy an existing packet
|
||||
/// \brief Create a new packet by copying an existing one
|
||||
///
|
||||
/// \param packet : Packet to copy
|
||||
/// \param packet Packet to copy
|
||||
///
|
||||
/// \return Copied object
|
||||
/// \return A new sfPacket object which is a copy of \a packet
|
||||
///
|
||||
////////////////////////////////////////////////////////////
|
||||
CSFML_API sfPacket* sfPacket_Copy(sfPacket* packet);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Destroy an existing packet
|
||||
/// \brief Destroy a packet
|
||||
///
|
||||
/// \param packet : Packet to delete
|
||||
/// \param packet Packet to destroy
|
||||
///
|
||||
////////////////////////////////////////////////////////////
|
||||
CSFML_API void sfPacket_Destroy(sfPacket* packet);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Append data to the end of a packet
|
||||
/// \brief Append data to the end of a packet
|
||||
///
|
||||
/// \param packet : Packet to fill
|
||||
/// \param data : Pointer to the bytes to append
|
||||
/// \param sizeInBytes : Number of bytes to append
|
||||
/// \param packet Packet object
|
||||
/// \param data Pointer to the sequence of bytes to append
|
||||
/// \param sizeInBytes Number of bytes to append
|
||||
///
|
||||
////////////////////////////////////////////////////////////
|
||||
CSFML_API void sfPacket_Append(sfPacket* packet, const void* data, size_t sizeInBytes);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Clear all the data of a packet
|
||||
/// \brief Clear a packet
|
||||
///
|
||||
/// \param packet : Packet to clear
|
||||
/// After calling Clear, the packet is empty.
|
||||
///
|
||||
/// \param packet Packet object
|
||||
///
|
||||
///////////////////////////////////////////////////////////
|
||||
CSFML_API void sfPacket_Clear(sfPacket* packet);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Get a pointer to the data contained in a packet
|
||||
/// Warning : the returned pointer may be invalid after you
|
||||
/// append data to the packet
|
||||
/// \brief Get a pointer to the data contained in a packet
|
||||
///
|
||||
/// \param packet : Packet to get data from
|
||||
/// Warning: the returned pointer may become invalid after
|
||||
/// you append data to the packet, therefore it should never
|
||||
/// be stored.
|
||||
/// The return pointer is NULL if the packet is empty.
|
||||
///
|
||||
/// \param packet Packet object
|
||||
///
|
||||
/// \return Pointer to the data
|
||||
///
|
||||
@@ -90,9 +95,12 @@ CSFML_API void sfPacket_Clear(sfPacket* packet);
|
||||
CSFML_API const char* sfPacket_GetData(const sfPacket* packet);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Get the size of the data contained in a packet
|
||||
/// \brief Get the size of the data contained in a packet
|
||||
///
|
||||
/// \param packet : Packet to get data size from
|
||||
/// This function returns the number of bytes pointed to by
|
||||
/// what sfPacket_GetData returns.
|
||||
///
|
||||
/// \param packet Packet object
|
||||
///
|
||||
/// \return Data size, in bytes
|
||||
///
|
||||
@@ -100,19 +108,29 @@ CSFML_API const char* sfPacket_GetData(const sfPacket* packet);
|
||||
CSFML_API size_t sfPacket_GetDataSize(const sfPacket* packet);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Tell if the reading position has reached the end of the packet
|
||||
/// \brief Tell if the reading position has reached the
|
||||
/// end of a packet
|
||||
///
|
||||
/// \param packet : Packet to check
|
||||
/// This function is useful to know if there is some data
|
||||
/// left to be read, without actually reading it.
|
||||
///
|
||||
/// \return sfTrue if all data have been read into the packet
|
||||
/// \param packet Packet object
|
||||
///
|
||||
/// \return sfTrue if all data was read, sfFalse otherwise
|
||||
///
|
||||
////////////////////////////////////////////////////////////
|
||||
CSFML_API sfBool sfPacket_EndOfPacket(const sfPacket* packet);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Return the validity of packet
|
||||
/// \brief Test the validity of a packet, for reading
|
||||
///
|
||||
/// \param packet : Packet to check
|
||||
/// This function allows to test the packet, to check if
|
||||
/// a reading operation was successful.
|
||||
///
|
||||
/// A packet will be in an invalid state if it has no more
|
||||
/// data to read.
|
||||
///
|
||||
/// \param packet Packet object
|
||||
///
|
||||
/// \return sfTrue if last data extraction from packet was successful
|
||||
///
|
||||
@@ -120,9 +138,9 @@ CSFML_API sfBool sfPacket_EndOfPacket(const sfPacket* packet);
|
||||
CSFML_API sfBool sfPacket_CanRead(const sfPacket* packet);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Functions to extract data from a packet
|
||||
/// \brief Functions to extract data from a packet
|
||||
///
|
||||
/// \param packet : Packet to read
|
||||
/// \param packet Packet object
|
||||
///
|
||||
////////////////////////////////////////////////////////////
|
||||
CSFML_API sfBool sfPacket_ReadBool(sfPacket* packet);
|
||||
@@ -138,9 +156,9 @@ CSFML_API void sfPacket_ReadString(sfPacket* packet, char* string);
|
||||
CSFML_API void sfPacket_ReadWideString(sfPacket* packet, wchar_t* string);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Functions to insert data into a packet
|
||||
/// \brief Functions to insert data into a packet
|
||||
///
|
||||
/// \param packet : Packet to write
|
||||
/// \param packet Packet object
|
||||
///
|
||||
////////////////////////////////////////////////////////////
|
||||
CSFML_API void sfPacket_WriteBool(sfPacket* packet, sfBool);
|
||||
|
||||
@@ -33,36 +33,40 @@
|
||||
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Create a new selector
|
||||
/// \brief Create a new selector
|
||||
///
|
||||
/// \return A new sfSelector object
|
||||
/// \return A new sfSocketSelector object
|
||||
///
|
||||
////////////////////////////////////////////////////////////
|
||||
CSFML_API sfSocketSelector* sfSocketSelector_Create(void);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Copy an existing selector
|
||||
/// \brief Create a new socket selector by copying an existing one
|
||||
///
|
||||
/// \param selector : Selector to copy
|
||||
/// \param selector Socket selector to copy
|
||||
///
|
||||
/// \return Copied object
|
||||
/// \return A new sfSocketSelector object which is a copy of \a selector
|
||||
///
|
||||
////////////////////////////////////////////////////////////
|
||||
CSFML_API sfSocketSelector* sfSocketSelector_Copy(sfSocketSelector* selector);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Destroy an existing selector
|
||||
/// \brief Destroy a socket selector
|
||||
///
|
||||
/// \param selector : Selector to delete
|
||||
/// \param selector Socket selector to destroy
|
||||
///
|
||||
////////////////////////////////////////////////////////////
|
||||
CSFML_API void sfSocketSelector_Destroy(sfSocketSelector* selector);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Add a socket to watch to a selector
|
||||
/// \brief Add a new socket to a socket selector
|
||||
///
|
||||
/// \param selector : Selector to add the socket to
|
||||
/// \param socket : Socket to add
|
||||
/// This function keeps a weak pointer to the socket,
|
||||
/// so you have to make sure that the socket is not destroyed
|
||||
/// while it is stored in the selector.
|
||||
///
|
||||
/// \param selector Socket selector object
|
||||
/// \param socket Pointer to the socket to add
|
||||
///
|
||||
////////////////////////////////////////////////////////////
|
||||
CSFML_API void sfSocketSelector_AddTcpListener(sfSocketSelector* selector, sfTcpListener* socket);
|
||||
@@ -70,10 +74,13 @@ CSFML_API void sfSocketSelector_AddTcpSocket(sfSocketSelector* selector, sfTcpSo
|
||||
CSFML_API void sfSocketSelector_AddUdpSocket(sfSocketSelector* selector, sfUdpSocket* socket);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Remove a socket from a selector
|
||||
/// \brief Remove a socket from a socket selector
|
||||
///
|
||||
/// \param selector : Selector to remove the socket from
|
||||
/// \param socket : Socket to remove
|
||||
/// This function doesn't destroy the socket, it simply
|
||||
/// removes the pointer that the selector has to it.
|
||||
///
|
||||
/// \param selector Socket selector object
|
||||
/// \param socket POointer to the socket to remove
|
||||
///
|
||||
////////////////////////////////////////////////////////////
|
||||
CSFML_API void sfSocketSelector_RemoveTcpListener(sfSocketSelector* selector, sfTcpListener* socket);
|
||||
@@ -81,20 +88,28 @@ CSFML_API void sfSocketSelector_RemoveTcpSocket(sfSocketSelector* selector, sfTc
|
||||
CSFML_API void sfSocketSelector_RemoveUdpSocket(sfSocketSelector* selector, sfUdpSocket* socket);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Remove all sockets from a selector
|
||||
/// \brief Remove all the sockets stored in a selector
|
||||
///
|
||||
/// \param selector : Selector to remove the socket from
|
||||
/// This function doesn't destroy any instance, it simply
|
||||
/// removes all the pointers that the selector has to
|
||||
/// external sockets.
|
||||
///
|
||||
/// \param selector Socket selector object
|
||||
///
|
||||
////////////////////////////////////////////////////////////
|
||||
CSFML_API void sfSocketSelector_Clear(sfSocketSelector* selector);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Wait and collect sockets which are ready for reading.
|
||||
/// This functions will return either when at least one socket
|
||||
/// is ready, or when the given timeout is over
|
||||
/// \brief Wait until one or more sockets are ready to receive
|
||||
///
|
||||
/// \param selector : Selector to check
|
||||
/// \param timeout : Maximum time to wait, in milliseconds (0 to disable timeout)
|
||||
/// This function returns as soon as at least one socket has
|
||||
/// some data available to be received. To know which sockets are
|
||||
/// ready, use the sfSocketSelector_IsXxxReady functions.
|
||||
/// If you use a timeout and no socket is ready before the timeout
|
||||
/// is over, the function returns sfFalse.
|
||||
///
|
||||
/// \param selector Socket selector object
|
||||
/// \param timeout Maximum time to wait, in milliseconds (use 0 for infinity)
|
||||
///
|
||||
/// \return sfTrue if there are sockets ready, sfFalse otherwise
|
||||
///
|
||||
@@ -102,12 +117,19 @@ CSFML_API void sfSocketSelector_Clear(sfSocketSelector* selector);
|
||||
CSFML_API sfBool sfSocketSelector_Wait(sfSocketSelector* selector, sfUint32 timeout);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Test a socket to know if it is ready to receive data
|
||||
/// \brief Test a socket to know if it is ready to receive data
|
||||
///
|
||||
/// \param selector : Selector to check
|
||||
/// \param socket : Socket to test
|
||||
/// This function must be used after a call to
|
||||
/// sfSocketSelector_Wait, to know which sockets are ready to
|
||||
/// receive data. If a socket is ready, a call to Receive will
|
||||
/// never block because we know that there is data available to read.
|
||||
/// Note that if this function returns sfTrue for a sfTcpListener,
|
||||
/// this means that it is ready to accept a new connection.
|
||||
///
|
||||
/// \return sfTrue if the socket is ready to receive data
|
||||
/// \param selector Socket selector object
|
||||
/// \param socket Socket to test
|
||||
///
|
||||
/// \return sfTrue if the socket is ready to read, sfFalse otherwise
|
||||
///
|
||||
////////////////////////////////////////////////////////////
|
||||
CSFML_API sfBool sfSocketSelector_IsTcpListenerReady(const sfSocketSelector* selector, sfTcpListener* socket);
|
||||
|
||||
@@ -27,15 +27,15 @@
|
||||
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Define the status that can be returned by the socket
|
||||
/// functions
|
||||
/// \brief Define the status that can be returned by the socket functions
|
||||
///
|
||||
////////////////////////////////////////////////////////////
|
||||
typedef enum
|
||||
{
|
||||
sfSocketDone,
|
||||
sfSocketNotReady,
|
||||
sfSocketDisconnected,
|
||||
sfSocketError
|
||||
sfSocketDone, ///< The socket has sent / received the data
|
||||
sfSocketNotReady, ///< The socket is not ready to send / receive data yet
|
||||
sfSocketDisconnected, ///< The TCP socket has been disconnected
|
||||
sfSocketError ///< An unexpected error happened
|
||||
|
||||
} sfSocketStatus;
|
||||
|
||||
|
||||
@@ -34,64 +34,91 @@
|
||||
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Construct a new TCP socket
|
||||
/// \brief Create a new TCP listener
|
||||
///
|
||||
/// \return Pointer to the new socket
|
||||
/// \return A new sfTcpListener object
|
||||
///
|
||||
////////////////////////////////////////////////////////////
|
||||
CSFML_API sfTcpListener* sfTcpListener_Create(void);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Destroy an existing TCP socket
|
||||
/// \brief Destroy a TCP listener
|
||||
///
|
||||
/// \param socket : Socket to destroy
|
||||
/// \param listener TCP listener to destroy
|
||||
///
|
||||
////////////////////////////////////////////////////////////
|
||||
CSFML_API void sfTcpListener_Destroy(sfTcpListener* socket);
|
||||
CSFML_API void sfTcpListener_Destroy(sfTcpListener* listener);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Change the blocking state of a TCP socket.
|
||||
/// The default behaviour of a socket is blocking
|
||||
/// \brief Set the blocking state of a TCP listener
|
||||
///
|
||||
/// \param socket : Socket to modify
|
||||
/// \param blocking : Pass sfTrue to set the socket as blocking, or sfFalse for non-blocking
|
||||
/// In blocking mode, calls will not return until they have
|
||||
/// completed their task. For example, a call to
|
||||
/// sfTcpListener_Accept in blocking mode won't return until
|
||||
/// a new connection was actually received.
|
||||
/// In non-blocking mode, calls will always return immediately,
|
||||
/// using the return code to signal whether there was data
|
||||
/// available or not.
|
||||
/// By default, all sockets are blocking.
|
||||
///
|
||||
/// \param listener TCP listener object
|
||||
/// \param blocking sfTrue to set the socket as blocking, sfFalse for non-blocking
|
||||
///
|
||||
////////////////////////////////////////////////////////////
|
||||
CSFML_API void sfTcpListener_SetBlocking(sfTcpListener* socket, sfBool blocking);
|
||||
CSFML_API void sfTcpListener_SetBlocking(sfTcpListener* listener, sfBool blocking);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Get the blocking state of the socket
|
||||
/// \brief Tell whether a TCP listener is in blocking or non-blocking mode
|
||||
///
|
||||
/// \param socket : Socket to read
|
||||
/// \param listener TCP listener object
|
||||
///
|
||||
/// \Return sfTrue if the socket is blocking, sfFalse otherwise
|
||||
/// \return sfTrue if the socket is blocking, sfFalse otherwise
|
||||
///
|
||||
////////////////////////////////////////////////////////////
|
||||
CSFML_API sfBool sfTcpListener_IsBlocking(const sfTcpListener* socket);
|
||||
CSFML_API sfBool sfTcpListener_IsBlocking(const sfTcpListener* listener);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Listen to a specified port for incoming data or connections
|
||||
/// \brief Get the port to which a TCP listener is bound locally
|
||||
///
|
||||
/// \param socket : Socket to use for listening
|
||||
/// \param port : Port to listen to
|
||||
/// If the socket is not listening to a port, this function
|
||||
/// returns 0.
|
||||
///
|
||||
/// \return Socket status
|
||||
/// \param listener TCP listener object
|
||||
///
|
||||
/// \return Port to which the TCP listener is bound
|
||||
///
|
||||
////////////////////////////////////////////////////////////
|
||||
CSFML_API sfSocketStatus sfTcpListener_Listen(sfTcpListener* socket, unsigned short port);
|
||||
CSFML_API unsigned short sfTcpListener_GetLocalPort(const sfTcpListener* listener);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Wait for a connection (must be listening to a port).
|
||||
/// This function is blocking, ie. it won't return before
|
||||
/// a connection has been accepted
|
||||
/// \brief Start listening for connections
|
||||
///
|
||||
/// \param socket : Socket to use for accepting
|
||||
/// \param connected : Pointer to a socket pointer that will be filled with the connected client
|
||||
/// This functions makes the socket listen to the specified
|
||||
/// port, waiting for new connections.
|
||||
/// If the socket was previously listening to another port,
|
||||
/// it will be stopped first and bound to the new port.
|
||||
///
|
||||
/// \return Socket status
|
||||
/// \param listener TCP listener object
|
||||
/// \param port Port to listen for new connections
|
||||
///
|
||||
/// \return Status code
|
||||
///
|
||||
////////////////////////////////////////////////////////////
|
||||
CSFML_API sfSocketStatus sfTcpListener_Accept(sfTcpListener* socket, sfTcpSocket** connected);
|
||||
CSFML_API sfSocketStatus sfTcpListener_Listen(sfTcpListener* listener, unsigned short port);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// \brief Accept a new connection
|
||||
///
|
||||
/// If the socket is in blocking mode, this function will
|
||||
/// not return until a connection is actually received.
|
||||
///
|
||||
/// \param listener TCP listener object
|
||||
/// \param connected Socket that will hold the new connection
|
||||
///
|
||||
/// \return Status code
|
||||
///
|
||||
////////////////////////////////////////////////////////////
|
||||
CSFML_API sfSocketStatus sfTcpListener_Accept(sfTcpListener* listener, sfTcpSocket** connected);
|
||||
|
||||
|
||||
#endif // SFML_TCPLISTENER_H
|
||||
@@ -36,45 +36,55 @@
|
||||
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Construct a new TCP socket
|
||||
/// \brief Create a new TCP socket
|
||||
///
|
||||
/// \return Pointer to the new socket
|
||||
/// \return A new sfTcpSocket object
|
||||
///
|
||||
////////////////////////////////////////////////////////////
|
||||
CSFML_API sfTcpSocket* sfTcpSocket_Create(void);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Destroy an existing TCP socket
|
||||
/// \brief Destroy a TCP socket
|
||||
///
|
||||
/// \param socket : Socket to destroy
|
||||
/// \param socket TCP socket to destroy
|
||||
///
|
||||
////////////////////////////////////////////////////////////
|
||||
CSFML_API void sfTcpSocket_Destroy(sfTcpSocket* socket);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Change the blocking state of a TCP socket.
|
||||
/// The default behaviour of a socket is blocking
|
||||
/// \brief Set the blocking state of a TCP listener
|
||||
///
|
||||
/// \param socket : Socket to modify
|
||||
/// \param blocking : Pass sfTrue to set the socket as blocking, or false for non-blocking
|
||||
/// In blocking mode, calls will not return until they have
|
||||
/// completed their task. For example, a call to
|
||||
/// sfTcpSocket_Receive in blocking mode won't return until
|
||||
/// new data was actually received.
|
||||
/// In non-blocking mode, calls will always return immediately,
|
||||
/// using the return code to signal whether there was data
|
||||
/// available or not.
|
||||
/// By default, all sockets are blocking.
|
||||
///
|
||||
/// \param socket TCP socket object
|
||||
/// \param blocking sfTrue to set the socket as blocking, sfFalse for non-blocking
|
||||
///
|
||||
////////////////////////////////////////////////////////////
|
||||
CSFML_API void sfTcpSocket_SetBlocking(sfTcpSocket* socket, sfBool blocking);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Get the blocking state of the socket
|
||||
/// \brief Tell whether a TCP socket is in blocking or non-blocking mode
|
||||
///
|
||||
/// \param socket : Socket to read
|
||||
/// \param socket TCP socket object
|
||||
///
|
||||
/// \Return sfTrue if the socket is blocking, sfFalse otherwise
|
||||
/// \return sfTrue if the socket is blocking, sfFalse otherwise
|
||||
///
|
||||
////////////////////////////////////////////////////////////
|
||||
CSFML_API sfBool sfTcpSocket_IsBlocking(const sfTcpSocket* socket);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Get the port to which a socket is bound locally
|
||||
/// \brief Get the port to which a TCP socket is bound locally
|
||||
///
|
||||
/// \param socket : Socket to read
|
||||
/// If the socket is not connected, this function returns 0.
|
||||
///
|
||||
/// \param socket TCP socket object
|
||||
///
|
||||
/// \return Port to which the socket is bound
|
||||
///
|
||||
@@ -82,9 +92,12 @@ CSFML_API sfBool sfTcpSocket_IsBlocking(const sfTcpSocket* socket);
|
||||
CSFML_API unsigned short sfTcpSocket_GetLocalPort(const sfTcpSocket* socket);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Get the address of the connected peer of a socket
|
||||
/// \brief Get the address of the connected peer of a TCP socket
|
||||
///
|
||||
/// \param socket : Socket to read
|
||||
/// It the socket is not connected, this function returns
|
||||
/// sfIpAddress_None().
|
||||
///
|
||||
/// \param socket TCP socket object
|
||||
///
|
||||
/// \return Address of the remote peer
|
||||
///
|
||||
@@ -92,9 +105,12 @@ CSFML_API unsigned short sfTcpSocket_GetLocalPort(const sfTcpSocket* socket);
|
||||
CSFML_API sfIpAddress sfTcpSocket_GetRemoteAddress(const sfTcpSocket* socket);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Get the port of the connected peer to which a socket is connected
|
||||
/// \brief Get the port of the connected peer to which
|
||||
/// a TCP socket is connected
|
||||
///
|
||||
/// \param socket : Socket to read
|
||||
/// If the socket is not connected, this function returns 0.
|
||||
///
|
||||
/// \param socket TCP socket object
|
||||
///
|
||||
/// \return Remote port to which the socket is connected
|
||||
///
|
||||
@@ -102,69 +118,89 @@ CSFML_API sfIpAddress sfTcpSocket_GetRemoteAddress(const sfTcpSocket* socket);
|
||||
CSFML_API unsigned short sfTcpSocket_GetRemotePort(const sfTcpSocket* socket);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Connect a TCP socket to another computer on a specified port
|
||||
/// \brief Connect a TCP socket to a remote peer
|
||||
///
|
||||
/// \param socket : Socket to connect
|
||||
/// \param host : IP Address of the host to connect to
|
||||
/// \param port : Port to use for transfers (warning : ports < 1024 are reserved)
|
||||
/// \param timeout : Maximum time to wait, in milliseconds (0 to use no timeout)
|
||||
/// In blocking mode, this function may take a while, especially
|
||||
/// if the remote peer is not reachable. The last parameter allows
|
||||
/// you to stop trying to connect after a given timeout.
|
||||
/// If the socket was previously connected, it is first disconnected.
|
||||
///
|
||||
/// \return sfTrue if operation has been successful
|
||||
/// \param socket TCP socket object
|
||||
/// \param remoteAddress Address of the remote peer
|
||||
/// \param remotePort Port of the remote peer
|
||||
/// \param timeout Maximum time to wait, in milliseconds
|
||||
///
|
||||
/// \return Status code
|
||||
///
|
||||
////////////////////////////////////////////////////////////
|
||||
CSFML_API sfSocketStatus sfTcpSocket_Connect(sfTcpSocket* socket, sfIpAddress host, unsigned short port, sfUint32 timeout);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Disconnect a connect from its remote peer
|
||||
/// \brief Disconnect a TCP socket from its remote peer
|
||||
///
|
||||
/// \param socket : Socket to disconnect
|
||||
/// This function gracefully closes the connection. If the
|
||||
/// socket is not connected, this function has no effect.
|
||||
///
|
||||
/// \param socket TCP socket object
|
||||
///
|
||||
////////////////////////////////////////////////////////////
|
||||
CSFML_API void sfTcpSocket_Disconnect(sfTcpSocket* socket);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Send an array of bytes to the host (must be connected first)
|
||||
/// \brief Send raw data to the remote peer of a TCP socket
|
||||
///
|
||||
/// \param socket : Socket to use for sending
|
||||
/// \param data : Pointer to the bytes to send
|
||||
/// \param size : Number of bytes to send
|
||||
/// This function will fail if the socket is not connected.
|
||||
///
|
||||
/// \return Socket status
|
||||
/// \param socket TCP socket object
|
||||
/// \param data Pointer to the sequence of bytes to send
|
||||
/// \param size Number of bytes to send
|
||||
///
|
||||
/// \return Status code
|
||||
///
|
||||
////////////////////////////////////////////////////////////
|
||||
CSFML_API sfSocketStatus sfTcpSocket_Send(sfTcpSocket* socket, const char* data, size_t size);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Receive an array of bytes from the host (must be connected first)
|
||||
/// \brief Receive raw data from the remote peer of a TCP socket
|
||||
///
|
||||
/// \param socket : Socket to use for receiving
|
||||
/// \param data : Pointer to a byte array to fill (make sure it is big enough)
|
||||
/// \param maxSize : Maximum number of bytes to read
|
||||
/// \param sizeReceived : Number of bytes received
|
||||
/// In blocking mode, this function will wait until some
|
||||
/// bytes are actually received.
|
||||
/// This function will fail if the socket is not connected.
|
||||
///
|
||||
/// \return Socket status
|
||||
/// \param socket TCP socket object
|
||||
/// \param data Pointer to the array to fill with the received bytes
|
||||
/// \param size Maximum number of bytes that can be received
|
||||
/// \param received This variable is filled with the actual number of bytes received
|
||||
///
|
||||
/// \return Status code
|
||||
///
|
||||
////////////////////////////////////////////////////////////
|
||||
CSFML_API sfSocketStatus sfTcpSocket_Receive(sfTcpSocket* socket, char* data, size_t maxSize, size_t* sizeReceived);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Send a packet of data to the host (must be connected first)
|
||||
/// \brief Send a formatted packet of data to the remote peer of a TCP socket
|
||||
///
|
||||
/// \param socket : Socket to use for sending
|
||||
/// \param packet : Packet to send
|
||||
/// This function will fail if the socket is not connected.
|
||||
///
|
||||
/// \return Socket status
|
||||
/// \param socket TCP socket object
|
||||
/// \param packet Packet to send
|
||||
///
|
||||
/// \return Status code
|
||||
///
|
||||
////////////////////////////////////////////////////////////
|
||||
CSFML_API sfSocketStatus sfTcpSocket_SendPacket(sfTcpSocket* socket, sfPacket* packet);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Receive a packet from the host (must be connected first)
|
||||
/// \brief Receive a formatted packet of data from the remote peer
|
||||
///
|
||||
/// \param socket : Socket to use for receiving
|
||||
/// \param packet : Packet to fill with received data
|
||||
/// In blocking mode, this function will wait until the whole packet
|
||||
/// has been received.
|
||||
/// This function will fail if the socket is not connected.
|
||||
///
|
||||
/// \return Socket status
|
||||
/// \param socket TCP socket object
|
||||
/// \param packet Packet to fill with the received data
|
||||
///
|
||||
/// \return Status code
|
||||
///
|
||||
////////////////////////////////////////////////////////////
|
||||
CSFML_API sfSocketStatus sfTcpSocket_ReceivePacket(sfTcpSocket* socket, sfPacket* packet);
|
||||
|
||||
@@ -36,45 +36,56 @@
|
||||
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Construct a new UDP socket
|
||||
/// \brief Create a new UDP socket
|
||||
///
|
||||
/// \return Pointer to the new socket
|
||||
/// \return A new sfUdpSocket object
|
||||
///
|
||||
////////////////////////////////////////////////////////////
|
||||
CSFML_API sfUdpSocket* sfUdpSocket_Create(void);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Destroy an existing UDP socket
|
||||
/// \brief Destroy a UDP socket
|
||||
///
|
||||
/// \param socket : Socket to destroy
|
||||
/// \param socket UDP socket to destroy
|
||||
///
|
||||
////////////////////////////////////////////////////////////
|
||||
CSFML_API void sfUdpSocket_Destroy(sfUdpSocket* socket);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Change the blocking state of a UDP socket.
|
||||
/// The default behaviour of a socket is blocking
|
||||
/// \brief Set the blocking state of a UDP listener
|
||||
///
|
||||
/// \param socket : Socket to modify
|
||||
/// \param blocking : Pass sfTrue to set the socket as blocking, or false for non-blocking
|
||||
/// In blocking mode, calls will not return until they have
|
||||
/// completed their task. For example, a call to
|
||||
/// sfUDPSocket_Receive in blocking mode won't return until
|
||||
/// new data was actually received.
|
||||
/// In non-blocking mode, calls will always return immediately,
|
||||
/// using the return code to signal whether there was data
|
||||
/// available or not.
|
||||
/// By default, all sockets are blocking.
|
||||
///
|
||||
/// \param socket UDP socket object
|
||||
/// \param blocking sfTrue to set the socket as blocking, sfFalse for non-blocking
|
||||
///
|
||||
////////////////////////////////////////////////////////////
|
||||
CSFML_API void sfUdpSocket_SetBlocking(sfUdpSocket* socket, sfBool blocking);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Get the blocking state of the socket
|
||||
/// \brief Tell whether a UDP socket is in blocking or non-blocking mode
|
||||
///
|
||||
/// \param socket : Socket to read
|
||||
/// \param socket UDP socket object
|
||||
///
|
||||
/// \Return sfTrue if the socket is blocking, sfFalse otherwise
|
||||
/// \return sfTrue if the socket is blocking, sfFalse otherwise
|
||||
///
|
||||
////////////////////////////////////////////////////////////
|
||||
CSFML_API sfBool sfUdpSocket_IsBlocking(const sfUdpSocket* socket);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Get the port to which a socket is bound locally
|
||||
/// \brief Get the port to which a UDP socket is bound locally
|
||||
///
|
||||
/// \param socket : Socket to read
|
||||
/// If the socket is not bound to a port, this function
|
||||
/// returns 0.
|
||||
///
|
||||
/// \param socket UDP socket object
|
||||
///
|
||||
/// \return Port to which the socket is bound
|
||||
///
|
||||
@@ -82,82 +93,116 @@ CSFML_API sfBool sfUdpSocket_IsBlocking(const sfUdpSocket* socket);
|
||||
CSFML_API unsigned short sfUdpSocket_GetLocalPort(const sfUdpSocket* socket);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Bind a socket to a specific port
|
||||
/// \brief Bind a UDP socket to a specific port
|
||||
///
|
||||
/// \param socket : Socket to bind
|
||||
/// \param port : Port to bind the socket to
|
||||
/// Binding the socket to a port is necessary for being
|
||||
/// able to receive data on that port.
|
||||
/// You can use the special value 0 to tell the
|
||||
/// system to automatically pick an available port, and then
|
||||
/// call sfUdpSocket_GetLocalPort to retrieve the chosen port.
|
||||
///
|
||||
/// \return Socket status
|
||||
/// \param socket UDP socket object
|
||||
/// \param port Port to bind the socket to
|
||||
///
|
||||
/// \return Status code
|
||||
///
|
||||
////////////////////////////////////////////////////////////
|
||||
CSFML_API sfSocketStatus sfUdpSocket_Bind(sfUdpSocket* socket, unsigned short port);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Unbind a socket from its previous port, if any
|
||||
/// \brief Unbind a UDP socket from the local port to which it is bound
|
||||
///
|
||||
/// \param socket : Socket to unbind
|
||||
/// The port that the socket was previously using is immediately
|
||||
/// available after this function is called. If the
|
||||
/// socket is not bound to a port, this function has no effect.
|
||||
///
|
||||
/// \param socket UDP socket object
|
||||
///
|
||||
////////////////////////////////////////////////////////////
|
||||
CSFML_API void sfUdpSocket_Unbind(sfUdpSocket* socket);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Send an array of bytes
|
||||
/// \brief Send raw data to a remote peer with a UDP socket
|
||||
///
|
||||
/// \param socket : Socket to use for sending
|
||||
/// \param data : Pointer to the bytes to send
|
||||
/// \param size : Number of bytes to send
|
||||
/// \param address : Address of the computer to send the packet to
|
||||
/// \param port : Port to use for communication
|
||||
/// Make sure that \a size is not greater than
|
||||
/// sfUdpSocket_MaxDatagramSize(), otherwise this function will
|
||||
/// fail and no data will be sent.
|
||||
///
|
||||
/// \return Socket status
|
||||
/// \param socket UDP socket object
|
||||
/// \param data Pointer to the sequence of bytes to send
|
||||
/// \param size Number of bytes to send
|
||||
/// \param remoteAddress Address of the receiver
|
||||
/// \param remotePort Port of the receiver to send the data to
|
||||
///
|
||||
/// \return Status code
|
||||
///
|
||||
////////////////////////////////////////////////////////////
|
||||
CSFML_API sfSocketStatus sfUdpSocket_Send(sfUdpSocket* socket, const char* data, size_t size, sfIpAddress address, unsigned short port);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Receive an array of bytes.
|
||||
/// This function is blocking, ie. it won't return before some
|
||||
/// bytes have been received
|
||||
/// \brief Receive raw data from a remote peer with a UDP socket
|
||||
///
|
||||
/// \param socket : Socket to use for receiving
|
||||
/// \param data : Pointer to a byte array to fill (make sure it is big enough)
|
||||
/// \param maxSize : Maximum number of bytes to read
|
||||
/// \param sizeReceived : Number of bytes received
|
||||
/// \param address : Address of the computer which sent the data
|
||||
/// \param port : Port on which the remote computer sent the data
|
||||
/// In blocking mode, this function will wait until some
|
||||
/// bytes are actually received.
|
||||
/// Be careful to use a buffer which is large enough for
|
||||
/// the data that you intend to receive, if it is too small
|
||||
/// then an error will be returned and *all* the data will
|
||||
/// be lost.
|
||||
///
|
||||
/// \return Socket status
|
||||
/// \param socket UDP socket object
|
||||
/// \param data Pointer to the array to fill with the received bytes
|
||||
/// \param size Maximum number of bytes that can be received
|
||||
/// \param received This variable is filled with the actual number of bytes received
|
||||
/// \param remoteAddress Address of the peer that sent the data
|
||||
/// \param remotePort Port of the peer that sent the data
|
||||
///
|
||||
/// \return Status code
|
||||
///
|
||||
////////////////////////////////////////////////////////////
|
||||
CSFML_API sfSocketStatus sfUdpSocket_Receive(sfUdpSocket* socket, char* data, size_t maxSize, size_t* sizeReceived, sfIpAddress* address, unsigned short* port);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Send a packet of data
|
||||
/// \brief Send a formatted packet of data to a remote peer with a UDP socket
|
||||
///
|
||||
/// \param socket : Socket to use for sending
|
||||
/// \param packet : Packet to send
|
||||
/// \param address : Address of the computer to send the packet to
|
||||
/// \param port : Port to use for communication
|
||||
/// Make sure that the packet size is not greater than
|
||||
/// sfUdpSocket_MaxDatagramSize(), otherwise this function will
|
||||
/// fail and no data will be sent.
|
||||
///
|
||||
/// \return Socket status
|
||||
/// \param socket UDP socket object
|
||||
/// \param packet Packet to send
|
||||
/// \param remoteAddress Address of the receiver
|
||||
/// \param remotePort Port of the receiver to send the data to
|
||||
///
|
||||
/// \return Status code
|
||||
///
|
||||
////////////////////////////////////////////////////////////
|
||||
CSFML_API sfSocketStatus sfUdpSocket_SendPacket(sfUdpSocket* socket, sfPacket* packet, sfIpAddress address, unsigned short port);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// Receive a packet.
|
||||
/// This function is blocking, ie. it won't return before a
|
||||
/// packet is received
|
||||
/// \brief Receive a formatted packet of data from a remote peer with a UDP socket
|
||||
///
|
||||
/// \param socket : Socket to use for receiving
|
||||
/// \param packet : Packet to fill with received data
|
||||
/// \param address : Address of the computer which sent the packet
|
||||
/// \param port : Port on which the remote computer sent the data
|
||||
/// In blocking mode, this function will wait until the whole packet
|
||||
/// has been received.
|
||||
/// Warning: this functon doesn't properly handle mixed data
|
||||
/// received from multiple peers.
|
||||
///
|
||||
/// \return Socket status
|
||||
/// \param packet Packet to fill with the received data
|
||||
/// \param remoteAddress Address of the peer that sent the data
|
||||
/// \param remotePort Port of the peer that sent the data
|
||||
///
|
||||
/// \return Status code
|
||||
///
|
||||
////////////////////////////////////////////////////////////
|
||||
CSFML_API sfSocketStatus sfUdpSocket_ReceivePacket(sfUdpSocket* socket, sfPacket* packet, sfIpAddress* address, unsigned short* port);
|
||||
|
||||
////////////////////////////////////////////////////////////
|
||||
/// \brief Return the maximum number of bytes that can be
|
||||
/// sent in a single UDP datagram
|
||||
///
|
||||
/// \return The maximum size of a UDP datagram (message)
|
||||
///
|
||||
////////////////////////////////////////////////////////////
|
||||
CSFML_API unsigned int sfUdpSocket_MaxDatagramSize();
|
||||
|
||||
|
||||
#endif // SFML_UDPSOCKET_H
|
||||
Reference in new issue
Block a user