nl::Weave::System::Platform::Layer

Summary

Functions
`DidInit(Layer & aLayer, void *aContext, Error aStatus)`	`NL_DLL_EXPORT void` This is a platform-specific Weave System Layer post-initialization hook.
`DidShutdown(Layer & aLayer, void *aContext, Error aStatus)`	`NL_DLL_EXPORT void` This is a platform-specific Weave System Layer pre-shutdown hook.
`DispatchEvent(Layer & aLayer, void *aContext, Event aEvent)`	`NL_DLL_EXPORT Error` This is a platform-specific event / message dispatch hook.
`DispatchEvents(Layer & aLayer, void *aContext)`	`NL_DLL_EXPORT Error` This is a platform-specific event / message dispatch hook.
`GetClock_Monotonic(void)`	`uint64_t` Platform-specific function for getting monotonic system time in microseconds.
`GetClock_MonotonicHiRes(void)`	`uint64_t` Platform-specific function for getting high-resolution monotonic system time in microseconds.
`GetClock_MonotonicMS(void)`	`uint64_t` Platform-specific function for getting monotonic system time in milliseconds.
`GetClock_RealTime(uint64_t & curTime)`	`Error` Platform-specific function for getting the current real (civil) time in microsecond Unix time format.
`GetClock_RealTimeMS(uint64_t & curTimeMS)`	`Error` Platform-specific function for getting the current real (civil) time in millisecond Unix time format.
`PostEvent(Layer & aLayer, void *aContext, Object & aTarget, EventType aType, uintptr_t aArgument)`	`NL_DLL_EXPORT Error` This is a platform-specific event / message post hook.
`SetClock_RealTime(uint64_t newCurTime)`	`Error` Platform-specific function for setting the current real (civil) time.
`StartTimer(Layer & aLayer, void *aContext, uint32_t aMilliseconds)`	`NL_DLL_EXPORT Error` This is a platform-specific event / message dispatch hook.
`WillInit(Layer & aLayer, void *aContext)`	`NL_DLL_EXPORT Error` This is a platform-specific Weave System Layer pre-initialization hook.
`WillShutdown(Layer & aLayer, void *aContext)`	`NL_DLL_EXPORT Error` This is a platform-specific Weave System Layer pre-shutdown hook.

Functions

DidInit

NL_DLL_EXPORT void DidInit(
  Layer & aLayer,
  void *aContext,
  Error aStatus
)

This is a platform-specific Weave System Layer post-initialization hook.

This may be overridden by assserting the preprocessor definition, WEAVE_SYSTEM_CONFIG_PLATFORM_PROVIDES_XTOR_FUNCTIONS.

Details

Parameters

`[in,out] aLayer`	A reference to the Weave System Layer instance being initialized.
`[in,out] aContext`	Platform-specific context data passed to the layer initialization method, ::Init.
`[in] anError`	The overall status being returned via the Weave System Layer ::Init method.

DidShutdown

NL_DLL_EXPORT void DidShutdown(
  Layer & aLayer,
  void *aContext,
  Error aStatus
)

This is a platform-specific Weave System Layer pre-shutdown hook.

This may be overridden by assserting the preprocessor definition, WEAVE_SYSTEM_CONFIG_PLATFORM_PROVIDES_XTOR_FUNCTIONS.

Details

Parameters

`[in,out] aLayer`	A reference to the Weave System Layer instance being shutdown.
`[in,out] aContext`	Platform-specific context data passed to the layer initialization method, ::Shutdown.
`[in] anError`	The overall status being returned via the Weave System Layer ::Shutdown method.

Returns

WEAVE_SYSTEM_NO_ERROR on success; otherwise, a specific error indicating the reason for shutdown failure. Returning non-successful status will abort shutdown.

DispatchEvent

NL_DLL_EXPORT Error DispatchEvent(
  Layer & aLayer,
  void *aContext,
  Event aEvent
)

This is a platform-specific event / message dispatch hook.

This may be overridden by assserting the preprocessor definition, WEAVE_SYSTEM_CONFIG_PLATFORM_PROVIDES_EVENT_FUNCTIONS.

This dispatches the specified event for handling, unmarshalling the type and arguments from the event for hand off to Weave System Layer::HandleEvent for the actual dispatch.

Details

Parameters

`[in,out] aLayer`	A reference to the layer instance for which events / messages are being dispatched.
`[in,out] aContext`	Platform-specific context data passed to the layer initialization method, ::Init.
`[in] anEvent`	The platform-specific event object to dispatch for handling.

Return Values

`#WEAVE_SYSTEM_ERROR_BAD_ARGS`	If #aLayer or the event target is NULL.
`#WEAVE_SYSTEM_ERROR_UNEXPECTED_EVENT`	If the event type is unrecognized.
`#WEAVE_SYSTEM_ERROR_UNEXPECTED_STATE`	If the state of the Weave System Layer object is unexpected.
`WEAVE_SYSTEM_NO_ERROR`	On success.

DispatchEvents

NL_DLL_EXPORT Error DispatchEvents(
  Layer & aLayer,
  void *aContext
)

