FreeTDS API: Network functions

FreeTDS API

Classes | Functions
Network functions
LibTDS API

Functions for reading or writing from network. More...

Collaboration diagram for Network functions:

## Classes
struct | retry_addr

## Functions
static size_t | read_and_convert (TDSSOCKET *tds, TDSICONV *char_conv, size_t *wire_size, char *outbuf, size_t outbytesleft)
| For UTF-8 and similar, tds_iconv() may encounter a partial sequence when the chunk boundary is not aligned with the character boundary. More...
int | tds7_get_instance_port (struct addrinfo *addr, const char *instance)
| Get port of given instance. More...
int | tds7_get_instance_ports (FILE *output, struct addrinfo *addr)
| Get port of all instances. More...
const char * | tds_addrinfo2str (struct addrinfo *addr, char *name, int namemax)
static void | tds_addrinfo_set_port (struct addrinfo *addr, unsigned int port)
void | tds_close_socket (TDSSOCKET *tds)
| Close current socket. More...
| TDS_COMPILE_CHECK (additional, TDS_ADDITIONAL_SPACE !=0)
void | tds_connection_close (TDSCONNECTION *conn)
int | tds_connection_read (TDSSOCKET *tds, unsigned char *buf, int buflen)
static int | tds_connection_signaled (TDSCONNECTION *conn)
int | tds_connection_write (TDSSOCKET *tds, const unsigned char *buf, int buflen, int final)
DSTR * | tds_dstr_get (TDSSOCKET *tds, DSTR *s, size_t len)
| Reads a string from wire and put in a DSTR. More...
TDSRET | tds_flush_packet (TDSSOCKET *tds)
| Flush packet to server. More...
void | tds_freeze (TDSSOCKET *tds, TDSFREEZE *freeze, unsigned size_len)
| Stop writing to server and cache every packet not sending them to server. More...
TDSRET | tds_freeze_abort (TDSFREEZE *freeze)
| Discard all data written after the freeze. More...
TDSRET | tds_freeze_close (TDSFREEZE *freeze)
| Stop keeping data for this specific freeze. More...
TDSRET | tds_freeze_close_len (TDSFREEZE *freeze, int32_t size)
| Stop keeping data for this specific freeze. More...
static void | tds_freeze_update_size (const TDSFREEZE *freeze, int32_t size)
size_t | tds_freeze_written (TDSFREEZE *freeze)
| Compute how many bytes has been written from freeze. More...
unsigned char | tds_get_byte (TDSSOCKET *tds)
| Return a single byte from the input buffer. More...
TDSRET | tds_get_char_data (TDSSOCKET *tds, char *row_buffer, size_t wire_size, TDSCOLUMN *curcol)
| Fetch character data the wire. More...
bool | tds_get_n (TDSSOCKET *tds, void *dest, size_t need)
| Get N bytes from the buffer and return them in the already allocated space given to us. More...
static TDSPACKET * | tds_get_packet (TDSCONNECTION *conn, unsigned len)
static int | tds_get_socket_error (TDS_SYS_SOCKET sock)
| Returns error stored in the socket.
size_t | tds_get_string (TDSSOCKET *tds, size_t string_len, char *dest, size_t dest_size)
| Fetch a string from the wire. More...
TDS_UINT | tds_get_uint (TDSSOCKET *tds)
| Get an int32 from the server. More...
TDS_UINT8 | tds_get_uint8 (TDSSOCKET *tds)
| Get an uint64 from the server. More...
TDS_USMALLINT | tds_get_usmallint (TDSSOCKET *tds)
| Get an int16 from the server.
int | tds_goodread (TDSSOCKET *tds, unsigned char *buf, int buflen)
| Loops until we have received some characters return -1 on failure.
int | tds_goodwrite (TDSSOCKET *tds, const unsigned char *buffer, size_t buflen)
int | tds_init_write_buf (TDSSOCKET *tds)
TDSERRNO | tds_open_socket (TDSSOCKET *tds, struct addrinfo *addr, unsigned int port, int timeout, int *p_oserr)
static void | tds_packet_cache_add (TDSCONNECTION *conn, TDSPACKET *packet)
unsigned char | tds_peek (TDSSOCKET *tds)
| Reads a byte from the TDS stream without removing it. More...
int | tds_put_buf (TDSSOCKET *tds, const unsigned char *buf, int dsize, int ssize)
int | tds_put_byte (TDSSOCKET *tds, unsigned char c)
int | tds_put_cancel (TDSSOCKET *tds)
int | tds_put_int (TDSSOCKET *tds, TDS_INT i)
int | tds_put_int8 (TDSSOCKET *tds, TDS_INT8 i)
int | tds_put_n (TDSSOCKET *tds, const void *buf, size_t n)
int | tds_put_smallint (TDSSOCKET *tds, TDS_SMALLINT si)
int | tds_put_string (TDSSOCKET *tds, const char *s, int len)
| Output a string to wire automatic translate string to unicode if needed. More...
int | tds_read_packet (TDSSOCKET *tds)
| Read in one 'packet' from the server. More...
int | tds_select (TDSSOCKET *tds, unsigned tds_sel, int timeout_seconds)
| Select on a socket until it's available or the timeout expires. More...
static TDSERRNO | tds_setup_socket (TDS_SYS_SOCKET *p_sock, struct addrinfo *addr, unsigned int port, int *p_oserr)
| Setup the socket and attempt a connection. More...
void | tds_socket_flush (TDS_SYS_SOCKET sock)
static int | tds_socket_read (TDSCONNECTION *conn, TDSSOCKET *tds, unsigned char *buf, int buflen)
| Read from an OS socket @TODO remove tds, save error somewhere, report error in another way. More...
int | tds_socket_set_nonblocking (TDS_SYS_SOCKET sock)
| Set socket to non-blocking. More...
int | tds_socket_set_nosigpipe (TDS_SYS_SOCKET sock, int on)
| Set socket to not throw SIGPIPE. More...
static int | tds_socket_write (TDSCONNECTION *conn, TDSSOCKET *tds, const unsigned char *buf, int buflen)
| Write to an OS socket. More...
void | tds_unget_byte (TDSSOCKET *tds)
| Unget will always work as long as you don't call it twice in a row. More...
void | tds_wakeup_close (TDSPOLLWAKEUP *wakeup)
int | tds_wakeup_init (TDSPOLLWAKEUP *wakeup)
void | tds_wakeup_send (TDSPOLLWAKEUP *wakeup, char cancel)
TDSRET | tds_write_packet (TDSSOCKET *tds, unsigned char final)

