Created Date: 19 Feb, 2021 10:18
Last Modifed Date: 29 Nov, 2021 14:48

We recommend that you drive ScreenPro Direct via the C-compatible API.

Integrating the API

Windows

The ScreenProDirect_API folder, in the ScreenPro Direct release, contains the following:

  • ScreenProDirect_API.h
  • ScreenProDirect_API.dll
  • ScreenProDirect_API.lib
  • ScreenProDirect_API_Example\
    • api.example.cpp
    • ScreenProDirect_API_Example.exe

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

#include "path/to/ScreenProDirect_API.h"

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

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

Linux

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

  • ScreenProDirect_API.h
  • ScreenProDirect_API.so
  • ScreenProDirect_API_Example\
    • api.example.cpp
    • ScreenProDirect_API_Example

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

#include "path/to/ScreenProDirect_API.h"

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

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

API summary

Unless otherwise noted, all API functions use the UNIX convention for return values: 0 on success and 1 on failure.

A list of functions that the ScreenPro Direct API provides follows. You can find these and additional information in the ScreenProDirect_API.h file.

API function

Parameters

Summary

spd_abort_print_run

(spdInstanceId id)

Aborts a print run. All jobs being processed are canceled.

spd_cancel_job

(spdInstanceId id, uint64_t jobId)

Cancels the job with ID jobId .

spd_check_init

()

Checks if the ScreenPro Direct API has been initialized. A return value of 0 indicates that it has been initialized; 1 indicates that it has not.

spd_disable_product_detect

(spdInstanceId id)

Disables the product detect signal.

spd_disconnect

(spdInstanceId id)

Disconnects from the ScreenPro Direct instance with ID id .

spd_enable_product_detect

(spdInstanceId id)

Enables the product detect signal.

spd_end_print_run

(spdInstanceId id)

Ends a print run. Closes the print run to new job submissions.

spd_free

(void* pAddress)

Frees memory allocated by the ScreenPro Direct API.

spd_get_license_variant

(spdInstanceId id, uint64_t* licenseVariant)

Returns the variant of the license used to run ScreenPro Direct. If the 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).

spd_get_pipeline_status

(spdInstanceId id, char* result, uint64_t* pResultLength)

Returns a string encoding the current pipeline status in result . The length of the required string is returned in *pResultLength .

spd_get_print_run_status

(spdInstanceId id, PrintRunStatus* result)

Returns a structure summarizing the status of the currently active print run.

spd_get_sheet_counter

(spdInstanceId id, uint64_t* sheetCounter)

Returns the total number of sheets ever printed by ScreenPro Direct in *sheetCounter .

spd_get_version

(spdInstanceId id, uint64_t* major, uint64_t* minor, uint64_t* revision, uint64_t* build)

Gets the version number of the connected ScreenPro Direct instance.

spd_idle

(spdInstanceId id)

Returns ScreenPro Direct to idle state after ending a print run.

spd_pause_print_run

(spdInstanceId id)

Pauses a print run.

spd_reconnect

(spdInstanceId id)

Reconnects to the ScreenPro Direct instance with ID id .

spd_register_job_cancelled_handler

(spd_job_cancelled_handler job_cancelled_handler, void* priv)

Registers job_cancelled_handler to be called when ScreenProDirect cancels a job. Client data can be passed via the priv parameter.

spd_register_job_failed_handler

(spd_job_failed_handler job_failed_handler, void* priv)

Registers job_failed_handler to be called when ScreenProDirect finishes a job unsuccessfully. Client data can be passed via the priv parameter.

spd_register_job_started_handler

(spd_job_started_handler job_started_handler, void* priv)

Registers job_started_handler to be called when ScreenPro Direct starts a job. Client data can be passed via the priv parameter.

spd_register_job_succeeded_handler

(spd_job_succeeded_handler job_succeeded_handler, void* priv)

Registers job_succeeded_handler to be called when ScreenPro Direct successfully finishes a job. Client data can be passed via the priv parameter.

spd_reset_sheet_counter

(spdInstanceId id)

Resets the total number of sheets ever printed by ScreenPro Direct.

spd_resume_print_run

(spdInstanceId id)

Resumes a print run from paused.

spd_send_background_image

(spdInstanceId id, const char* filePath, uint64_t copyCount, uint64_t planeNumber, bool finalPlane)

Sends an image to be used as a static background. Used in Variable Data Printing when a foreground is to be overlaid.

spd_send_blank_image

(spdInstanceId id, uint64_t width, uint64_t height, uint64_t bpp, uint64_t planeNumber)

Sends a blank image with the given dimensions to be screened.

spd_send_heartbeat

(spdInstanceId id)

Sends a heartbeat signal to the ScreenPro Direct instance with ID id .

spd_send_image

(spdInstanceId id, const char* filePath, uint64_t copyCount, const SPD_TaskID* taskId)

Sends a TIFF or XML file for screening. The taskId is an input parameter that cannot be null. It may have Job ID or Image ID equal to zero, in which case the defaults from ScreenPro Direct are used. If the plane number is zero, the value set in the configuration file is used.

spd_send_preload_image

(spdInstanceId id, const char* filePath, uint64_t copyCount, uint64_t planeNumber, bool finalPlane)

Sends an image to be preloaded.