This is a platform-specific event / message dispatch hook.

This may be overridden by assserting the preprocessor definition, WEAVE_SYSTEM_CONFIG_PLATFORM_PROVIDES_EVENT_FUNCTIONS.

This effects an event loop, waiting on a queue that services this instance, pulling events off of that queue, and then dispatching them for handling.

Details

Parameters

`[in,out] aLayer`	A reference to the layer instance for which events / messages are being dispatched.
`[in,out] aContext`	Platform-specific context data passed to the layer initialization method, ::Init.

Return Values

`#WEAVE_SYSTEM_ERROR_BAD_ARGS`	If #aLayer or #aContext is NULL.
`#WEAVE_SYSTEM_ERROR_UNEXPECTED_STATE`	If the state of the Weave System Layer object is unexpected.
`#WEAVE_SYSTEM_ERROR_UNEXPECTED_EVENT`	If an event type is unrecognized.
`WEAVE_SYSTEM_NO_ERROR`	On success.

GetClock_Monotonic

uint64_t GetClock_Monotonic(
  void
)

Platform-specific function for getting monotonic system time in microseconds.

This function is expected to return elapsed time in microseconds since an arbitrary, platform-defined epoch. Platform implementations are obligated to return a value that is ever-increasing (i.e. never wraps) between reboots of the system. Additionally, the underlying time source is required to tick continuously during any system sleep modes that do not entail a restart upon wake.

The epoch for time returned by this function is not required to be the same that for any of the other GetClock... functions, including GetClock_MonotonicMS().

This function is expected to be thread-safe on any platform that employs threading.

Details
Returns	Elapsed time in microseconds since an arbitrary, platform-defined epoch.

GetClock_MonotonicHiRes

uint64_t GetClock_MonotonicHiRes(
  void
)

Platform-specific function for getting high-resolution monotonic system time in microseconds.

This function is expected to return elapsed time in microseconds since an arbitrary, platform-defined epoch. Values returned by GetClock_MonotonicHiRes() are required to be ever-increasing (i.e. never wrap). However, the underlying timer is not required to tick continuously during system deep-sleep states.

Platform are encouraged to implement GetClock_MonotonicHiRes() using a high-resolution timer that is not subject to gradual clock adjustments (slewing). On platforms without such a timer, GetClock_MonotonicHiRes() can return the same value as GetClock_Monotonic().

The epoch for time returned by this function is not required to be the same that for any of the other GetClock... functions.

This function is expected to be thread-safe on any platform that employs threading.

Details
Returns	Elapsed time in microseconds since an arbitrary, platform-defined epoch.

GetClock_MonotonicMS

uint64_t GetClock_MonotonicMS(
  void
)

Platform-specific function for getting monotonic system time in milliseconds.

This function is expected to return elapsed time in milliseconds since an arbitrary, platform-defined epoch. Platform implementations are obligated to return a value that is ever-increasing (i.e. never wraps) between reboots of the system. Additionally, the underlying time source is required to tick continuously during any system sleep modes that do not entail a restart upon wake.

The epoch for time returned by this function is not required to be the same as that for any of the other GetClock... functions, including GetClock_Monotonic().

This function is expected to be thread-safe on any platform that employs threading.

Details
Returns	Elapsed time in milliseconds since an arbitrary, platform-defined epoch.

GetClock_RealTime

Error GetClock_RealTime(
  uint64_t & curTime
)

Platform-specific function for getting the current real (civil) time in microsecond Unix time format.

This function is expected to return the local platform's notion of current real time, expressed as a Unix time value scaled to microseconds. The underlying clock is required to tick at a rate of least at whole seconds (values of 1,000,000), but may tick faster.

On those platforms that are capable of tracking real time, GetClock_RealTime() must return the error WEAVE_SYSTEM_ERROR_REAL_TIME_NOT_SYNCED whenever the system is unsynchronized with real time.

Platforms that are incapable of tracking real time should not implement the GetClock_RealTime() function, thereby forcing link-time failures of features that depend on access to real time. Alternatively, such platforms may supply an implementation of GetClock_RealTime() that returns the error WEAVE_SYSTEM_ERROR_NOT_SUPPORTED.

This function is expected to be thread-safe on any platform that employs threading.

Details

Parameters

[out] curTime

The current time, expressed as Unix time scaled to microseconds.

Return Values

`WEAVE_SYSTEM_NO_ERROR`	If the method succeeded.
`#WEAVE_SYSTEM_ERROR_REAL_TIME_NOT_SYNCED`	If the platform is capable of tracking real time, but is is currently unsynchronized.
`#WEAVE_SYSTEM_ERROR_NOT_SUPPORTED`	If the platform is incapable of tracking real time.

GetClock_RealTimeMS

Error GetClock_RealTimeMS(
  uint64_t & curTimeMS
)

Platform-specific function for getting the current real (civil) time in millisecond Unix time format.

This function is expected to return the local platform's notion of current real time, expressed as a Unix time value scaled to milliseconds.

