odbx_escape(3)

NAME

odbx_escape - Prepare strings for inclusion in statements

SYNOPSIS

FC#include <opendbx/api.h>F[0]

FCint odbx_escapeF[0] FC(odbx_t* handle, const char* from, unsigned long fromlen, char* to, unsigned long* tolen);F[0]

DESCRIPTION

FCodbx_escapeF[0]() neutralizes potentially dangerous characters of the string so it can be used as part of a statement. For security reasons every user input has to be passed to FCodbx_escapeF[0]() to avoid SQL injection attacks which can have fatal consequences! It's also a good idea to escape strings returned from database fields again if you want to use them in a query because they don't stay escaped once they are returned as part of a record.

Most backends require the buffer to be more than twice as long as the input string. To be precise, the output buffer must be 2 * size of input + 1 bytes long. After successfully escaping the characters in FCfromF[0], they are written into the memory provided via FCtoF[0] and the value/result parameter FCtolenF[0] is updated to the new length of FCtoF[0] in the end.

The first parameter FChandleF[0] is the connection object created and returned by FCodbx_initF[0]() which becomes invalid as soon as it was supplied to FCodbx_finishF[0]().

FCfromF[0] has to point to a character string containing the string which should be used as part of a statement. It doesn't have to be zero-terminated because the length of it is also given via FCfromlenF[0]. The backends may support variable width character sets like UTF-8 but this function doesn't support the wide char type (wchar_t) where each character has a fixed size of two or four bytes.

The value of the parameter FCfromlenF[0] must be the length in bytes of the string which FCfromF[0] is pointing to. This is also true for variable width character sets like UTF-8 but the wide char type (wchar_t) is not supported. The terminating \0 character shouldn't be part of FCfromlenF[0].

The calling function provides a buffer for storing the escaped string via FCtoF[0]. In general, the length of the buffer should be more than twice as long as the string passed via FCfromF[0] to be able to store the escaped string even if every character has to be escaped.

FCtolenF[0] is a value-result parameter which points to an integer variable in the calling function. It must contain the original length of the buffer given via FCtoF[0] and if escaping the string in FCfromF[0] suceeded, FCodbx_escapeF[0]() will store the new length of the escaped string in this variable.

RETURN VALUE

FCodbx_escapeF[0]() returns FCODBX_ERR_SUCCESSF[0], or an error code whose value is less than zero if one of the operations couldn't be completed successfully. Possible error codes are listed in the error section and they can be feed to FCodbx_errorF[0]() and FCodbx_error_typeF[0]() to get further details.

ERRORS

-FCODBX_ERR_BACKENDF[0]: The native database library returned an error because it wasn't able to escape the given string to be suitable for a statement

-FCODBX_ERR_PARAMF[0]: One of the supplied parameters is invalid or is NULL and this isn't allowed in the used backend module or in the native database client library

-FCODBX_ERR_SIZEF[0]: The length of the escaped string exceeds or is likely to exeed the available buffer (before 1.1.4 the name of the label was FCODBX_ERR_TOOLONGF[0] but the value is still the same)