## Detailed Description

Functions for reading or writing from network.

## Function Documentation

## ◆ read_and_convert()

static size_t read_and_convert | ( | TDSSOCKET * | tds,
|  | TDSICONV * | char_conv,
|  | size_t * | wire_size,
|  | char * | outbuf,
|  | size_t | outbytesleft
| ) |  |
| static

For UTF-8 and similar, tds_iconv() may encounter a partial sequence when the chunk boundary is not aligned with the character boundary.

In that event, it will return an error, and some number of bytes (less than a character) will remain in the tail end of temp[]. They are moved to the beginning, ptemp is adjusted to point just behind them, and the next chunk is read.

Parameters

  | tds | A pointer to the TDSSOCKET structure managing a client/server operation.
  | char_conv | conversion structure
  [out] | wire_size | size readed from wire
  | outbuf | buffer to write to
  | outbytesleft | buffer length

Returns
  bytes readed

Here is the call graph for this function:

## ◆ tds7_get_instance_port()

int tds7_get_instance_port | ( | struct addrinfo * | addr,
|  | const char * | instance
| ) |  |

Get port of given instance.

Returns
  port number or 0 if error

## ◆ tds7_get_instance_ports()

int tds7_get_instance_ports | ( | FILE * | output,
|  | struct addrinfo * | addr
| ) |  |

Get port of all instances.

Returns
  default port number or 0 if error

Remarks
  experimental, cf. MC-SQLR.pdf.

## ◆ tds_close_socket()

void tds_close_socket | ( | TDSSOCKET * | tds | ) |

Close current socket.

For last socket close entire connection. For MARS send FIN request. This attempts a graceful disconnection, for ungraceful call tds_connection_close.

## ◆ tds_dstr_get()

DSTR* tds_dstr_get | ( | TDSSOCKET * | tds,
|  | DSTR * | s,
|  | size_t | len
| ) |  |

Reads a string from wire and put in a DSTR.

On error we read the bytes from the wire anyway.

Parameters

  | tds | A pointer to the TDSSOCKET structure managing a client/server operation.
  [out] | s | output string
  [in] | len | string length (in characters)

Returns
  string or NULL on error

## ◆ tds_flush_packet()

TDSRET tds_flush_packet | ( | TDSSOCKET * | tds | ) |

Flush packet to server.

Returns
  TDS_FAIL or TDS_SUCCESS

Here is the caller graph for this function:

