Rtnl2OpenClock

Rtnl2OpenClock opens a clock object specified by the handle of the owning interface and the index of the clock within that interface.

Syntax

Copy

RTNL2_HCLOCK Rtnl2OpenClock(
    [in] RTNL2_HINTERFACE Interface, 
    [in] ULONG ClockIndex, 
    [in] ULONG Flags
);

Parameters

[in] Interface

The handle of the owning interface.

[in] ClockIndex

The clock index to open within the owning interface.

[in] Flags

A collection of flags that specify the clock’s expected usage:

Flag	Description
RTNL2_CLOCK_FLAG_PTM	This flag instructs the NL2 that all cross-timestamping operations performed by the clock must use PTM.
RTNL2_CLOCK_FLAG_MODIFY	This flag instructs the NL2 that this application intends to use the Clock handle to modify the clock by calling Rtnl2AdjustClockTime and/or Rtnl2SetClockRate.

Return Value

If the function succeeds, it returns a handle to the opened clock object. If the function fails, it returns NULL. Call GetLastError to obtain an error code.

Possible error codes:

Error code	Meaning
ERROR_NOT_READY	The calling process has not called Rtnl2Init.
ERROR_INVALID_PARAMETER	One of the following conditions occurred: The supplied Interface handle is invalid. The ClockIndex value doesn’t correspond to an existing clock.
RTNL2_ERROR_INCOMPATIBLE_REQUEST	The supplied Flags parameter is not the result of a bitwise OR operation between a set of the supported flags defined above. This may occur when the Runtime version doesn’t match the SDK version and cannot interpret the new flags it defines.
ERROR_RESOURCE_NOT_AVAILABLE	The calling process has already opened too many clock handles.
ERROR_ACCESS_DENIED	The RTNL2_CLOCK_FLAG_MODIFY flag was set, but the specified clock is already opened with that flag.
ERROR_DEVICE_FEATURE_NOT_SUPPORTED	One of the following conditions occurred: Hardware timestamping is not supported by the hardware. The RTNL2_CLOCK_FLAG_PTM flag was set, but PTM is not available on this hardware.
RTNL2_ERROR_TIMESTAMPING_NOT_CONFIGURED	Timestamping is not enabled.
RTNL2_ERROR_SERIALIZED_COMMAND_TIMEOUT	The NL2 process didn’t reply within an acceptable delay.
RTNL2_ERROR_NO_MORE_COMMUNICATION	Unable to communicate with the NL2 process. This might be because the NL2 process is no longer running, or because an application process thread was terminated during a previous call to an NL2 API function.

Remarks

A clock object can be opened multiple times by the same application process or multiple application processes. However, multiple instances of the same clock object cannot be opened with the RTNL2_CLOCK_FLAG_MODIFY flag at the same time

A clock handle must be closed with the Rtnl2CloseClock function when it is no longer needed.

Characteristics

Real-time
Deterministic	No
Shutdown-safe	No
Local memory usage
Process	External MSpace usage	Internal MSpace usage
System	No	No
NL2 process	No	No
Calling process	No	No
Windows contiguous memory usage
Usage	No

Requirements

Minimum supported version	Header	Library
wRTOS 1.0 SDK	Rtnl2Api.h	Rtnl2Api.lib