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.