The qDecoder Project: C/C++ Library

- Main Page
- Data Structures
- Files

- File List
- Globals

# 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.
ssize_t | qSocketSendfile (int sockfd, const char *filepath, off_t offset, size_t nbytes)
| Send file to socket.
ssize_t | qSocketSaveIntoFile (int filefd, int sockfd, size_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.

ssize_t qSocketSendfile | ( | int | sockfd,
|  | const char * | filepath,
|  | off_t | offset,
|  | size_t | nbytes |
| ) |  |  |

Send file to socket.

Parameters:

  | sockfd | socket descriptor
  | filepath | variable argument lists
  | offset | file start 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

ssize_t qSocketSaveIntoFile | ( | int | filefd,
|  | int | sockfd,
|  | size_t | nbytes,
|  | int | timeoutms |
| ) |  |  |

Store socket data into file directly.

Parameters:

  | filefd | save file descriptor
  | sockfd | socket descriptor
  | 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(filefd, 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]