hvdevmon.h File Reference

eHVD event monitor and responder. More...

#include "std.h"
#include "rrevents.h"
#include "hvdlib.h"
#include "hvdcache.h"
#include "hvdtracker.h"
#include "swmemapi.h"

Data Structures
struct	HVD_monitor_params
	Parameters for the HVD monitor. More...

Macros
#define	HVD_MONITOR_PARAMS_INIT
	Default initialiser for HVD monitor params.

Typedefs
typedef struct HVD_monitor	HVD_monitor
	An opaque typedef for the HVD event monitor handle.
typedef HqBool()	HVD_connect_verify_fn(const uint8 *cache_id, void *data)
	Function type for verifying HVD connection. More...
typedef struct HVD_monitor_params	HVD_monitor_params
	Parameters for the HVD monitor.

Functions
HVD_result	HVD_monitor_start (const HVD_monitor_params *params, void *vprdr_api, HVD_monitor **ppMonitor)
	Create an HVD event monitor and register a connect event handler for a particular raster cache ID and PGB type. More...
void	HVD_monitor_finish (HVD_monitor **ppMonitor)
	Destroy an HVD cache monitor. More...
HqBool	HVD_monitor_connected (const HVD_monitor *monitor)
	Determine if an HVD monitor is currently connected. More...
HVD_result	HVD_monitor_add_raster (HVD_monitor *monitor, const uint8 id[16], unsigned int nExpected, void *hraster, size_t size)
	Inform the HVD cache that we are adding raster data to an HVD element. More...
void *	HVD_monitor_get_data (HVD_monitor *monitor, const uint8 id[16])
	Get the element data associated with an element. More...
void	HVD_monitor_get_ids (HVD_monitor *monitor, const uint8 **pCacheId, const uint8 **pSetupId)
	Get the cache and setup IDs for a connected HVD monitor. More...

Detailed Description

eHVD event monitor and responder.

The event monitor is responsible for capturing eHVD events, and calling libHVD tracker and cache functions to connect a producer of elements and pages to an element cache and output page compositor. This component will only be used if libHVD is built into a RIP or another process that uses RDR-based events (documented in Events system) to create variable data pages using eHVD elements and page definitions.

Typedef Documentation

HVD_connect_verify_fn

typedef HqBool() HVD_connect_verify_fn(const uint8 *cache_id, void *data)

Function type for verifying HVD connection.

Parameters

[in]	cache_id	A zero-terminated string indicating the OptimizedPDFCacheID that this connection was for.
[in]	data	The data supplied to HVD_monitor_start() by the creator for the purposes of verifying the connection.

Return values

TRUE	The HVD connection should be established.
FALSE	The HVD connection should not be established.

This function exists so that the creator of an HVD monitor can verify that the RIP is configured suitably for use with HVD. HVD is configured using the /OptimizedPDFCacheID PDF parameter. This function can be used to prevent confusion or corruption if the RIP output is not configured in a way that is not suitable for with the HVD cache specified.

Function Documentation

HVD_monitor_add_raster()

HVD_result HVD_monitor_add_raster	(	HVD_monitor *	monitor,
		const uint8	id[16],
		unsigned int	nExpected,
		void *	hraster,
		size_t	size
	)

Inform the HVD cache that we are adding raster data to an HVD element.

Parameters

[in]	monitor	The monitor returned by HVD_monitor_start().
[in]	id	The element ID to append the raster to.
[in]	nExpected	The total number of rasters that we expect to add for this element. In general, this number should be set on the first call of this function for an element, and the same value should be used for all calls on the same element thereafter. It is possible to revise the expected number downwards if some rasters are omitted, or upwards if more rasters are added, but it should never be less than the number of rasters added (including this one), and it should never be increased after all of the expected rasters have been received. When all of the rasters that are expected have been received, the element is marked as ready for use, and pages using this element may be output immediately.
[in]	hraster	A raster handle. This is used to identify the raster data when the page is output, or the element is destroyed.
[in]	size	The size of the raster data stored. This is counted against the cache limit.

