visit Kofax web site

Parameter encoding

Parameter encoding

Some parameters must be encoded to allow a transmission complient with html rules.

Standard parameters

The plugins implement several functionality. The plugins are called with a set of parameters that will pass size and type of the visible portion of the plugin, the function and some function specific parameters.

The standard input parameters include:

Standard return values

The plugins return a final plugin result and optional return parameters which depend on the functionality.

The result is passed in a parameter rc. It is passed as an integer, coded as a hexadecimal number.

The most common values are:

For a full list of return codes please see file //Gimli/spdfs/dev/rel/spjcshared//SPJcShared/SPConstants.h or SignWare documentation for details.

Integer parameter

Integer parameters are passed in decimal notation, or hexadecimal notation if prefixed with '0x' or postfixed with 'h'.

Example: 

"0x32" will be read as a hexadecimal number which converts
to "50" decimal (3 * 16 + 2)

"32h" will be read as a hexadecimal number which converts
to "50" decimal (3 * 16 + 2)

"50" will be read as a decimal number

Integer return

Integer return values are passed in hexadecimal notation.

Example: 

// A decimal value of 50 will be returned as "32", (3 * 16 + 2 = 50)
/*
 Encode an integer value
 param pszTag [i] the tag name
 param iData [i] the entry data to be encoded
 param pszResult [io] buffer that will be filled with the encoded string.
       pszResult must have a length of at least strlen(pszTag) + 1 + 8 (+ 1) bytes
 */
void encodeInteger(const char *pszTag, const int iData, char *pszResult)
{
    sprintf(pszResult, "%s=%X", pszTag, iData);
}

Character return

Character data is returned as a single character string.
Example: 
/*
 Encode a character value
 param pszTag [i] the tag name
 param chData [i] the entry data to be encoded
 param pszResult [io] buffer that will be filled with the encoded string.
       pszResult must have a length of at least strlen(pszTag) + 1 + 1 (+ 1) bytes
 */
void encodeChar(const char *pszTag, const char chData, char *pszResult)
{
    sprintf(pszResult, "%s=%c", pszTag, chData);
}

Character parameter

Character data is read as a single character string.
Example: 
/*
 Decode a character value
 param pszData [i] parameter string
 return the character data in the parameter string
 */
char decodeChar(const char *pszData)
{
    return *pszData;
}

String return

String data is returned without encoding.
Example: 
/*
 Encode a string value
 param pszTag [i] the tag name
 param pszData [i] zero terminated string value to be encoded
 param pszResult [io] buffer that will be filled with the encoded string.
       pszResult must have a length of at least strlen(pszTag) + 1 + strlen(pszData) (+ 1) bytes
 */
void encodeChar(const char *pszTag, const char *pszData, char *pszResult)
{
    sprintf(pszResult, "%s=%s", pszTag, pszData);
}

String parameter

String data is directly read from the parameter option.
Example: 
/*
 Decode a string value
 param pszData [i] parameter string
 return the string data in the parameter string
 */
const char *decodeString(const char *pszData)
{
    return pszData;
}

Base64-encoded String return

Binary data is Base64-encoded and the resulting string is returned.
Note:
You may have to replace all ' ' (space) characters against '+' (plus) characters in the returned stream.

Some Requests include a specification of the Base64 encoding; use Base64Url to assure that the encoded string is URL safe
Example: 

/*
 Encode a string value
 param pszTag [i] the tag name
 param pszData [i] zero terminated string value to be encoded
 param pszResult [io] buffer that will be filled with the encoded string.
       pszResult must have a length of at least strlen(pszTag) + 1 + (iEntryLen * 8 + 5) / 6 + 1 (+ 1) bytes
 */
void encodeBase64(const char *pszTag, const char *pszData, char *pszResult)
{
    char *pOut = 0;
    int iOut = 0;
    Base64Encode(pEntry, iEntry, &pOut, &iOut);
    sprintf(pszResult, "%s=%s", pszTag, pOut);
    FREE(pOut);
}

Base64-encoded data

String or binary data is Base64-decoded. The Base64 encoding may either equal rfc3548 or rfc4648.
Example: 
/*
 Decode a base64-encoded string
 param pszData [i] parameter string
 return the string data in the parameter string
 */
void decodeBase64(const char *pszData, unsigned char *pData, unsigned int *piLen)
{
    char *pOut = 0;
    Base64Decode(pszData, strlen(pszData), pOut, piLen);
    memcpy(pData, pOut, *piLen);
    FREE(pOut);
}

Binary data return

Arrays of binary data are returned as hexadecimal coded ASCII string.
Example: 
/*
 Encode a binary data array
 param pszTag [i] the tag name
 param pszEntry [i] the entry data to be encoded
 param iEntryLen [i] the length of the entry data array [in bytes]
 param pszResult [io] buffer that will be filled with the encoded string.
       pszResult must have a length of at least strlen(pszTag) + 1 + 2 * iEntryLen (+ 1) bytes
 */
void encodeByteArray(const char *pszTag, const char *pszEntry, int iEntryLen, char *pszResult)
{
    int ik;
    char *px;
    px = pszResult;
    px += sprintf(px, "%s=", pszTag);
    for(ik = 0; px = pszResult; ik < iEntryLen; ik++) {
        sprintf(px, "%02X", pszEntry[ik]);
        px += 2;
    }
}

Binary data parameter

Arrays of binary data are passed as hexadecimal coded ASCII string.
Example: 
/*
 Decode a binary data array
 param pszParameter [i] the parameter data to be decoded
 param pszResult [io] buffer that will be filled with the decoded string.
       pszResult must have a length of at least strlen(pszParameter) / 2 + 1 bytes
 */
void decodeByteArray(const char *pszParameter, char *pszResult)
{
    int ik;
    const char *px;
    for(ik = 0; px = pszParameter; isxdigit(*px) && isxdigit(*(px + 1); ik++) {
        pszEntry[ik] = ((ascii2hex(*px) << 4) & 0xf0) + (ascii2hex(*(px + 1)) & 0xf);
        px += 2;
    }
}

/*
 Convert a character to a hex nibble
 param ch [i] the character to be converted
 return the hexadecimal equivalent
 */
unsigned char ascii2hex(const char ch)
{
   if(ch >= '0' && ch <= '9')
       return ch - '0';
   if(ch >= 'A' && ch <= 'F')
       return ch - 'A' + 10;
   if(ch >= 'a' && ch <= 'f')
       return ch - 'a' + 10;
   return 0;    // error, check for valid hex characters before !!
}