## ◆ tds_freeze()

void tds_freeze | ( | TDSSOCKET * | tds,
|  | TDSFREEZE * | freeze,
|  | unsigned | size_len
| ) |  |

Stop writing to server and cache every packet not sending them to server.

This is used to write data without worrying to compute length before. If size_len is provided the number of bytes written between tds_freeze and tds_freeze_close will be written as a number of size size_len. This call should be followed by a tds_freeze_close, tds_freeze_close_len or a tds_freeze_abort. Failing to match tds_freeze with a close would possibly result in a disconnection from the server.

Parameters

  [out] | freeze | structure to initialize
  | size_len | length of the size to automatically write on close (0, 1, 2, or 4)

Here is the caller graph for this function:

## ◆ tds_freeze_abort()

TDSRET tds_freeze_abort | ( | TDSFREEZE * | freeze | ) |

Discard all data written after the freeze.

After this call freeze should not be used.

Parameters

  [in] | freeze | structure to work on

## ◆ tds_freeze_close()

TDSRET tds_freeze_close | ( | TDSFREEZE * | freeze | ) |

Stop keeping data for this specific freeze.

If size_len was used for tds_freeze this function write the written bytes at position when tds_freeze was called. After this call freeze should not be used.

Parameters

  [in] | freeze | structure to work on

Here is the call graph for this function:

## ◆ tds_freeze_close_len()

TDSRET tds_freeze_close_len | ( | TDSFREEZE * | freeze,
|  | int32_t | size
| ) |  |

Stop keeping data for this specific freeze.

Similar to tds_freeze_close but specify the size to be written instead of letting tds_freeze_close compute it. After this call freeze should not be used.

Parameters

  [in] | freeze | structure to work on
  [in] | size | size to write

Here is the caller graph for this function:

## ◆ tds_freeze_written()

size_t tds_freeze_written | ( | TDSFREEZE * | freeze | ) |

Compute how many bytes has been written from freeze.

Returns
  bytes written since tds_freeze call

Here is the caller graph for this function:

## ◆ tds_get_byte()

unsigned char tds_get_byte | ( | TDSSOCKET * | tds | ) |

Return a single byte from the input buffer.

Parameters

  tds | A pointer to the TDSSOCKET structure managing a client/server operation.

Here is the call graph for this function:
Here is the caller graph for this function:

## ◆ tds_get_char_data()

TDSRET tds_get_char_data | ( | TDSSOCKET * | tds,
|  | char * | row_buffer,
|  | size_t | wire_size,
|  | TDSCOLUMN * | curcol
| ) |  |

Fetch character data the wire.

Output is NOT null terminated. If char_conv is not NULL, convert data accordingly.

Parameters

  tds | state information for the socket and the TDS protocol
  row_buffer | destination buffer in current_row. Can't be NULL
  wire_size | size to read from wire (in bytes)
  curcol | column information

Returns
  TDS_SUCCESS or TDS_FAIL (probably memory error on text data)

## ◆ tds_get_n()

bool tds_get_n | ( | TDSSOCKET * | tds,
|  | void * | dest,
|  | size_t | need
| ) |  |

Get N bytes from the buffer and return them in the already allocated space
given to us.

We ASSUME that the person calling this function has done the
bounds checking for us since they know how many bytes they want here. dest of NULL means we just want to eat the bytes. (tethe.nosp@m.row@.nosp@m.nol.o.nosp@m.rg)

Here is the call graph for this function:
Here is the caller graph for this function:

## ◆ tds_get_string()

size_t tds_get_string | ( | TDSSOCKET * | tds,
|  | size_t | string_len,
|  | char * | dest,
|  | size_t | dest_size
| ) |  |

Fetch a string from the wire.

Output string is NOT null terminated. If TDS version is 7 or 8 read unicode string and convert it. This function should be use to read server default encoding strings like columns name, table names, etc, not for data (use tds_get_char_data instead)

Returns
  bytes written to dest

Parameters

  tds | connection information
  string_len | length of string to read from wire (in server characters, bytes for tds4-tds5, ucs2 for tds7+)
  dest | destination buffer, if NULL string is read and discarded
  dest_size | destination buffer size, in bytes

## ◆ tds_get_uint()

TDS_UINT tds_get_uint | ( | TDSSOCKET * | tds | ) |

Get an int32 from the server.

Parameters

  tds | A pointer to the TDSSOCKET structure managing a client/server operation.

Here is the call graph for this function:
Here is the caller graph for this function:

## ◆ tds_get_uint8()

