Harlequin RIP SDK
sw_timeline_api_20110623 Struct Reference

Timeline API struct for version 20110623. More...

#include "timelineapi.h"

Data Fields

HqBool valid
 
sw_tl_ref(* start )(sw_tl_type, sw_tl_ref, sw_tl_extent, sw_tl_extent, sw_tl_unit, sw_tl_priority, void *, const uint8 *, size_t)
 Create a Timeline, issuing a Start Event immediately. More...
 
sw_tl_result(* end )(sw_tl_ref)
 Potentially end a Timeline. More...
 
sw_tl_result(* abort )(sw_tl_ref, int)
 Potentially abort a Timeline. More...
 
sw_tl_result(* set_title )(sw_tl_ref, const uint8 *, size_t)
 Change the title of a Timeline. Issues an Event before changing the title. More...
 
size_t(* get_title )(sw_tl_ref, uint8 *, size_t)
 Return the Timeline's title and length. More...
 
sw_tl_result(* set_extent )(sw_tl_ref, sw_tl_extent, sw_tl_extent)
 Extend the length of the Timeline. Issues an Event for a nonzero change. More...
 
sw_tl_result(* set_progress )(sw_tl_ref, sw_tl_extent)
 Update the progress of the Timeline, in the units given when the Timeline was started. Issues an Event if the current value changes. More...
 
sw_tl_result(* get_progress )(sw_tl_ref, sw_tl_extent *, sw_tl_extent *, sw_tl_extent *, sw_tl_unit *)
 Return the extent, unit and progress through a Timeline. More...
 
sw_tl_ref(* get_ancestor )(sw_tl_ref, sw_tl_type)
 Return the nearest ancestor of the Timeline of the specified type. More...
 
sw_tl_type(* get_type )(sw_tl_ref)
 Return the Timeline type if known. More...
 
sw_tl_result(* set_context )(sw_tl_ref, sw_tl_context, void *)
 Attach a secondary context to a Timeline. More...
 
void *(* get_context )(sw_tl_ref, sw_tl_context)
 Return a context from the Timeline. More...
 
sw_tl_priority(* get_priority )(sw_tl_ref)
 Return the Timeline priority if known. More...
 
sw_tl_ref(* of_type )(sw_tl_ref, sw_tl_type)
 Ensure the Timeline or an ancestor is of the given type. More...
 

Detailed Description

Timeline API struct for version 20110623.

Deprecated:
This version of the API is deprecated. Use sw_timeline_api_20170413 instead.

Field Documentation

◆ abort

sw_tl_result( * sw_timeline_api_20110623::abort) (sw_tl_ref, int)

Potentially abort a Timeline.

Whether the Timeline Abort Event is issued immediately depends on whether there are ongoing descendant Timelines of the same or higher priority, whether the timeline was created with the sw_tl_options::can_prolong option SW_TL_PROLONG_TRUE, and whether any event handlers objected to aborting the timeline.

Parameters
refTimeline reference to abort
reasonA reason code for the abort, defined per Timeline type
Return values
SW_TL_SUCCESSif the Timeline has ended
SW_TL_ERROR_UNKNOWNif the Timeline is not known
SW_TL_ERROR_IN_USEif the Timeline is being kept alive by an event Handler
SW_TL_ERROR_SYNTAXif an event handler incorrectly tries to end a timeline from the same thread that a descendent is already ending or aborting it, potentially causing a deadlock. This is a programming error, and will also cause an assert.

SwTimelineAbort() will only return SW_TL_SUCCESS when the timeline has been ended or aborted, and all of the timeline and its descendents' have been the subject of EVENT_TIMELINE_ABORTED or EVENT_TIMELINE_ENDED events.

SwTimelineAbort() will only return SW_TL_ERROR_IN_USE if the timeline was created with the sw_tl_options::can_prolong option SW_TL_PROLONG_TRUE.

If there are priority inversions in the descendent hierarchy, or a timeline in the descendent hierarchy is prolonged using an event handler objection, the thread calling SwTimelineEnd() may be blocked waiting for a descendent to end. It is the programmer's responsibility to ensure that all priority inversions and objections are handled, by ending or aborting higher priority children explicitly, and by removing event handler objections.

Note that if SW_TL_ERROR_IN_USE is returned, the timeline is being prolonged by an event handler. It is the event handler's responsibility to remove the objection at a suitable point, and also to delegate calling of SwTimelineEnd() or SwTimelineAbort() on the timeline. Failing to remove the objection or end or abort the timeline may result in threads being blocked indefinitely.

