Integrating the API

Windows

The HarlequinDirect_API folder, in the Harlequin Direct release, contains the following:

DirectReturnCodes.h
HarlequinDirect_API.h
HarlequinDirect_API.dll
HarlequinDirect_API.lib
HarlequinDirect_API_Example.cpp

To access the API functionality, include the HarlequinDirect_API.h header file in your source code:

#include "path/to/HarlequinDirect_API.h"

You may wish to add the HarlequinDirect_API folder to your include path.

Also, link your code with HarlequinDirect_API.lib and distribute HarlequinDirect_API.dll with your binary. Please consult your build system documentation for more information on linking static libraries.

Linux

The HarlequinDirect_API directory, in the ScreenPro Direct release, contains the following:

DirectReturnCodes.h
HarlequinDirect_API.h
HarlequinDirect_API.so
HarlequinDirect_API_Example.cpp

To access the API functionality, include the HarlequinDirect_API.h header file in your source code:

#include "path/to/HarlequinDirect_API.h"

You may wish to add the HarlequinProDirect_API directory to your include path.

Also, link your code with HarlequinDirect_API.so and distribute HarlequinDirect_API.so with your binary. Please consult your build system documentation for more information on linking shared objects.

API workflow example

The code below is a full working example of how to start up the API, connect to an instance of Harlequin Direct (running on the local machine, using port 9999 to receive commands), submit a job, and properly shut down the API.

#include <cstdio>
#include "HarlequinDirect_API.h"
#include <chrono>
#include <thread>

int simpleHarlequinDirectWorkflowExample()
{
	const char* licensePassword = "1234567"; // This is used to unlock the license in the HarlequinDirect config file
	const char* printFlatOemId = "oem"; // The PrintFlat Oem Id is set here, which should match the value in your PrintFlat subscription file. This is an optional parameter and can be set as "" if unused.
	const char* relativePathToPDF = "brochure.pdf"; // The relative path to the working directory, where the PDF file is stored, is set here.

	/*
    * The hd_startup function is used to initialize the HarlequinDirect API. Two parameters are being passed into this function, which is licensePassword and a printFlatOemID .
    * This must be called before all other methods and, upon success, must be paired with an eventual call to hd_shutdown.
    */
	if (hd_startup(licensePassword, printFlatOemId) != DirectReturnCode_Success)
	{
		printf("hd_startup Failed\n");
		return 1;
	}

	hdInstanceId instanceId = 1;
	SocketConfiguration config = { "127.0.0.1", 9999 }; // These example settings are for running HarlequinDirect on a local machine with port 9999 for communication. 

	/*
	* hd_connectToInstance can be used to connect to a running instance, or create a new running instance, of the HarlequinDirect process.
	* Upon success, this should be paired with an eventual call to hd_shutDownInstance.
	*/
	if (hd_connectToInstance(instanceId, &config) != DirectReturnCode_Success)
	{
		printf("hd_connectToInstance Failed\n");
		return 1;
	}

	/*
	* hd_startPrintRun is used to start the print run so that jobs can be submitted.
	* Returns failure if print run is already running.
	* Upon success, this must be paired with an eventual call to hd_stopPrintRun to end the print run.
	*/
	if (hd_startPrintRun(instanceId) != DirectReturnCode_Success)
	{
		printf("hd_startPrintRun failed\n");
		return 1;
	}

	hd_jobId jobId = 0;
	uint64_t numberOfCopies = 1;

	/*
	* hd_submitJob is used to submit a job to be RIPped.
	* You pass in an instanceId, the PDF to be RIPped (which is a path relative to the working directory for the Harlequin Direct instance), a job Id, and the number of copies you want.
	* Notice how the hd_submitJob call is synchronized with the jobStartedEvent handler using a mutex; since jobs may start before hd_submitJob returns, your event handlers should be designed with this in mind.
	* Returns as soon as the jobs have been queued for submission.
	* Returns failure if print run is not running, if filePath is invalid, if the file cannot be accepted, outJobId is NULL, or copyCount is 0.
	*/
	if (hd_submitJob(instanceId, relativePathToPDF, &jobId, numberOfCopies) != DirectReturnCode_Success)
	{
		printf("Failed to submit Job 1\n");
		return 0;
	}

	/*
	* In order for HarlequinDirect to shutdown properly, you will need to ensure all jobs have been completed.
	* One method you can use is to sleep the thread for a few seconds to give HarlequinDirect enough time to finish processing.
	*/
	std::this_thread::sleep_for(std::chrono::milliseconds(3000));

	/*
	* hd_stopPrintRun stops the print run
	* Returns failure if print run is not running.
	*/
	if (hd_stopPrintRun(instanceId) != DirectReturnCode_Success)
	{
		printf("Failed to stop print run\n");
		return 1;
	}

	/*
	* hd_shutDownInstance shuts down the HarlequinDirect instance.
	* There should be no calls to the instance during, or after, this call has been made, and will fail if print run is running.
	*/
	if (hd_shutDownInstance(instanceId) != DirectReturnCode_Success)
	{
		printf("hd_shutDownInstance Failed\n");
		return 1;
	}

	/*
	* hd_shutDown shuts down the Harlequin Direct API.
	*/
	if (hd_shutDown() != DirectReturnCode_Success)
	{
		printf("Failed to shutdown\n");
		return 1;
	}

	printf("shutdown");
	return 0;
}

