4. Using the Harlequin Direct API
Created Date: 16 Feb, 2021 12:04
Last Modifed Date: 29 Nov, 2021 14:48
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;
}
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 |
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 |
hd_getCpuUsage | (hdInstanceId id, uint64_t* result) | Populates Note: This fails if |
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 |
| ( | Returns the variant of the license used to run Harlequin Direct. If a password has not been successfully set yet, return Return value:
|
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 Fails if 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 |
| 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 |
hd_registerDisconnectedEventHandler |
| Registers the function pointer Note: This fails if |
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 |
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 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
Returns as soon as the jobs have been queued for submission. The command reserves as many 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 |
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 |
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 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 |
currentPage | uint64_t | The current page being processed in the current Job. If no Job is currently being worked on, then this field contains |
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 |
averageThroughput | double | The average throughput of the pipeline measured in MB/s. |