SUBMITJOB4 and SUBMITJOB5

The SUBMITJOB4 and SUBMITJOB5 data structures contain additional parameters for the extended KCM Core APIs. The SUBMITJOB4 data structure is used with SSubmitJobEx4; the SUBMITJOB5 data structure is used with SSubmitJobEx5. The data structures are identical except for the calling conventions used for the callback functions.

typedef struct {
DWORD     Version; // Version of the data structure
DWORD     Extended; // Extended attributes
void*     Context;  // Application data for callbacks

// Callback for progress messages
void    (*Progress) (void* Context, TCHAR *);

// Callback for warnings
BOOL    (*Warning) (void* Context, TCHAR *);	

// Callback for filename validation
TCHAR  *(*ValidateFileName) (void* Context, TCHAR *, BOOL);

	// Callback for data exchange
TCHAR  *(*ExchangeData) (void* Context, TCHAR *, TCHAR *);


TCHAR *Reserved1;
TCHAR *SessionID;   // ITP/Server session ID
TCHAR *Reserved2;
} SUBMITJOB4;

typedef struct {
DWORD     Version;	// Version of the data structure
DWORD     Extended;	// Extended attributes
void* Context;      // Application data for callbacks

// Callback for progress messages
void    (__stdcall *Progress) (void* Context, TCHAR *);

// Callback for warnings
BOOL    (__stdcall *Warning) (void* Context, TCHAR *);	

// Callback for filename validation
TCHAR  *(__stdcall *ValidateFileName) (void* Context, TCHAR *, BOOL);

	// Callback for data exchange
TCHAR  *(__stdcall *ExchangeData) (void* Context, TCHAR *, TCHAR *);


TCHAR *Reserved1;
TCHAR *SessionID;   // ITP/Server session ID
TCHAR *Reserved2;
} SUBMITJOB5;

Version field indicates which other members of the data structure are valid. Currently, the only supported value is SUBMITJOB_4 for the SUBMITJOB4 data structure, and SUBMITJOB_5 for the SUBMITJOB5 data structure.

Extended attributes for the APIs that can be a combination of any of the values described in the following table.

Value	Meaning
0	No extended attributes apply.
OPTION_QUERY_CODEPAGE	The API is allowed to send its codepage to the KCM Core server.
OPTION_RECEIVE_FILE	The API is allowed to receive files from the KCM Core server.
OPTION_SEND_FILE	The API is allowed to send files to the KCM Core server.
OPTION_CONFIRM_DISCONNECT	The caller requires that KCM Core waits for confirmation after reporting a successful job. This option guarantees that the confirmation has been received by the client before KCM Core starts another job. Failure during this disconnect exchange reports the job as failed, but does not trigger an OnError statement.
OPTION_EXCHANGE_DATA	The API is allowed to exchange data with the KCM Core server.
OPTION_VERIFY_CONNECTION	The API is Verify Connection enabled.
OPTION_TCP_NODELAY	Disables the packet size optimizations done by the Nagle algorithm. This option improves responsiveness significantly at the cost of increased network traffic. This option has an effect only if the network connection is between different virtual computers. Connections over the local host/loopback interface are never buffered. Use with caution.
OPTION_ALL_DPS	The job is submitted to run once on all available KCM Document Processors.

Context may hold a pointer to arbitrary data defined by the application. It is not used by the API function. It is passed as the Context parameter to the callback functions Progress, Warning, ValidateFileName, and ExchangeData. You can use it to pass extra, application defined information to these callback functions.

Progress is a pointer to a callback function called by the API whenever the server sends back a progress message. This progress message is passed as parameter to the function Progress. When called, the function is passed the Context member field of the SUBMITJOB4/5 structure in the Context parameter. This function is NULL if the application does not want to receive progress messages.

Warning is a pointer to a callback function called by the API whenever it encounters a recoverable error. This error is passed as a parameter to the function Warning. This function returns TRUE if it wants to continue, and FALSE if the call should be terminated. When called, the function is passed the Context member field of the SUBMITJOB4/5 structure in the Context parameter.

This function can be NULL if the application wants to ignore recoverable errors. The errors are still passed to the KCM Core server but the script can choose to ignore them using the command OnError.

ValidateFileName is a pointer to a callback function called by the API whenever the server wants to receive or send a file from the client. For more information on ValidateFileName, see ValidateFileName.

When called, the function is passed the Context member field of the SUBMITJOB4/5 structure in the Context parameter. This function is NULL if the application does not need to validate file names. In this situation, all suggested file names are accepted.

ExchangeData is a pointer to a callback function called by the API whenever the server wants to exchange data with the client. For more information, see ExchangeData.

When called, the function is passed the Context member field of the SUBMITJOB4/5 structure in the Context parameter. This function is NULL if the application does need to exchange data. In this situation, all attempts to exchange data succeed and return an empty response.

QuickInfo

Header, declared in s_api.h and p_api.h.

Import Library, use sock_api.lib.

Unicode, implemented as both Unicode and ASCII.