Jump to main content

##

# TCPIP_HTTP_PostReadPair Macro

## C

    #define TCPIP_HTTP_PostReadPair(connHandle, cData, wLen) TCPIP_HTTP_PostValueRead(connHandle, cData, wLen)

## Description

Reads a name and value pair from a URL encoded string in the TCP buffer. This function is meant to be called from a TCPIP_HTTP_PostExecute callback to facilitate easier parsing of incoming data. This function also precents buffer overflows by forcing the programmer to indicate how many bytes are expected. At least 2 extra bytes are needed in cData over the maximum length of data expected to be read.

This function will read until the next '&' character, which indicates the end of a value parameter. It assumes that the front of the buffer is the beginning of the name parameter to be read. This function properly updates the connection byteCount (see TCPIP_HTTP_CurrentConnectionByteCountGet()) by decrementing it by the number of bytes read. It also removes the delimiting '&' from the buffer. Once complete, two strings will exist in the cData buffer. The first is the parameter name that was read, while the second is the associated value.

## Preconditions

The front of the TCP buffer is the beginning of a name parameter, and the rest of the TCP buffer contains a URL-encoded string with a name parameter terminated by a '=' character and a value parameter terminated by a '&'.

## Parameters

Parameters | Description
--- | ---
connHandle | HTTP connection handle.
cData | Where to store the name and value strings once they are read.
wLen | How many bytes can be written to cData.

## Returns

- HTTP_READ_OK - Name and value were successfully read.
- HTTP_READ_TRUNCTATED - Entire name and value could not fit in the buffer, so input was truncated and data has been lost.
- HTTP_READ_INCOMPLETE - Entire name and value was not yet in the buffer, so call this function again later to retrieve.

## Remarks

This function is aliased to TCPIP_HTTP_PostValueRead, since they effectively perform the same task. The name is provided only for completeness.