CODE

For a more detailed function reference, please see the next section.

API function reference

Below is a list of functions which the Harlequin Direct API provides. You can find these and additional information in the HarlequinDirect_API.h file. Unless otherwise noted, API functions return a DirectReturnCode (see next section for details).

API functions are designed to be called serially for a given Harlequin Direct instance. Overlapping calls to the same instance leads to undefined behavior.

API function	Parameters	Description
`hd_abortPrintRun`	`(hdInstanceId id)`	Terminates the active print run immediately without waiting for jobs to finish. Cancels all queued jobs and stops RIP and ScreenPro Direct processes.
`hd_cancelJob`	`(hdInstanceId id, const hd_jobId jobId)`	Requests a prompt cancellation of the specified job. Returns immediately. You subsequently receive a JOB_COMPLETED event when the cancellation is complete. Note: This fails if the `jobId` is invalid or no print run is active.
`hd_connectToInstance`	`(hdInstanceId id, const SocketConfiguration* socketConfiguration)`	Connects to a running instance of the HarlequinDirect process; pair this with an eventual call to `hd_shutDownInstance`.
`hd_disconnectFromInstance`	`(hdInstanceId id)`	Disconnects from the Harlequin Direct instance.
`hd_force_product_detect`	`(hdInstanceId id, uint64_t controllerNumber)`	Sends a product detect signal to supported hardware. Note: This fails if no print run is active.
`hd_getAverageMBsThroughput`	`(hdInstanceId id, double* outThroughput)`	Requests and displays the average throughput of raster data in MB/s. Note: This fails if no print run is active, or if `outThroughput` is `NULL`.
`hd_getCpuUsage`	`(hdInstanceId id, uint64_t* result)`	Populates `result` with the system's current CPU usage. Note: This fails if `result` is `NULL`.
`hd_getHarlequinVersionNumber`	`(hdInstanceId id, uint64_t* major, uint64_t* minor, uint64_t* revision, uint64_t* build)`	Returns with the version number of the connected Harlequin Direct Instance. Note: This fails if you did not call `hd_startup.`
`hd_getLicenseVariant`	(`hdInstanceId` `id`, `uint64_t* licenseVariant`)	Returns the variant of the license used to run Harlequin Direct. If a password has not been successfully set yet, return `0`. Return value: `0`: Unknown `1`: Standard `2`: High Data Rate `3`: Ultra High Data Rate `4`: Ultra High Data Rate (none; plugin only).
`hd_getPipelineStatus`	`(hdInstanceId id, char* result, uint64_t* ResultLength)`	Populates `result` with a representation of the current pipeline state.
`hd_getPrintRunStatus`	`(hdInstanceId id, hd_PrintRunStatus* result)`	Populates `result` with a representation of the current print run state. See the Querying Print Run Status section below for details of the `hd_PrintRunStatus` struct. Fails if `result` is `NULL`. Note: We do not recommend calling this function at high frequency (that is, several times per second), as it could negatively affect performance.
`hd_getScreenProDirectVersionNumber`	`(hdInstanceId id, uint64_t* major, uint64_t* minor, uint64_t* revision, uint64_t* build)`	Returns with the version number of the connected ScreenPro Direct Instance. Note: This fails if there is no active print run.
`hd_getSheetCounter`	`(hdInstance id, uint64_t* sheetCounter)`	Returns the total sheet count.
`hd_isActive`	`(hdInstanceId id)`	Reports if the Harlequin Direct API is active.
`hd_isHeartbeatRunning`	`(HdBool* outIsRunning)`	Indicates whether or not the heartbeat loop is running. Note: This fails if `outIsRunning` is `NULL`.
`hd_registerDisconnectedEventHandler`	`(HdDisconnectedEventHandler handlerFunc, void* priv)`	Registers the function pointer `handlerFunc` to call if a disconnection event arises. Provide client data using the `priv` parameter, which passes in to the provided callback function. Note: This fails if `handlerFunc` is `NULL`.
`hd_resetSheetCounter`	`(hdInstance id)`	Resets the total sheet count to `0`.
`hd_shutDownInstance`	`(hdInstanceId id)`	Shuts down the Harlequin Direct instance. Note: This fails if a print run is active.
`hd_shutdown`		Shuts down the API.
`hd_startHeartbeat`	`(uint64_t interval, uint64_t maxSkipped)`	Starts the heartbeat loop on a separate thread. It sends a heartbeat signal to Harlequin Direct every `interval` milliseconds. If no response is received within the timeout (also equal to `interval`), then a skipped beat is recorded. If the number of skipped beats exceeds `maxSkipped`, then the Command socket is disconnected, a disconnected event is raised, and the loop is stopped.
`hd_startPrintRun`	`(hdInstance id)`	Starts a print run. Must be paired with an eventual call to `hd_stopPrintRun` if this call is successful. Note: This fails if a print run is running.
`hd_startup`	`(const char* licensePassword, const char* printFlatOemId)`	Initializes the Harlequin Direct API. If using PrintFlat, the `printFlatOemId` must be valid for any PrintFlat calibrations to be used during screening; the call to `hd_startPrintRun` returns `ScreenProDirectOperationFailed` if it is not valid.
`hd_stopHeartbeat`		Stops the heartbeat loop. Note: This fails if no heartbeat loop is running.
`hd_stopPrintRun`	`(hdInstanceId id)`	Stops the print run. Note: This fails if no print run is active.
`hd_submitConfig`	`(hdInstance id, const char* configFile)`	Submits a configuration file to be loaded for the next print run. Note: This fails if the supplied instance is not idle (or if the path to the config file is null, invalid, or not a valid JSON file).
`hd_submitJob`	`(hdInstanceId id, const char* filePath, hd_jobId* outJobId, uint64_t copyCount)`	Submits the file path to be processed. The file may be a PDF, TIFF, or XML. Returns as soon as the jobs have been queued for submission. The command reserves as many `jobIds` as copies requested (for example, submitting your first job of 10,000 copies reserves `jobIds` 1 through 10,000). Note: Job events may be raised before this function returns. You must ensure that your submission thread is correctly synchronized with your event handlers.
`hd_submitJobWithConfig`	`(hdInstanceId id, const char* filePath, hd_jobId* copyCount, const char* jobConfig)`	Submits the file path to be processed, along with a `jobConfig`. The file may be a PDF, TIFF, or XML. `jobConfig` may be `NULL`, in which case this function behaves the same as `hd_submitJob`. Returns as soon as the jobs have been queued for submission. The command reserves as many `jobIds` as copies requested (for example, submitting your first job of 10,000 copies reservse `jobIds` 1 through 10,000). Note: Job events may be raised before this function returns. You must ensure that your submission thread is correctly synchronized with your event handlers.
`hd_turnOffHeadPower`	`(hdInstanceId id)`	Turns off the head power to supported hardware. Note: This fails if no print run is active.
`hd_turnOnHeadPower`	`(hdInstanceId id)`	Turns on the head power to supported hardware. Note: This fails if no print run is active.
`hd_runPluginCommand`	`(hdInstanceId id, const char* pluginName, const char* command, char* result, uint64_t* pResultLength)`	Populates `result` with a plugin-dependent response to `command`. `pResultLength` should initially point to the length of `command`. If `command` is not large enough to hold the entire result, `pResultLength` updates the length to the required length - so a second call can be made.