TDS_UINT8 tds_get_uint8 | ( | TDSSOCKET * | tds | ) |

Get an uint64 from the server.

Parameters

  tds | A pointer to the TDSSOCKET structure managing a client/server operation.

Here is the call graph for this function:

## ◆ tds_goodwrite()

int tds_goodwrite | ( | TDSSOCKET * | tds,
|  | const unsigned char * | buffer,
|  | size_t | buflen
| ) |  |

Parameters

  tds | the famous socket
  buffer | data to send
  buflen | bytes in buffer
  last | 1 if this is the last packet, else 0

Returns
  length written (>0), <0 on failure

## ◆ tds_peek()

unsigned char tds_peek | ( | TDSSOCKET * | tds | ) |

Reads a byte from the TDS stream without removing it.

Parameters

  tds | A pointer to the TDSSOCKET structure managing a client/server operation.

Here is the call graph for this function:

## ◆ tds_put_string()

int tds_put_string | ( | TDSSOCKET * | tds,
|  | const char * | s,
|  | int | len
| ) |  |

Output a string to wire automatic translate string to unicode if needed.

Returns
  bytes written to wire

Parameters

  tds | state information for the socket and the TDS protocol
  s | string to write
  len | length of string in characters, or -1 for null terminated

Here is the caller graph for this function:

## ◆ tds_read_packet()

int tds_read_packet | ( | TDSSOCKET * | tds | ) |

Read in one 'packet' from the server.

This is a wrapped outer packet of the protocol (they bundle result packets into chunks and wrap them at what appears to be 512 bytes regardless of how that breaks internal packet up. (tetherow@nol.org)

Returns
  bytes read or -1 on failure

Here is the caller graph for this function:

## ◆ tds_select()

int tds_select | ( | TDSSOCKET * | tds,
|  | unsigned | tds_sel,
|  | int | timeout_seconds
| ) |  |

Select on a socket until it's available or the timeout expires.

Meanwhile, call the interrupt function.

Returns
  >0 ready descriptors 0 timeout <0 error (cf. errno). Caller should close socket and return failure. This function does not call tdserror or close the socket because it can't know the context in which it's being called.

## ◆ tds_setup_socket()

static TDSERRNO tds_setup_socket | ( | TDS_SYS_SOCKET * | p_sock,
|  | struct addrinfo * | addr,
|  | unsigned int | port,
|  | int * | p_oserr
| ) |  |
| static

Setup the socket and attempt a connection.

Function allocate the socket in *p_sock and try to start a connection.

Parameters

  p_sock | where returned socket is stored. Socket is stored even on error. Can be INVALID_SOCKET.
  addr | address to use for attempting the connection
  port | port to connect to
  p_oserr | where system error is returned

Returns
  TDSEOK is success, TDSEINPROGRESS if connection attempt is started or any other error.

## ◆ tds_socket_read()

static int tds_socket_read | ( | TDSCONNECTION * | conn,
|  | TDSSOCKET * | tds,
|  | unsigned char * | buf,
|  | int | buflen
| ) |  |
| static

Read from an OS socket @TODO remove tds, save error somewhere, report error in another way.

Returns
  0 if blocking, <0 error >0 bytes read

## ◆ tds_socket_set_nonblocking()

int tds_socket_set_nonblocking | ( | TDS_SYS_SOCKET | sock | ) |

Set socket to non-blocking.

Parameters

  sock | socket to set

Returns
  0 on success or error code

## ◆ tds_socket_set_nosigpipe()

int tds_socket_set_nosigpipe | ( | TDS_SYS_SOCKET | sock,
|  | int | on
| ) |  |

Set socket to not throw SIGPIPE.

Not many systems support this feature (in this case ENOTSUP can be returned).

Parameters

  sock | socket to set
  on | flag if enable or disable

Returns
  0 on success or error code

## ◆ tds_socket_write()

static int tds_socket_write | ( | TDSCONNECTION * | conn,
|  | TDSSOCKET * | tds,
|  | const unsigned char * | buf,
|  | int | buflen
| ) |  |
| static

Write to an OS socket.

Returns
  0 if blocking, <0 error >0 bytes readed

## ◆ tds_unget_byte()

void tds_unget_byte | ( | TDSSOCKET * | tds | ) |

Unget will always work as long as you don't call it twice in a row.

It it may work if you call it multiple times as long as you don't backup over the beginning of network packet boundary which can occur anywhere in the token stream.

Parameters

  tds | A pointer to the TDSSOCKET structure managing a client/server operation.