|
Harlequin RIP SDK
|
|
|
|
Harlequin RIP SDK
|
|
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... | |
Timeline API struct for version 20110623.
| 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.
| ref | Timeline reference to abort |
| reason | A reason code for the abort, defined per Timeline type |
| SW_TL_SUCCESS | if the Timeline has ended |
| SW_TL_ERROR_UNKNOWN | if the Timeline is not known |
| SW_TL_ERROR_IN_USE | if the Timeline is being kept alive by an event Handler |
| SW_TL_ERROR_SYNTAX | if 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.
| 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.
| ref | Timeline reference to end |
| SW_TL_SUCCESS | if the Timeline has ended |
| SW_TL_ERROR_UNKNOWN | if the Timeline is not known |
| SW_TL_ERROR_IN_USE | if the Timeline is being kept alive by an event handler |
| SW_TL_ERROR_SYNTAX | if 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.
| 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.
| ref | Timeline reference |
| type | Type of ancestor to find, or SW_TL_TYPE_ANY to find immediate parent. |
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.
| void*( * sw_timeline_api_20110623::get_context) (sw_tl_ref, sw_tl_context) |
Return a context from the Timeline.
| ref | Timeline reference | |
| [in] | id | Unique identifier for context. Zero for Timeline creator's primary context |
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.
| sw_tl_priority( * sw_timeline_api_20110623::get_priority) (sw_tl_ref) |
Return the Timeline priority if known.
| ref | Timeline reference |
This call does not issue an Event.
| 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.
| ref | Timeline reference | |
| [out] | start | If not null, this is filled in with the extent start |
| [out] | end | If not null, this is filled in with the extent end |
| [out] | progress | If not null, this is filled in with the progress |
| [out] | unit | If not null, this is filled in with the unit |
| SW_TL_SUCCESS | normally |
| SW_TL_ERROR_UNKNOWN | if 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.
Return the Timeline's title and length.
| ref | Timeline reference | |
| [out] | buffer | If not null, this is filled in with the title, space permitting |
| size | The size of the supplied buffer |
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.
| sw_tl_type( * sw_timeline_api_20110623::get_type) (sw_tl_ref) |
Return the Timeline type if known.
| ref | Timeline reference |
This call does not issue an Event.
| 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.
| ref | Timeline reference |
| type | Type of Timeline to find |
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:
This call does not issue an Event.
| sw_tl_result( * sw_timeline_api_20110623::set_context) (sw_tl_ref, sw_tl_context, void *) |
Attach a secondary context to a Timeline.
| ref | Timeline reference | |
| id | Unique identifier for context. | |
| [in] | context | The context pointer to attach to the Timeline, or null |
| SW_TL_SUCCESS | The context was attached to the timeline. |
| SW_TL_ERROR_UNKNOWN | If the Timeline is not known |
| SW_TL_ERROR_SYNTAX | If an attempt was made to change the owner context (identifier zero). |
| SW_TL_ERROR_MEMORY | If 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.
| 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.
| ref | Timeline reference |
| start | New start of the Timeline extent |
| end | New end of the Timeline extent, or SW_TL_EXTENT_INDETERMINATE |
| SW_TL_SUCCESS | normally |
| SW_TL_ERROR_UNKNOWN | if 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.
| 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.
| ref | Timeline reference |
| progress | Current progress value. |
| SW_TL_SUCCESS | normally |
| SW_TL_ERROR_UNKNOWN | if 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.
| 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.
| ref | Timeline reference to rename | |
| [in] | title | Pointer to a string, or null to remove the name |
| length | Length of the unterminated string |
| SW_TL_SUCCESS | normally |
| SW_TL_ERROR_UNKNOWN | if the Timeline is not known |
| SW_TL_ERROR_MEMORY | if 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.
| 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.
| type | Timeline type, such as Job, Document, Interpret, Render | |
| parent | ID of parent Timeline, or SW_TL_REF_INVALID for an autonomous Timeline | |
| start | Start of the Timeline extent in some units, eg total bytes, number of pages. Often zero. | |
| end | End of the Timeline extent, or SW_TL_EXTENT_INDETERMINATE | |
| unit | Unit of the above extent, eg Bytes, Pages, Lines | |
| priority | Used to resolve Ending a Timeline with ongoing child Timelines | |
| [in] | context | The primary context supplied by the Timeline owner |
| [in] | title | A title for the Timeline. Could be leafname, page title or job phase |
| length | The length of the title |
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.
| HqBool sw_timeline_api_20110623::valid |
Is this API initialized?