If SW_TL_ERROR_IN_USE is returned, it also means that the attached primary context must also continue to exist. For such contexts that must be discarded, it may be best to discard them in a default priority EVENT_TIMELINE_ABORTED Handler for that Timeline reference.

◆ end

sw_tl_result( * sw_timeline_api_20110623::end) (sw_tl_ref)

Potentially end a Timeline.

Whether the Timeline End Event is issued immediately depends on whether there are ongoing descendant Timelines of the same or higher priority, whether the timeline was created with the sw_tl_options::can_prolong option SW_TL_PROLONG_TRUE, and whether any event handlers objected to ending the timeline.

Parameters
refTimeline reference to end
Return values
SW_TL_SUCCESSif the Timeline has ended
SW_TL_ERROR_UNKNOWNif the Timeline is not known
SW_TL_ERROR_IN_USEif the Timeline is being kept alive by an event handler
SW_TL_ERROR_SYNTAXif an event handler incorrectly tries to end a timeline from the same thread that a descendent is already ending or aborting it, potentially causing a deadlock. This is a programming error, and will also cause an assert.

SwTimelineEnd() will only return SW_TL_SUCCESS when the timeline has been ended or aborted, and all of the timeline and its descendents have been the subject of EVENT_TIMELINE_ENDED or EVENT_TIMELINE_ABORTED events.

SwTimelineEnd() will only return SW_TL_ERROR_IN_USE if the timeline was created with the sw_tl_options::can_prolong option SW_TL_PROLONG_TRUE.

If there are priority inversions in the descendent hierarchy, or a timeline in the descendent hierarchy is prolonged using an event handler objection, the thread calling SwTimelineEnd() may be blocked waiting for a descendent to end. It is the programmer's responsibility to ensure that all priority inversions and objections are handled, by ending or aborting higher priority children explicitly, and by removing event handler objections.

Note that if SW_TL_ERROR_IN_USE is returned, the timeline is being prolonged by an event handler. It is the event handler's responsibility to remove the objection at a suitable point, and also to delegate calling of SwTimelineEnd() or SwTimelineAbort() on the timeline. Failing to remove the objection or end or abort the timeline may result in threads being blocked indefinitely.

If SW_TL_ERROR_IN_USE is returned, it also means that the attached primary context must also continue to exist. For such contexts that must be discarded, it may be best to discard them in a default priority EVENT_TIMELINE_ABORTED Handler for that Timeline reference.

◆ get_ancestor

sw_tl_ref( * sw_timeline_api_20110623::get_ancestor) (sw_tl_ref, sw_tl_type)

Return the nearest ancestor of the Timeline of the specified type.

Parameters
refTimeline reference
typeType of ancestor to find, or SW_TL_TYPE_ANY to find immediate parent.
Returns
The Timeline reference of the ancestor, or SW_TL_REF_INVALID there is no ancestor of type.

This can be used to find the immediate parent of a Timeline, if it has one, or to find a Timeline's ancestor of a particular known type.

This allows something that cares about Job Timelines, for example, to find out whether a particular message Event belongs to its job. Note however that it may in principle be possible for there to be multiple nested Job Timelines, so the first Job parent found may itself be a child of the Job Timeline in question.

This call does not issue an Event.

◆ get_context

void*( * sw_timeline_api_20110623::get_context) (sw_tl_ref, sw_tl_context)

Return a context from the Timeline.

Parameters
refTimeline reference
[in]idUnique identifier for context. Zero for Timeline creator's primary context
Returns
The pointer registered with that identifier, or NULL if there is no relevant context attached.

The Timeline system places no interpretation on these contexts, they are for client use. Note that NULL is returned if the Timeline reference or context id is not known.

This call does not issue an Event.

◆ get_priority

sw_tl_priority( * sw_timeline_api_20110623::get_priority) (sw_tl_ref)

Return the Timeline priority if known.

Parameters
refTimeline reference
Returns
The priority of the Timeline if known, or SW_TL_PRIORITY_UNKNOWN if the reference is invalid.

This call does not issue an Event.

◆ get_progress

sw_tl_result( * sw_timeline_api_20110623::get_progress) (sw_tl_ref, sw_tl_extent *, sw_tl_extent *, sw_tl_extent *, sw_tl_unit *)