Return codes

Each of the Harlequin Direct API functions returns a DirectReturnCode on completion, which is an enum defined in DirectReturnCodes.h. Each return code starts with DirectReturnCode. The return codes are documented below:

Return code suffix	Meaning
`Success`	The command was successful.
`InvalidArgument`	One or more of the given arguments was invalid (for example, empty/null).
`UnknownError`	An unknown error occurred.
`CPlusPlusException`	A C++ exception was thrown.
`UnrecognizedCommand`	The given command was not recognized.
`NoActivePrintRun`	The command given could not execute, as no print run is active.
`PrintRunActive`	The command given could not execute, as a print run is active.
`FailedToLoadConfigFile`	The given config file could not be opened.
`JobFileNotFound`	The given file argument is not found at the specified path.
`InvalidConfig`	The given config file is invalid. This includes bad JSON syntax, wrongly typed fields, invalid directories specified within the config, or bad combinations of values (for example, enabling both Continuous and Mixed mode).
`InvalidPassword`	The password is invalid for the given license.
`InvalidLicence`	The license string or license settings are invalid (for example, rip count setting is too high for the specified license).
`LicenceAlreadySet`	Could not set license because a license is already set.
`NoConnection`	The command is not sent, as there is no socket connection.
`PluginFailedToLoad`	Failed to load a plugin (for example, it may not exist at the specified path).
`PrintRunBusy`	The action is not executed, as the active print run is still processing one or more jobs.
`InstanceNotFound`	The specified Harlequin Direct instance is not found.
`ApiAlreadyShutDown`	The API is already shut down when trying to issue a shut down.
`ApiAlreadyActive`	The API is already active when trying to activate it.
`InvalidInterfaceSocketOperation`	The interface socket operation failed.
`InterfaceSocketAlreadyStarted`	The interface socket is already started when trying to start it.
`InvalidJobID`	The given job ID does not point to an existing job.
`BadClripDirectory`	The specified Scalable RIP directory is not a directory.
`BadOutputDirectory`	The specified output directory for the Scalable RIP is either unspecified or not a directory.
`ScalableRipNotFound`	The Scalable RIP is not found in the specified directory.
`ZeroNumberOfRips`	The number of rips specified for the Scalable RIP is zero.
`BadSpdDirectory`	The specified ScreenPro Direct directory is not a directory.
`ScreenProDirectNotFound`	ScreenPro Direct is not found in the specified directory.
`SPDConfigFileNotFound`	The specified ScreenPro Direct config file is not found.
`DuplicateScreenProDirectInstance`	A ScreenPro Direct instance already exists with the given ID.
`InvalidScreenProDirectOperation`	The issued command cannot be executed in ScreenPro Direct's current state (for example, attempting to start when it is already active).
`ScreenProDirectOperationFailed`	A ScreenPro Direct command is issued, and it returns with a failure code.
`PipelineStatusError`	An error occurs while fetching the pipeline status.
`InvalidSPDStatusTransition`	Can't transition ScreenPro Direct to the given status.
`InvalidPlaneNumber`	The given plane number argument to the `JobXmlSerialiser` is invalid (for example, when attempting to set plane parameters of a plane that already exists, or adding a filename to a plane number that doesn't exist).
`InvalidScreenDirectory`	The given screen directory does not exist or is not empty.
`InvalidFilename`	The given file name does not exist.
`DuplicateHarlequinDirectInstance`	A Harlequin Direct instance already exists with the given ID.
`FailedToRegisterHandler`	An event handler failed to register.
`HeartbeatActive`	Can't execute command because a heartbeat is already active.
`NoHeartbeatActive`	No heartbeat is active to carry out the given command.
`ResponseTimeout`	The Harlequin Direct socket timed out while expecting a response.
`ResultTimeout`	The Harlequin Direct socket timed out while expecting a result.
`FailedToSendData`	Data failed to send over the socket.
`ConnectionFailed`	Failed to establish a connection to a socket.
`InvalidJson`	The given JSON file is invalid. This error code is separate from `InvalidConfig`, as it only concerns JSON files that are not configs (for example, JSON metadata for sprites). The same conditions apply: bad syntax, bad value formatting, or wrongly typed fields...
`InvalidOperation`	An attempt is made to perform an operation that is not valid for the current state.
`ScalableRipFailedToStart`	The Scalable RIP failed to start.
`PluginCommandFailed`	This is returned, when using `hd_runPluginCommand()`, if the result is a failure.

Querying print run status

The hd_PrintRunStatus struct holds information about the currently running print run.

Calling hd_getPrintRunStatus retrieves the information and populates a hd_PrintRunStatus struct with the following fields:

Field	Type	Meaning
`jobsSubmitted`	uint64_t	The number of Jobs that have been submitted to the print run over its lifetime.
`jobsCompleted`	uint64_t	The number of Jobs that have completed during this print run's lifetime.
`currentJobID`	uint64_t	The ID of the Job currently being worked on. If no Job is currently being worked on, then this field contains `0`.
`currentPage`	uint64_t	The current page being processed in the current Job. If no Job is currently being worked on, then this field contains `0`.
`pageCount`	uint64_t	The number of pages that the current Job is comprised of. If no Job is currently being worked on, then this field contains `0`.
`averageThroughput`	double	The average throughput of the pipeline measured in MB/s.