NAME

       odbx_escape - Prepare strings for inclusion in statements

SYNOPSIS

       #include <opendbx/api.h>

       int odbx_escape (odbx_t* handle, const char* from, unsigned long fromlen, char* to,
                       unsigned long* tolen);

DESCRIPTION

       odbx_escape() 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
       odbx_escape() 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 from, they are written into the memory provided via to and  the
       value/result parameter tolen is updated to the new length of to in the end.

       The  first  parameter  handle is the connection object created and returned by odbx_init()
       which becomes invalid as soon as it was supplied to odbx_finish().

       from 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 fromlen. 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 fromlen must be the length in bytes of the string which from 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
       fromlen.

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

       tolen  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 to and  if  escaping
       the string in from suceeded, odbx_escape() will store the new length of the escaped string
       in this variable.

RETURN VALUE

       odbx_escape() returns ODBX_ERR_SUCCESS, 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 odbx_error()  and  odbx_error_type()  to  get
       further details.

ERRORS

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

       -ODBX_ERR_PARAM
              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

       -ODBX_ERR_SIZE
              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 ODBX_ERR_TOOLONG but the value is still the
              same)

SEE ALSO

       odbx_error(), odbx_error_type(), odbx_query()

                                         21 October 2016                           odbx_escape(3)