On-Premises Developer Guide

6.4.0
- 6.5.0
- 6.3.0
- 6.2.0
- 6.1.0
- 6.0.0

Back Next

Creating a Job

A job object is a passive data structure that contains parameters, input data, and result data

based on the

AVJob.schema.json

specification

. Each job has its own Uniform Resource Identifier (URI), which the function returns when creating the job.

Before you run a job request, use the IDVE_Post() or IDVE_PostW() function to create a job object. Use the IDVE_Post() function to retrieve the job URI in the UTF-8 encoding. Use the IDVE_Post()W function to retrieve the job URI in the UTF-16 encoding.

Each function allows you to append one or more commands to the URI to specify the type of action that the function must perform. To create a job, append

create

to the URI string. The

create

command is not a part of the schema.

The functions also provide arguments to specify input and output data. The input and output content depends on the commands that you use.

All parameters, elements, and values in Address Verification JSON schemas are case-sensitive. Take care to follow the character case that the AVJob.schema.json file specifies.

Creating a Job: UTF-8 Variant

The following sample code shows the structure of the IDVE_Post() function:

IDVE_EXPORTCALL1 IDVE_StatusCode IDVE_EXPORTCALL2 IDVE_Post(
   const char* const kpksCustomerID,
   const char* const kpksURI,
   const char* const kpksInput,
   const IDVE_U64 ku64InputLength,
   char* const kpsOutput,
   const IDVE_U64 ku64OutputBufferSize,
   IDVE_U64* const kpu64SizeWritten,
   char* const kpsExtStatusMsg
);

The following table shows the parameter definitions for the IDVE_Post() 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. The value might not be NULL.
const char* const kpksInput	[in]	Pointer to the UTF-8-encoded input string. The value can be NULL if there is no input string. The content of the input string depends on the command. For the create command, the string content must be NULL.
const IDVE_U64 ku64InputLength	[in]	Length of the input string in number of code units excluding a possibly terminating zero. The value can be string length or IDVE_AUTOLEN.
char* const kpsOutput	[out]	Pointer to an UTF-8-encoded output string buffer for the output. The value can be NULL. For the create command, the output string contains the job ID and the full URI to the root of the job.
const IDVE_U64 ku64OutputBufferSize	[in]	Size of the output string 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.
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.

Creating a Job: UTF-16 Variant

The following sample code shows the structure of the IDVE_PostW() function:

IDVE_EXPORTCALL1 IDVE_StatusCode IDVE_EXPORTCALL2 IDVE_PostW(
const char* const kpksCustomerID,    
const char* const kpksURI,           
const IDVE_WChar* const kpksInput,   
const IDVE_U64 ku64InputLength,      
IDVE_WChar* const kpsOutput,         
const IDVE_U64 ku64OutputBufferSize, 
IDVE_U64* const kpu64SizeWritten,    
char* const kpsExtStatusMsg         
);

The following table shows the parameter definitions for the IDVE_PostW() 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. The value might not be NULL.
const IDVE_WChar* const kpksInput	[in]	Pointer to the UTF-16-encoded input string. The value can be NULL if there is no input string. The content of the input string depends on the command. For the create command, the string content must be NULL.
const IDVE_U64 ku64InputLength	[in]	Length of the input string in number of code units excluding a possibly terminating zero. The value can be string length or IDVE_AUTOLEN.
IDVE_WChar* const kpsOutput	[out]	Pointer to an UTF-16-encoded output string buffer for the output. The value can be NULL. For the create command, the output string contains the job ID and the full URI to the root of the job.
const IDVE_U64 ku64OutputBufferSize	[in]	Size of the output string 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.
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: Creating a Job

The following example shows an IDVE_Post() function call to create a job:

char sJobURI[ IDVE_POST_OUTPUT_BUFFER_SIZE ];
char sExtStatusMsg[ IDVE_EXT_STATUS_MSG_BUFFER_SIZE ];
IDVE_StatusCode i32StatusCode = IDVE_Post( "", "AV/v1/Jobs/create", NULL, 0, sJobURI, sizeof( sJobURI ), NULL, sExtStatusMsg );

The parameters in the IDVE_Post call have the following meanings:

The first parameter is an empty string. You can specify a customer ID.

The second parameter is the URI.

The third parameter is an unused input string.

The fourth parameter is the length of the input string.

The fifth parameter is a pointer to an output string buffer.

The sixth parameter is the length of the output string buffer.

The seventh parameter is NULL, because you do not want to receive the number of chars of the output string.

The final parameter is a pointer to an output buffer for an extended error message.

The call creates a new job object and, in case of success, returns its URI in the string buffer sJobURI. In the URI string

"AV/v1/Jobs/0"

, the final element "0" might be arbitrary, for example

E9FC48AF9

. The value is a handle to a unique job.

After you create a job object, set or verify the parameters.

Verifying Addresses

Download Guide

Watch

Comments

Communities

Knowledge Base

Success Portal

0 COMMENTS

We’d like to hear from you! Log in to comment.

Rename Saved Search

Table of Contents

On-Premises Developer Guide

On-Premises Developer Guide

Creating a Job

Creating a Job

Creating a Job: UTF-8 Variant

Creating a Job: UTF-16 Variant

Example: Creating a Job