#ifndef _apl_tokenizers_cgi_getdataapi_h_
#define _apl_tokenizers_cgi_getdataapi_h_
/*----------------------------------------------------------------------------
** SUMMARY: Parser for CGI Encoded URLs generated by a Form's GET Action
**
** DESCRIPTION:
**  This file provides a minimal, destructive parser for decoding an
**  encoded URL that is the result of a HTML form's GET action.  The parser
**  is destructive in that it tokenizes/decodes the raw string "in place"
**  
**  NOTE: There is no checking for malformed encoded URLs - so buyer
**        beware!!!
**  
**  
** CONFIGURATION 
** -------------
**  COMPILE:     none.
**
**  APPLICATION: none.
**
**  PLATFORM:    none.
**
**
**  NOTES:
**  1. For efficency/optimization some methods are 'inlined'.  The inlining
**     is done by using the preprocessor/macros.  The application should
**     treat all methods as function calls and not rely on the fact they may
**     be currently defined as macros.
----------------------------------------------------------------------------*/

#include "apl/types/types.h"                        /* For: basic types */
#include "apl/parsing/tokenizers/cgi/getdata.h"     /* For: implementation */


#ifdef __cplusplus
extern "C" {
#endif


/*-------------- PUBLIC/PUBLISHED API --------------------------------------*/
/** This method parses the raw encoded URL string into individual name/value
    pairs and it decodes any special characters.  The number of fields found
    and/or parsed is returned.  
    NOTES:
        o The rawEncodedUrl string must be a null terminated C string.
        o rawEncodedUrl is assumed to point to the first character after
          the '?' in the encoded URL string
        o It is assumed that all named fields found in the string
          have a value (i.e. every named field has a '=')
        o It is assumed that the name portion of the name/value pairs
          does *not* have any special characters (i.e. does not have any 
          %xx encoding).
        o Assumes that all ascii-hex digits used on the '%xx' encoding
          are upper case (i.e. 'A' not 'a').

    Prototype:
        AplByte Apl_cgiTokenizeGetAction( char* rawEncodedUrl )
 */            
#define Apl_cgiTokenizeGetAction            _Apl_cgiTokenizeGetAction

/** This method is called once the raw URL string has been tokenized.
    It returns a pointer to the value for the specified field name.  
    If the field name does not exists, then 0 is returned.
    NOTES:
        o Field names are case sensitive.
        o Field names can not be an empty string
        o The rawEncodedUrl parameter must the same as the rawEncodedUrl
          parameter used when Apl_cgiTokenizeGetAction() was called.
        o The numFields parameter must be the value return by 
          Apl_cgiTokenizeGetAction()

    Prototype:
        const char* Apl_cgiGetFieldValue( const char* rawEncodedUrl, AplByte numFields, const char* fieldName )
 */
#define Apl_cgiGetFieldValue                _Apl_cgiGetFieldValue

/** This method is called once the raw ULR string has been tokenized.
    It returns a pointer to the Nth name/value pair.  The format of
    of the return string is "<name>=<value>"
    associated name.
    NOTES:
        o The argument fieldNumToGet, is a 0 based index that MUST always
          less than the num-fields value returned by Apl_cgiTokenizeGetAction()
    
    Prototype:
        const char* Apl_cgiGetFieldPair( const char* rawEncodedUrl, AplByte fieldNumToGet );
 */
#define Apl_cgiGetFieldPair                 _Apl_cgiGetFieldPair


#ifdef __cplusplus
}
#endif
/*--------------------------------------------------------------------------*/
#endif  /* end _apl_tokenizers_cgi_getdataapi_h_ */