Harlequin RIP SDK
Files | Typedefs | Enumerations | Functions
Hot folder support
Harlequin RIP SDK

Hot folder support. More...

Files

file  hotfolder.h
 Hot folder implementation.
 
file  hotfoldererrors.h
 Header file defining the hotfolder result translation.
 
file  pnotify.c
 Implementation of the skinkit file change notification interfaces, in terms of the Microsoft Windows API.
 
file  hotfolder.c
 Hot folder implementation.
 
file  hotfolderprv.h
 Hot folder skinkit private API.
 
file  pnotify.h
 API for platform implementations of directory and file change notification.
 

Typedefs

typedef HqnResult hotfolder_result
 Status return type for API calls. More...
 

Enumerations

enum  HOTFOLDER_RESULT {
  HOTFOLDER_SUCCESS = HQN_RESULT_SUCCESS , HOTFOLDER_ERROR , HOTFOLDER_ERROR_MEMORY , HOTFOLDER_ERROR_PARAMS ,
  HOTFOLDER_ERROR_MISSING , HOTFOLDER_ERROR_DELETE , HOTFOLDER_ERROR_NAME
}
 Return type for hotfolder monitoring calls. More...
 

Functions

hotfolder_result hotfolder_monitor (const uint8 *directory, const uint8 *setupname, const uint8 *overrideps, uint32 rescan_ms, uint32 stabilise_ms, HqBool append, sw_inputq_mkcontext_fn *mkcontext, void *mkdata)
 Add a hot folder for monitoring, along with a configuration that will be used to submit jobs to the input queue. More...
 
hotfolder_result hotfolder_unmonitor (const uint8 *directory)
 Remove a hot folder from monitoring. More...
 
static HqnResult hotfolder_result_translate (hotfolder_result result)
 Translate a hotfolder-specific error code to a generic HqnResult error code. More...
 

Detailed Description

Hot folder support.

This is the Harlequin SDK library's implementation of a hot folder monitor. The hot folder monitor watches one or more directories for new files, monitors them until they stabilize, then uses the input queue API to submit jobs to the RIP, monitors the jobs for completion, and then deletes the jobs from the hot folder.

The hotfolder_monitor() function is used to add a directory to monitor for jobs. The hotfolder_unmonitor() function is used to stop monitoring a directory.

Each hot folder can have its own configuration and override associated with it, and a different scanning and stabilization period. This may be useful for jobs submitted over network links, where the rate of change when copying a job is not as fast as a local filesystem.

The hotfolder_result_translate() function is used to convert hotfolder function results to HqnResult codes that can be used as RIP errors.

Typedef Documentation

◆ hotfolder_result

typedef HqnResult hotfolder_result

Status return type for API calls.

This is a subclass of HqnResult that also supports some specific extra error codes generated by the hotfolder (declared as the HOTFOLDER_RESULT enumeration). Before assigning to values of HqnResult type or any of its other subclasses, hotfolder_result values must be converted to change the API specific values to HQN_RESULT_SUCCESS or a monitor UID error code greater than MON_CLASS_ERROR. This can be done by including the file hotfoldererrors.h and calling the function hotfolder_result_translate().

Enumeration Type Documentation

◆ HOTFOLDER_RESULT

enum HOTFOLDER_RESULT

Return type for hotfolder monitoring calls.

Enumerator
HOTFOLDER_SUCCESS 

Normal return value.

HOTFOLDER_ERROR 

Unspecified error.

HOTFOLDER_ERROR_MEMORY 

Out of memory error.

HOTFOLDER_ERROR_PARAMS 

Invalid API parameters.

HOTFOLDER_ERROR_MISSING 

Hotfolder directory does not exist.

HOTFOLDER_ERROR_DELETE 

Failed to delete a completed job.

HOTFOLDER_ERROR_NAME 

Error in hotfolder directory name.

Function Documentation

◆ hotfolder_monitor()

hotfolder_result hotfolder_monitor ( const uint8 *  directory,
const uint8 *  setupname,
const uint8 *  overrideps,
uint32  rescan_ms,
uint32  stabilise_ms,
HqBool  append,
sw_inputq_mkcontext_fn *  mkcontext,
void *  mkdata 
)

Add a hot folder for monitoring, along with a configuration that will be used to submit jobs to the input queue.

Parameters
[in]directoryThe hot folder directory to monitor, as a platform path name. The directory must already exist.
[in]setupnameThe configuration name that will be submitted to the input queue API for newly stabilized files in the hot folder.
[in]overridepsAn optional buffer of PostScript that will be run after the setup when running jobs from the hot folder.
[in]rescan_msThe time, in milliseconds, between rescans of the hot folder. Setting this value to a lower number may result in more prompt response to new files in the hot folder, but will consume more processing time. Note that the hot folder implementation may use other techniques (such as file system change notification APIs) on some platforms to improve responsiveness. For such implementations, setting this value too low will consume processing time for no benefit. If this value is zero, a sensible default value will be chosen for the platform.
[in]stabilise_msThe time, in milliseconds, between rescans of a file that is not in a stable state. When a new file is detected by a hotfolder scan, it is marked as unstable, and this timeout is used to check for key aspects of the file changing. Setting this value to a lower number may result in more prompt response to completed file copies into the hot folder, but will consume more processing time. Note that the hot folder implementation may use other techniques (such as file system change notification APIs) on some platforms to improve responsiveness. For such implementations, setting this value too low will consume processing time for no benefit. If this value is zero, a sensible default value will be chosen for the platform.
[in]appendThis should be TRUE for normal hotfolders, where new items are added to the end of the input queue, giving first-in-first-out behaviour. If it is FALSE, the hotfolder will insert items at the head of the input queue, overriding all other input sources.
[in]mkcontextA function to construct job contexts suitable for passing to inputq_print_job() when submitting hotfolder jobs.
[in]mkdataA data pointer passed to the mkcontext job constructor function to create job contexts.
Returns
One of the HOTFOLDER_RESULT status codes. If HOTFOLDER_SUCCESS is returned, the directory is now being monitored, and existing and new files will be added to the input queue.

Note that if a hot folder monitor is started on a directory that already has files in it, the files will be added to the input queue as soon as the monitor determines they are stable.

◆ hotfolder_result_translate()

static HqnResult hotfolder_result_translate ( hotfolder_result  result)
inlinestatic

Translate a hotfolder-specific error code to a generic HqnResult error code.

Parameters
[in]resultOne of the HOTFOLDER_RESULT values, or an error value greater than MON_CLASS_ERROR.
Returns
Either HQN_RESULT_SUCCESS, or an error value greater than MON_CLASS_ERROR.

The header file defining this function should be included explicitly in every C or C++ file that calls it.

◆ hotfolder_unmonitor()

hotfolder_result hotfolder_unmonitor ( const uint8 *  directory)

Remove a hot folder from monitoring.

Parameters
[in]directoryThe hot folder directory to stop monitoring, as a platform path name. If this parameter is NULL, all hot folder monitors are removed.
Returns
One of the HOTFOLDER_RESULT status codes. If HOTFOLDER_SUCCESS is returned, the hot folder monitor was removed cleanly. If HOTFOLDER_ERROR_MISSING is returned, the hot folder was not being monitored. Other return values indicate errors cleaning up the hotfolder monitor (for example, deletions of completed files failed). If a hot folder monitor exists for the directory, it is destroyed regardless of the return value.