spd_set_config_param

(spdInstanceId id, const char* section, const char* key, const char* value)

Sets the value of a configuration parameter, overwriting the previous value if already set. Can only be called when no print run is active.

spd_set_cross_web_offset

(spdInstanceId id, uint64_t value, uint64_t planeNumber)

Sets the offset on the web (in nozzles) where the image should be printed.

spd_set_hardware_parameter

(spdInstanceId id, uint64_t parameterId, uint64_t controllerNumber, uint64_t headNumber, uint64_t value)

Sets a hardware parameter.

spd_set_hardware_parameter_ex

(spdInstanceId id, uint64_t parameterId, uint64_t controllerNumber, uint64_t headControllerNumber, uint64_t headNumber, uint64_t jettingAssemblyNumber, uint64_t value)

Sets a hardware parameter.

spd_set_hardware_signal

(spdInstanceId id, uint64_t signalId, uint64_t controllerNumber, uint64_t headNumber, uint64_t value)

Sends a signal to the hardware.

spd_set_job_config

(spdInstanceId id, uint64_t jobId, const char* config)

Sets a custom job configuration option. Reserved.

spd_set_job_id

(spdInstanceId id, uint64_t jobId)

Starts a new job in ScreenProDirect with ID jobId . For use with the Shared Memory Interface.

spd_set_last_page

(spdInstanceId id, uint64_t jobId, uint64_t lastPage)

Sets the number of the last separation in the given job.

spd_set_print_flat_credentials

(const char* oemId)

Sets the oemId for PrintFlat. This must be called before starting a print run so that your credentials can be checked against calibrations/linearizations used by your screen. If the details are incorrect and do not match the screen to be used, the call to spd_start_print_run fails; ScreenPro Direct will need to be shut down and restarted before the correct PrintFlat credentials are accepted.

spd_set_sheet_number_offset(spdInstanceId id, uint64_t jobId, uint64_t offset)Sets the sheet number offset for the given job. For use with the Sheet Numbering plugin when submitting a job with multiple copies.

spd_shutdown

()

Shuts down the ScreenPro Direct API. Make no further calls to API functions after this.

spd_start_print_run

(spdInstanceId id)

Starts a print run.

spd_startup

(const SocketConfiguration* socketConfig, uint64_t socketConfigCount, spd_print_run_event_handler printRunEventHandler, void* priv, const char* licensePassword)

Initializes the ScreenPro Direct API:

  • Connects to the ScreenPro Direct instances given in the socketConfig array.
  • Registers printRunEventHandler to be called print run event occurs. Client data can be passed via the priv parameter.
  • Stores licensePassword for validation when a print run is started.

spd_turn_off_head_power

(spdInstanceId id)

Turns off power to the print heads.

spd_turn_on_head_power

(spdInstanceId id)

Turns on power to the print heads.

spd_run_plugin_command(spdInstanceId 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 will update the length to the required length - so a second call can be made.

Example code

The following code snippets showcase what you can do with the ScreenPro Direct API. There are more examples in the ScreenProDirect_API_Example.cpp file that is provided with ScreenPro Direct. All code below assumes you have already launched a ScreenPro Direct instance.

The first code snippet demonstrates how to initialize the ScreenPro Direct API. A SocketConfiguration object is required to connect to the running ScreenPro Direct instance. Notice how the client data passed to spd_startup  is passed back to and re-cast in the printRunEventHandler function.

std::string screenProPassword;

struct LocalContext
{
   // details omitted...
} localContext;

void printRunEventHandler(spdInstanceId id, SPD_PrintRunEventCode code, void* priv)
{
    auto& context = *reinterpret_cast<LocalContext*>(priv)
    // do stuff with the LocalContext and Event data
    // details omitted...
}

auto socketConfigurations = std::vector<SocketConfiguration>
{
    {
        1, // ID to assign to the ScreenProDirect instance.
        "127.0.0.1", // IP Address
        9099, // Port number for command socket
        9098, // Port number for status socket
		1000, // Acknowledgment timeout in milliseconds
		30000, // Result timeout in milliseconds
    }
};

if (spd_startup(socketConfigurations.data(), socketConfigurations.size(), &printRunEventHandler, &localContext, screenProPassword.c_str()) != 0 || spd_check_init() != 0)
{
    std::cout << "spd_startup() failed" << std::endl;
    return 1;
}
CODE

The next example shows how to start a print run and send an image for screening. Note how both API methods require a ScreenPro Direct Instance ID.

    if (spd_start_print_run(1) != 0)
    {
        std::cout << "spd_start_print_run() failed" << std::endl;
        return 1;
    }

    auto const tiffFile = "MyTiffFile.tif"s;
    auto constexpr copyCount = 1;
    auto constexpr taskId_plane0 = SPD_TaskID{ 0, 0, 0 }; // Use all zeroes to get default numbering.
    if (spd_send_image(1, tiffFile.c_str(), copyCount, &taskId_plane0) != 0)
    {
        std::cout << "spd_send_image() failed" << std::endl;
        return 1;
    }
CPP

Lastly, this code shows how to shutdown the API.

if (spd_shutdown() != 0)
{
    std::cout << "spd_shutdown() failed" << std::endl;
    return 1;
}
CPP