Return the extent, unit and progress through a Timeline.

Parameters
refTimeline reference
[out]startIf not null, this is filled in with the extent start
[out]endIf not null, this is filled in with the extent end
[out]progressIf not null, this is filled in with the progress
[out]unitIf not null, this is filled in with the unit
Return values
SW_TL_SUCCESSnormally
SW_TL_ERROR_UNKNOWNif the Timeline is not known

An extent end of SW_TL_EXTENT_INDETERMINATE means the Timeline is not of a known length. The progress and unit may still be informational.

This call does not issue an Event.

◆ get_title

size_t( * sw_timeline_api_20110623::get_title) (sw_tl_ref, uint8 *, size_t)

Return the Timeline's title and length.

Parameters
refTimeline reference
[out]bufferIf not null, this is filled in with the title, space permitting
sizeThe size of the supplied buffer
Returns
The actual length of the title

This call allows the Timeline's title to be retrieved. It can be called with a null buffer pointer to find the length of the title so a suitable buffer can be allocated before calling this function again, but be prepared for the title to be changed by another thread between the calls.

If the returned title length is greater than the buffer size passed in, the title returned will have been truncated.

This call does not issue an Event.

◆ get_type

sw_tl_type( * sw_timeline_api_20110623::get_type) (sw_tl_ref)

Return the Timeline type if known.

Parameters
refTimeline reference
Returns
The type of the Timeline if known, or SW_TL_TYPE_NONE if the reference is invalid.

This call does not issue an Event.

◆ of_type

sw_tl_ref( * sw_timeline_api_20110623::of_type) (sw_tl_ref, sw_tl_type)

Ensure the Timeline or an ancestor is of the given type.

Parameters
refTimeline reference
typeType of Timeline to find
Returns
The Timeline reference of type, or SW_TL_REF_INVALID

This is similar to SwTimelineGetAncestor(), but can return the Timeline passed in and does not accept SW_TL_TYPE_ANY as a parameter.

If the Timeline passed in and none of its ancestors are of the required type, SW_TL_REF_INVALID is returned.

It is equivalent to an atomic version of:

type = SwTimelineGetType(ref) ;
if (type == SW_TL_TYPE_NONE)
else if (type != requiredType)
ref = SwTimelineGetAncestor(ref, requiredType) ;
sw_tl_ref SwTimelineGetAncestor(sw_tl_ref ref, sw_tl_type type)
Return the nearest ancestor of the Timeline of the specified type.
sw_tl_type SwTimelineGetType(sw_tl_ref ref)
Return the Timeline type if known.
@ SW_TL_TYPE_NONE
Definition: timelineapi.h:700
@ SW_TL_REF_INVALID
Definition: timelineapi.h:530

This call does not issue an Event.

◆ set_context

sw_tl_result( * sw_timeline_api_20110623::set_context) (sw_tl_ref, sw_tl_context, void *)

Attach a secondary context to a Timeline.

Parameters
refTimeline reference
idUnique identifier for context.
[in]contextThe context pointer to attach to the Timeline, or null
Return values
SW_TL_SUCCESSThe context was attached to the timeline.
SW_TL_ERROR_UNKNOWNIf the Timeline is not known
SW_TL_ERROR_SYNTAXIf an attempt was made to change the owner context (identifier zero).
SW_TL_ERROR_MEMORYIf memory allocation fails

The Timeline system places no interpretation on these contexts, they are for client use. Context management is not performed by the Timeline system, and these contexts can only be retrieved using this call while the Timeline continues to exist.

Note: Entities that wish to associate a context with a Timeline that will outlive the Timeline itself should register the context with RDR using a Class of RDR_CLASS_TIMELINE, the Timeline reference as the RDR Type, and their context identifier as the RDR ID. Such an RDR will have to be manually deregistered when the Timeline ends (though not necessarily immediately).

This call does not issue an Event.

◆ set_extent

sw_tl_result( * sw_timeline_api_20110623::set_extent) (sw_tl_ref, sw_tl_extent, sw_tl_extent)

Extend the length of the Timeline. Issues an Event for a nonzero change.

Parameters
refTimeline reference
startNew start of the Timeline extent
endNew end of the Timeline extent, or SW_TL_EXTENT_INDETERMINATE
Return values
SW_TL_SUCCESSnormally
SW_TL_ERROR_UNKNOWNif the Timeline is not known

A Timeline created with an end of SW_TL_EXTENT_INDETERMINATE should not be represented by a GUI as having a known length.

