Table of Contents

Search

  1. Preface
  2. Part 1: On-Prem Operations
  3. Part 2: Parameter and Element Reference
  4. Appendix A: Geocode Countries
  5. Appendix B: Certified Mode Values

On-Premises Developer Guide

On-Premises Developer Guide

Retrieving the Job Results

Retrieving the Job Results

The operations to retrieve the output data and to submit the input data are similar. To fetch the verified addresses, use the IDVE_GetJSON() or IDVE_GetJSONW() function. The IDVE_GetJSON() function returns the data in a UTF-8-encoded string, whereas the IDVE_GetJSONW() function returns the data in a UTF-16-encoded string. The functions otherwise operate identically. The JSON functions operate on JSON values.

Retrieving the Job Results in the UTF-8 Encoding

The following sample code shows the structure of the IDVE_GetJSON() function:
IDVE_EXPORTCALL1 IDVE_StatusCode IDVE_EXPORTCALL2
IDVE_GetJSON
( const char* const kpksCustomerID, const char* const kpksURI, char* const kpsValueBuffer, const IDVE_U64 ku64ValueBufferSize, IDVE_U64* const kpu64SizeWritten, IDVE_Bool* const kpbIsValuePresent, char* const kpsExtStatusMsg );
The following table shows the parameter definitions of the IDVE_GetJSON() function:
Parameter
Operation
Comment
const char* const kpksCustomerID
[in]
Pointer to the zero-terminated 7-bit ASCII-encoded customer ID. The value might not be NULL.
const char* const kpksURI
[in]
Pointer to the zero-terminated 7-bit ASCII URI, for example "
AV/v1/Jobs/0/IO/Outputs/0/Results/0/Variants/0
". The value might not be NULL.
char* const kpsValueBuffer
[out]
Pointer to the output buffer that receives the UTF-8-encoded JSON value and the terminating zero.
The JSON value may be an output address, or it may be the path to the file that contains the set of output addresses.
const IDVE_U64 ku64ValueBufferSize
[in]
Size of the output buffer in code units, including the terminating zero.
IDVE_U64* const kpu64SizeWritten
[out]
Pointer to an unsigned 64-bit integer value that receives the size of the output written in code units, excluding the terminating zero. The value can be NULL.
IDVE_Bool* const kpbIsValuePresent
[out]
Pointer to the JSON value to be retrieved by the function call. If you provide a valid pointer for kpbIsValuePresent, the function will indicate if the value at the given URI is present by setting kpbIsValuePresent to true or false.
If you provide NULL for kpbIsValuePresent and the JSON value that you want to retrieve does not exist, the function call reports an error. If you provide NULL for kpbIsValuePresent and the JSON value exists, it is retrieved normally.
char* const kpsExtStatusMsg
[out]
Pointer to a buffer of size IDVE_EXT_STATUS_MSG_BUFFER_SIZE for an optional extended status message. The value can be NULL.

Retrieving the Job Results in the UTF-16 Encoding

The following sample code shows the structure of the IDVE_GetJSONW() function:
IDVE_EXPORTCALL1 IDVE_StatusCode IDVE_EXPORTCALL2
IDVE_GetJSONW
( const char* const kpksCustomerID, const char* const kpksURI, IDVE_WChar* const kpsValueBuffer, const IDVE_U64 ku64ValueBufferSize, IDVE_U64* const kpu64SizeWritten, IDVE_Bool* const kpbIsValuePresent, char* const kpsExtStatusMsg );
The following table shows the parameter definitions of the IDVE_GetJSONW() function:
Parameter
Operation
Comment
const char* const kpksCustomerID
[in]
Pointer to the zero-terminated 7-bit ASCII-encoded customer ID. The value might not be NULL.
const char* const kpksURI
[in]
Pointer to the zero-terminated 7-bit ASCII URI, for example "
AV/v1/Jobs/0/IO/Outputs/0/Results/0/Variants/0
". The value might not be NULL.
IDVE_WChar* const kpsValueBuffer
[out]
Pointer to the output buffer that receives the UTF-16-encoded JSON value and the terminating zero.
The JSON value may be an output address, or it may be the path to the file that contains the set of output addresses.
const IDVE_U64 ku64ValueBufferSize
[in]
Size of the output buffer in code units, including the terminating zero.
IDVE_U64* const kpu64SizeWritten
[out]
Pointer to an unsigned 64-bit integer value that receives the size of the output written in code units, excluding the terminating zero. The value can be NULL.
IDVE_Bool* const kpbIsValuePresent
[out]
Pointer to the JSON value to be retrieved by the function call. If you provide a valid pointer for kpbIsValuePresent, the function will indicate if the value at the given URI is present by setting kpbIsValuePresent to true or false.
If you provide NULL for kpbIsValuePresent and the JSON value that you want to retrieve does not exist, the function call reports an error. If you provide NULL for kpbIsValuePresent and the JSON value exists, it is retrieved normally.
char* const kpsExtStatusMsg
[out]
Pointer to a buffer of size IDVE_EXT_STATUS_MSG_BUFFER_SIZE for an optional extended status message. The value can be NULL.

Example: Retrieving the Job Results

The following example shows an IDVE_GetJSON() function call to retrieve a job result:
char sJSON[ 50 * 1024 ]; char sExtStatusMsg[ IDVE_EXT_STATUS_MSG_BUFFER_SIZE ]; IDVE_StatusCode i32StatusCode = IDVE_GetJSON( "", “AV/v1/Jobs/0/IO/Outputs/0”, sJSON, sizeof( sJSON ), NULL, NULL, sExtStatusMsg );
The URI value that you pass to the IDVE_GetJSON() function is the job URI returned by the IDVE_Post call and the sub-URI pointing to the first output of the job. An implementation typically concatenates the URI fragments dynamically.
The output is not a URI, but rather a complete JSON document in UTF-8 format.


Updated November 02, 2020