See the documentation for GetClock_RealTime() for details on the expected behavior.

Details

Parameters

[out] curTime

The current time, expressed as Unix time scaled to milliseconds.

Return Values

`WEAVE_SYSTEM_NO_ERROR`	If the method succeeded.
`#WEAVE_SYSTEM_ERROR_REAL_TIME_NOT_SYNCED`	If the platform is capable of tracking real time, but is is currently unsynchronized.
`#WEAVE_SYSTEM_ERROR_NOT_SUPPORTED`	If the platform is incapable of tracking real time.

PostEvent

NL_DLL_EXPORT Error PostEvent(
  Layer & aLayer,
  void *aContext,
  Object & aTarget,
  EventType aType,
  uintptr_t aArgument
)

This is a platform-specific event / message post hook.

This may be overridden by assserting the preprocessor definition, WEAVE_SYSTEM_CONFIG_PLATFORM_PROVIDES_EVENT_FUNCTIONS.

This posts an event / message of the specified type with the provided argument to this instance's platform-specific event / message queue.

Details

Parameters

`[in,out] aLayer`	A pointer to the layer instance to which the event / message is being posted.
`[in,out] aContext`	Platform-specific context data passed to the layer initialization method, ::Init.
`[in,out] aTarget`	A pointer to the Weave System Layer object making the post request.
`[in] aType`	The type of event to post.
`[in,out] anArg`	The argument associated with the event to post.

Returns

WEAVE_SYSTEM_NO_ERROR on success; otherwise, a specific error indicating the reason for initialization failure.

SetClock_RealTime

Error SetClock_RealTime(
  uint64_t newCurTime
)

Platform-specific function for setting the current real (civil) time.

Weave calls this function to set the local platform's notion of current real time. The new current time is expressed as a Unix time value scaled to microseconds.

Once set, underlying platform clock is expected to track real time with a granularity of at least whole seconds.

On platforms that support tracking real time, the SetClock_RealTime() function must return the error WEAVE_SYSTEM_ERROR_ACCESS_DENIED if the calling application does not have the privilege to set the current time.

Platforms that are incapable of tracking real time, or do not offer the ability to set real time, should not implement the SetClock_RealTime() function, thereby forcing link-time failures of features that depend on setting real time. Alternatively, such platforms may supply an implementation of SetClock_RealTime() that returns the error WEAVE_SYSTEM_ERROR_NOT_SUPPORTED.

This function is expected to be thread-safe on any platform that employs threading.

Details

Parameters

[in] newCurTime

The new current time, expressed as Unix time scaled to microseconds.

Return Values

`WEAVE_SYSTEM_NO_ERROR`	If the method succeeded.
`#WEAVE_SYSTEM_ERROR_NOT_SUPPORTED`	If the platform is incapable of tracking real time.
`#WEAVE_SYSTEM_ERROR_ACCESS_DENIED`	If the calling application does not have the privilege to set the current time.

StartTimer

NL_DLL_EXPORT Error StartTimer(
  Layer & aLayer,
  void *aContext,
  uint32_t aMilliseconds
)

This is a platform-specific event / message dispatch hook.

This may be overridden by assserting the preprocessor definition, WEAVE_SYSTEM_CONFIG_PLATFORM_PROVIDES_EVENT_FUNCTIONS.

Details

Parameters

`[in,out] aLayer`	A reference to the layer instance for which events / messages are being dispatched.
`[in,out] aContext`	Platform-specific context data passed to the layer initialization method, ::Init.
`[in] aMilliseconds`	The number of milliseconds to set for the timer.

Return Values

WEAVE_SYSTEM_NO_ERROR

Always succeeds unless overridden.

WillInit

NL_DLL_EXPORT Error WillInit(
  Layer & aLayer,
  void *aContext
)

This is a platform-specific Weave System Layer pre-initialization hook.

This may be overridden by assserting the preprocessor definition, WEAVE_SYSTEM_CONFIG_PLATFORM_PROVIDES_XTOR_FUNCTIONS.

Details

Parameters

`[in,out] aLayer`	A reference to the Weave System Layer instance being initialized.
`[in,out] aContext`	Platform-specific context data passed to the layer initialization method, ::Init.

Returns

WEAVE_SYSTEM_NO_ERROR on success; otherwise, a specific error indicating the reason for initialization failure. Returning non-successful status will abort initialization.

WillShutdown

NL_DLL_EXPORT Error WillShutdown(
  Layer & aLayer,
  void *aContext
)

This is a platform-specific Weave System Layer pre-shutdown hook.

This may be overridden by assserting the preprocessor definition, WEAVE_SYSTEM_CONFIG_PLATFORM_PROVIDES_XTOR_FUNCTIONS.

Details

Parameters

`[in,out] aLayer`	A pointer to the Weave System Layer instance being shutdown.
`[in,out] aContext`	Platform-specific context data passed to the layer initialization method, ::Shutdown.

Returns

WEAVE_SYSTEM_NO_ERROR on success; otherwise, a specific error indicating the reason for shutdown failure. Returning non-successful status will abort shutdown.