An EVENT_TIMELINE_EXTEND event will be issued. The Timeline system ignores the return code from this event.

Timeline extents can have the start value greater than the end value, for example to represent a countdown timer or remaining resource items. The caller can determine if this is the case by comparing the extent boundaries returned by SwTimelineGetProgress().

If the timeline was originally created with the sw_tl_options::progress_monotonic option TRUE, then the extents can only be increased if the original extent order was positive, or decreased if the original extent order was negative.

◆ set_progress

sw_tl_result( * sw_timeline_api_20110623::set_progress) (sw_tl_ref, sw_tl_extent)

Update the progress of the Timeline, in the units given when the Timeline was started. Issues an Event if the current value changes.

Parameters
refTimeline reference
progressCurrent progress value.
Return values
SW_TL_SUCCESSnormally
SW_TL_ERROR_UNKNOWNif the Timeline is not known

If the timeline was created with the sw_tl_options::progress_monotonic option TRUE, then retrograde progress updates will be silently ignored, and an event will not be issued.

If the timeline was created with the default options, then progressing beyond the current Timeline extent automatically extends the extent. If the timeline was created with the sw_tl_options::progress_clamped option TRUE, then attempts to progress beyond the extent will be clamped. If the progress is already at the timeline extent, then an event will not be issued.

A Handler may choose to reflect the progress of a child Timeline in the parent Timeline, eg by reducing the parent's extent start by some amount, and then updating the parent's progress accordingly.

An EVENT_TIMELINE_PROGRESS event is issued. The Timeline system ignores the return code from this event.

◆ set_title

sw_tl_result( * sw_timeline_api_20110623::set_title) (sw_tl_ref, const uint8 *, size_t)

Change the title of a Timeline. Issues an Event before changing the title.

Parameters
refTimeline reference to rename
[in]titlePointer to a string, or null to remove the name
lengthLength of the unterminated string
Return values
SW_TL_SUCCESSnormally
SW_TL_ERROR_UNKNOWNif the Timeline is not known
SW_TL_ERROR_MEMORYif memory allocation fails

The title will be copied so does not need to be maintained.

An EVENT_TIMELINE_TITLE event is issued. A Handler may choose to modify the title or suppress it by changing the pointer and length in the Event Message. If a Handler returns SW_EVENT_HANDLED, no title change occurs at all.

◆ start

sw_tl_ref( * sw_timeline_api_20110623::start) (sw_tl_type, sw_tl_ref, sw_tl_extent, sw_tl_extent, sw_tl_unit, sw_tl_priority, void *, const uint8 *, size_t)

Create a Timeline, issuing a Start Event immediately.

Parameters
typeTimeline type, such as Job, Document, Interpret, Render
parentID of parent Timeline, or SW_TL_REF_INVALID for an autonomous Timeline
startStart of the Timeline extent in some units, eg total bytes, number of pages. Often zero.
endEnd of the Timeline extent, or SW_TL_EXTENT_INDETERMINATE
unitUnit of the above extent, eg Bytes, Pages, Lines
priorityUsed to resolve Ending a Timeline with ongoing child Timelines
[in]contextThe primary context supplied by the Timeline owner
[in]titleA title for the Timeline. Could be leafname, page title or job phase
lengthThe length of the title
Returns
The new Timeline reference or SW_TL_REF_INVALID if it fails.

The timeline created has the default options (no negotiation, non-monotonic progress, no progress limiting). If a timeline is desired with non-default options, call SwTimelineStartEx() instead.

A Timeline that has no concept of length, for which progress has no real meaning, should have an extent end of SW_TL_EXTENT_INDETERMINATE. A GUI may represent this as an indeterminate progress bar instead of a standard progress bar.

A EVENT_TIMELINE_START event is issued immediately after creating the Timeline. If a Handler returns SW_EVENT_HANDLED the Timeline is immediately ended and SW_TL_REF_INVALID will be returned to the creator.

See SwTimelineEnd() for usage of the priority parameter.

The title is copied so need not be maintained.

The supplied context is delivered in Timeline Events and is identified by context id zero. It can be retrieved with SwTimelineGetContext() but cannot be changed - Timeline events can occur at any time and in other threads, so changing this primary context would invalidate events currently in flow.

◆ valid

HqBool sw_timeline_api_20110623::valid

Is this API initialized?


The documentation for this struct was generated from the following file: