Created Date: Feb 16, 2021 12:04
Last Modifed Date: May 26, 2021 10:39

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 functions

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 will lead 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.

Note: This fails if the jobId is invalid or no print run is active.

hd_connectToInstance(hdInstanceId id, const SocketConfiguration* socketConfiguration)Initializes an instance of Harlequin Direct but first requires running a Harlequin Direct process; pair this with an eventual call to hd_shutDownInstance
hd_createInstance(hdInstanceId id, const SocketConfiguration* socketConfiguration)Initializes an instance of Harlequin Direct, but requires a Harlequin Direct process to already been running. (Note: This should no longer be used, use hd_connectToInstance instead)
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 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.

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 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 HarlequinDirect 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 a connection to Harlequin Direct.

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.

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.

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.

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.

Example code

The code snippets below showcase what you can do with the Harlequin Direct API. The HarlequinDirect_API_Example.cpp file provided with Harlequin Direct gives more examples.

The following code assumes a launched Harlequin Direct instance.


    const std::string printFlatOemId = argc > 5 ? argv[5] : "";
    if (hd_startup(argv[4], printFlatOemId.c_str()) != DirectReturnCode_Success)
    {
        printf("hd_startup Failed\n");
        return 1;
    }
CODE

The code snippet above shows how you can initialize a connection to HarlequinDirect with the hd_startup function. Two parameters are being passed into this function, which are the license password (argv[4]) and a printFlatOemID . 

    SocketConfiguration config = { "127.0.0.1", 9999) };

    if (hd_connectToInstance(instanceId, &config) != DirectReturnCode_Success)
    {
        printf("hd_connectToInstance Failed\n");
        return 1;
    }
CODE

The above code block shows the hd_connectToInstance API function, where the code connects to an instance of Harlequin Direct. The SocketConfiguration receives the IP address of the machine running Harlequin Direct (localhost  in this case) and the port number to communicate with it. This config structure is then given to the hd_connectToInstance function.

    std::mutex mutex;
    void jobStartedHandler(hdInstanceId id, hd_jobId jobId, uint64_t pageCount, void* priv)
    {
        std::scoped_lock lock(mutex);
        // logic involving the jobId ... details omitted ...
    }

    // ...

    hd_jobId submit_job(hdInstanceId instanceId)
    {
        std::scoped_lock lock(mutex)
        hd_jobId jobId = 0;
        if (hd_submitJob(instanceId, "brochure.pdf", &jobId, 1) != DirectReturnCode_Success)
        {
            printf("Failed to submit Job 1\n");
            return 0;
        }
        return jobId;
    }
CODE

Lastly, this code shows you how 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.

Querying Print Run Status

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

Calling hd_getPrintRunStatus will retrieve the information and populate 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 will contain 0.

currentPageuint64_t

The current page being processed in the current Job.

If no Job is currently being worked on, then this field will contain 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 will contain 0.

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