Created Date: Feb 16, 2021 12:04
Last Modifed Date: Jul 22, 2021 10:47

We recommend that you use the C-compatible API to drive Harlequin Direct.

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 functionParametersDescription
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 suffixMeaning
SuccessThe command was successful.
InvalidArgumentOne or more of the given arguments was invalid (for example, empty/null).
UnknownErrorAn unknown error occurred.
CPlusPlusExceptionA C++ exception was thrown.
UnrecognizedCommandThe given command was not recognized.
NoActivePrintRunThe command given could not execute, as no print run is active.
PrintRunActiveThe command given could not execute, as a print run is active.
FailedToLoadConfigFileThe given config file could not be opened.
JobFileNotFoundThe 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). 

InvalidPasswordThe 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).

LicenceAlreadySetCould not set license because a license is already set.
NoConnectionThe command is not sent, as there is no socket connection.
PluginFailedToLoadFailed to load a plugin (for example, it may not exist at the specified path).
PrintRunBusyThe action is not executed, as the active print run is still processing one or more jobs.
InstanceNotFoundThe specified Harlequin Direct instance is not found.
ApiAlreadyShutDownThe API is already shut down when trying to issue a shut down.
ApiAlreadyActiveThe API is already active when trying to activate it.
InvalidInterfaceSocketOperationThe interface socket operation failed.
InterfaceSocketAlreadyStartedThe interface socket is already started when trying to start it.
InvalidJobIDThe given job ID does not point to an existing job.
BadClripDirectoryThe specified Scalable RIP directory is not a directory.
BadOutputDirectoryThe specified output directory for the Scalable RIP is either unspecified or not a directory.
ScalableRipNotFoundThe Scalable RIP is not found in the specified directory.
ZeroNumberOfRipsThe number of rips specified for the Scalable RIP is zero.
BadSpdDirectoryThe specified ScreenPro Direct directory is not a directory.
ScreenProDirectNotFoundScreenPro Direct is not found in the specified directory.
SPDConfigFileNotFoundThe specified ScreenPro Direct config file is not found.
DuplicateScreenProDirectInstanceA ScreenPro Direct instance already exists with the given ID.
InvalidScreenProDirectOperationThe issued command cannot be executed in ScreenPro Direct's current state (for example, attempting to start when it is already active).
ScreenProDirectOperationFailedA ScreenPro Direct command is issued, and it returns with a failure code.
PipelineStatusErrorAn error occurs while fetching the pipeline status.
InvalidSPDStatusTransitionCan'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).

InvalidScreenDirectoryThe given screen directory does not exist or is not empty.
InvalidFilenameThe given file name does not exist.
DuplicateHarlequinDirectInstanceA Harlequin Direct instance already exists with the given ID.
FailedToRegisterHandlerAn event handler failed to register.
HeartbeatActiveCan't execute command because a heartbeat is already active.
NoHeartbeatActiveNo heartbeat is active to carry out the given command.
ResponseTimeoutThe Harlequin Direct socket timed out while expecting a response.
ResultTimeoutThe Harlequin Direct socket timed out while expecting a result.
FailedToSendDataData failed to send over the socket.
ConnectionFailedFailed 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...

InvalidOperationAn attempt is made to perform an operation that is not valid for the current state.
ScalableRipFailedToStart The Scalable RIP failed to start.
PluginCommandFailedThis 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:

FieldTypeMeaning
jobsSubmitteduint64_tThe number of Jobs that have been submitted to the print run over its lifetime.
jobsCompleteduint64_tThe number of Jobs that have completed during this print run's lifetime.
currentJobIDuint64_t

The ID of the Job currently being worked on.

If no Job is currently being worked on, then this field contains 0.

currentPageuint64_t

The current page being processed in the current Job.

If no Job is currently being worked on, then this field contains 0.

pageCountuint64_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.

averageThroughputdoubleThe average throughput of the pipeline measured in MB/s.