Return values

HVD_SUCCESS	The raster handle was added to the element successfully. This was the final raster expected.
HVD_SUCCESS_INCOMPLETE	The raster handle was added to the element successfully. This was not the final raster expected.
HVD_ERROR_NO_ELEMENT	There was no element to add the raster to.
HVD_ERROR_EXCESS_RASTERS	The number of rasters is more than the number expected, including the raster currently being added.
HVD_ERROR_NO_MEMORY	The raster handle could not be added to the element, because the cache could not allocate memory.

Returns

Any other return value greater than MON_CLASS_ERROR is an error UID. The subclass, PS error type, and UID for the error can be deconstructed using the macros in monevent.h.

All elements expect to have at least one raster, and will not be marked as complete until nExpected rasters have been delivered.

If the return value is HVD_SUCCESS or HVD_SUCCESS_INCOMPLETE, the raster handle has been retained by the HVD element, and must remain valid until the HVD cache calls the raster release callback function with the handle. This will happen during the HVD disconnect call if rendering is aborted, or when the element is purged from the cache.

For any other return value, the caller should dispose of the raster data.

HVD_monitor_connected()

HqBool HVD_monitor_connected

(

const HVD_monitor *

monitor

)

Determine if an HVD monitor is currently connected.

Parameters

[in]

monitor

The monitor returned by HVD_monitor_start().

Return values

TRUE	This monitor is currently connected.
FALSE	This monitor is not connected.

HVD_monitor_finish()

void HVD_monitor_finish

(

HVD_monitor **

ppMonitor

)

Destroy an HVD cache monitor.

Parameters

[in,out]

ppMonitor

The address of the HVD monitor to destroy.

HVD_monitor_get_data()

void* HVD_monitor_get_data	(	HVD_monitor *	monitor,
		const uint8	id[16]
	)

Get the element data associated with an element.

Parameters

[in]	monitor	The monitor returned by HVD_monitor_start().
[in]	id	The element ID to get the data for.

Returns

The data attached to this element by the HVD_element_set_data().

HVD_monitor_get_ids()

void HVD_monitor_get_ids	(	HVD_monitor *	monitor,
		const uint8 **	pCacheId,
		const uint8 **	pSetupId
	)

Get the cache and setup IDs for a connected HVD monitor.

Parameters

[in]	monitor	The monitor returned by HVD_monitor_start().
[out]	pCacheId	A location to store the cache ID, or NULL if it should not be returned.
[out]	pSetupId	A location to store the setup ID, or NULL if it should not be returned.

This may be used for debug output, or to construct file or object names unique to the cache or its elements.

HVD_monitor_start()

HVD_result HVD_monitor_start	(	const HVD_monitor_params *	params,
		void *	vprdr_api,
		HVD_monitor **	ppMonitor
	)

Create an HVD event monitor and register a connect event handler for a particular raster cache ID and PGB type.

Parameters

[in]	params	The parameters for this HVD monitor.
[in]	vprdr_api	A pointer to the process's RDR API implementation.
[out]	ppMonitor	A location to store the HVD monitor created.

Return values

HVD_SUCCESS	The HVD event monitor created successfully, and a handle was stored in ppMonitor. If this function succeeds, HVD_monitor_finish() must be called to destroy it before the RIP shuts down. A handler for the SWEVT_RR_CONNECT has been registered for the cache ID specified.
HVD_ERROR_INVALID_PARAMS	The HVD monitor could not be created because the parameters were invalid.
HVD_ERROR_NO_MEMORY	The HVD monitor could not be created because of memory exhaustion.

Returns

Any other return value greater than MON_CLASS_ERROR is an error UID. The subclass, PS error type, and UID for the error can be deconstructed using the macros in monevent.h.