---

qSocket.c File Reference

Socket Handling API. More…

Defines
#define	MAX_SENDFILE_CHUNK_SIZE   (64 * 1024)
#define	MAX_SAVEINTOFILE_CHUNK_SIZE   (64 * 1024)
Functions
int	qSocketOpen (const char *hostname, int port)
	Create a TCP socket for the remote host and port.
bool	qSocketClose (int sockfd)
	Close socket.
int	qSocketWaitReadable (int sockfd, int timeoutms)
	Wait until the socket has some readable data.
int	qSocketWaitWritable (int sockfd, int timeoutms)
	Wait until the socket is writable.
ssize_t	qSocketRead (void *binary, int sockfd, size_t nbytes, int timeoutms)
	Read data from socket.
ssize_t	qSocketGets (char *str, int sockfd, size_t nbytes, int timeoutms)
	Read line from the stream.
ssize_t	qSocketWrite (int sockfd, const void *binary, size_t nbytes)
	Send string or binary data to socket.
ssize_t	qSocketPuts (int sockfd, const char *str)
	Send string with newline characters(CRLF) to socket.
ssize_t	qSocketPrintf (int sockfd, const char *format,…)
	Send formatted string to socket.
off_t	qSocketSendfile (int sockfd, int fd, off_t offset, off_t nbytes)
	Send file to socket.
off_t	qSocketSaveIntoFile (int fd, int sockfd, off_t nbytes, int timeoutms)
	Store socket data into file directly.
ssize_t	qSocketSaveIntoMemory (char *mem, int sockfd, size_t nbytes, int timeoutms)
	Store socket data into memory directly.

---

Detailed Description

Socket Handling API.

---

Function Documentation

int qSocketOpen	(	const char *	hostname,
		int	port
	)

Create a TCP socket for the remote host and port.

Parameters:

	hostname	remote hostname
	port	remote port

Returns:

the new socket descriptor, or -1 in case of invalid hostname, -2 in case of socket creation failure, -3 in case of connection failure.

Since:

8.1R

Note:

bool qSocketClose

(

int

sockfd

)

Close socket.

Parameters:

sockfd

socket descriptor

Returns:

true on success, or false if an error occurred.

Since:

8.1R

Note:

int qSocketWaitReadable	(	int	sockfd,
		int	timeoutms
	)

Wait until the socket has some readable data.

Parameters:

	sockfd	socket descriptor
	timeoutms	wait timeout milliseconds. if set to negative value, wait indefinitely.

Returns:

1 on readable, or 0 on timeout, or -1 if an error(ex:socket closed) occurred.

Since:

8.1R

Note:

does not need to set the socket as non-block mode.

int qSocketWaitWritable	(	int	sockfd,
		int	timeoutms
	)

Wait until the socket is writable.

Parameters:

	sockfd	socket descriptor
	timeoutms	wait timeout mili-seconds. if set to negative value, wait indefinitely.

Returns:

1 on writable, or 0 on timeout, or -1 if an error(ex:socket closed) occurred.

Since:

8.1R

Note:

does not need to set the socket as non-block mode.

ssize_t qSocketRead	(	void *	binary,
		int	sockfd,
		size_t	nbytes,
		int	timeoutms
	)

Read data from socket.

Parameters:

	binary	data buffer pointer
	sockfd	socket descriptor
	nbytes	read size
	timeoutms	wait timeout milliseconds

Returns:

the length of data readed on success, or 0 on timeout, or -1 if an error(ex:socket closed) occurred.

Since:

8.1R

Note:

does not need to set the socket as non-block mode.

ssize_t qSocketGets	(	char *	str,
		int	sockfd,
		size_t	nbytes,
		int	timeoutms
	)

Read line from the stream.

New-line characters(CR, LF ) will not be stored into buffer.

Parameters:

	str	data buffer pointer
	sockfd	socket descriptor
	nbytes	read size
	timeoutms	wait timeout milliseconds

Returns:

the length of data readed on success, or 0 on timeout, or -1 if an error(ex:socket closed) occurred.

Since:

8.1R

Note:

be sure the return length is not the length of stored data. it means how many bytes are readed from the socket. so the new-line characters will be counted, but not be stored.

ssize_t qSocketWrite	(	int	sockfd,
		const void *	binary,
		size_t	nbytes
	)

Send string or binary data to socket.

Parameters:

	sockfd	socket descriptor
	binary	data pointer
	nbytes	sending size

Returns:

the number of bytes sent on success, or -1 if an error(ex:socket closed) occurred.

Since:

8.1R

ssize_t qSocketPuts	(	int	sockfd,
		const char *	str
	)

Send string with newline characters(CRLF) to socket.

Parameters:

	sockfd	socket descriptor
	str	string pointer

Returns:

the number of bytes sent on success, or -1 if an error(ex:socket closed) occurred.

Since:

8.1R

ssize_t qSocketPrintf	(	int	sockfd,
		const char *	format,
			…
	)

Send formatted string to socket.

Parameters:

	sockfd	socket descriptor
	format	variable argument lists

Returns:

the number of bytes sent on success, or -1 if an error(ex:socket closed) occurred.

Since:

8.1R

Note:

the final length of formatted string must be less than 1024 If you need to send more huge string, use qSocketPuts instead.

off_t qSocketSendfile	(	int	sockfd,
		int	fd,
		off_t	offset,
		off_t	nbytes
	)

Send file to socket.

Parameters:

	sockfd	socket descriptor (out)
	fd	file descriptor (in)
	offset	file offset to send
	nbytes	total bytes to send. 0 means send data until EOF.

Returns:

the number of bytes sent on success, or -1 if an error(ex:socket closed) occurred.

Since:

8.1R

off_t qSocketSaveIntoFile	(	int	fd,
		int	sockfd,
		off_t	nbytes,
		int	timeoutms
	)

Store socket data into file directly.

Parameters:

	fd	file descriptor (out)
	sockfd	socket descriptor (in)
	nbytes	length of bytes to read from socket
	timeoutms	wait timeout milliseconds

Returns:

the number of bytes wrote on success, -1 if an error(ex:socket closed, file open failed) occurred.

Since:

8.1R

Note:

timeoutms is not the total retrieving time. only affected if no data reached to socket until timeoutms reached. if some data are received, it will wait until timeoutms reached again.

   qSocketSaveIntoFile(fd, sockfd, 100, 5000);

ssize_t qSocketSaveIntoMemory	(	char *	mem,
		int	sockfd,
		size_t	nbytes,
		int	timeoutms
	)

Store socket data into memory directly.

Parameters:

	mem	memory buffer pointer
	sockfd	socket descriptor
	nbytes	length of bytes to read from socket
	timeoutms	wait timeout milliseconds

Returns:

the number of bytes sent on success, or -1 if an error(ex:socket closed) occurred.

Since:

8.1R

Note:

timeoutms is not the total retrieving time. only affected if no data reached to socket until timeoutms reached. if some data are received, it will wait until timeoutms reached again.

---

[Home] [About] [Examples] [Changes] [Download] [SVN Repository] [Install] [Reference]