The qDecoder Project

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]