Version: 21 Aug 2024

ml_power_manager.h

Classes

	Name
struct	MLPowerManagerComponentProperty A structure to encapsulate the data for each MLPowerManagerPropertyType.
struct	MLPowerManagerPropertyData A structure to encapsulate output data when getting the current properties.
struct	MLPowerManagerPropertyTypeData A structure to encapsulate output data when getting a component's available property types.
struct	MLPowerManagerPropertyTypeInfo A structure to encapsulate information used by the Power Manager when getting the available property types.
struct	MLPowerManagerPropertyInfo A structure to encapsulate info data used by the Power Manager when getting the current properties.
struct	MLPowerManagerPowerStateSettings A structure to encapsulate settings used by the Power Manager when requesting the power state to be changed.
struct	MLPowerManagerPowerStateInfo A structure to encapsulate info data used by the Power Manager when getting the current power state.
struct	MLPowerManagerPowerStateData A structure to encapsulate output data when either getting available power states, or the current power state.
struct	MLPowerManagerCallbacks A structure containing Power Manager callback events. Individual callbacks which are not required by the Power Manager can be NULL.
union	MLPowerManagerComponentProperty.unnamed

Types

	Name
typedef struct MLPowerManagerComponentProperty	MLPowerManagerComponentProperty A structure to encapsulate the data for each MLPowerManagerPropertyType.
typedef struct MLPowerManagerPropertyData	MLPowerManagerPropertyData A structure to encapsulate output data when getting the current properties.
typedef struct MLPowerManagerPropertyTypeData	MLPowerManagerPropertyTypeData A structure to encapsulate output data when getting a component's available property types.
typedef struct MLPowerManagerPropertyTypeInfo	MLPowerManagerPropertyTypeInfo A structure to encapsulate information used by the Power Manager when getting the available property types.
typedef struct MLPowerManagerPropertyInfo	MLPowerManagerPropertyInfo A structure to encapsulate info data used by the Power Manager when getting the current properties.
typedef struct MLPowerManagerPowerStateSettings	MLPowerManagerPowerStateSettings A structure to encapsulate settings used by the Power Manager when requesting the power state to be changed.
typedef struct MLPowerManagerPowerStateInfo	MLPowerManagerPowerStateInfo A structure to encapsulate info data used by the Power Manager when getting the current power state.
typedef struct MLPowerManagerPowerStateData	MLPowerManagerPowerStateData A structure to encapsulate output data when either getting available power states, or the current power state.
typedef struct MLPowerManagerCallbacks	MLPowerManagerCallbacks A structure containing Power Manager callback events. Individual callbacks which are not required by the Power Manager can be NULL.

Enums

	Name
enum	Anonymous Enum 24 { MLResultAPIPrefix_PowerManager = ( 0x4c8a << 16) }
enum	MLPowerManagerResult { MLPowerManagerResult_NotConnected = MLResultAPIPrefix_PowerManager, MLPowerManagerResult_InvalidStateTransition, MLPowerManagerResult_StateTransitionsDisabled, MLPowerManagerResult_UnsupportedState, MLPowerManagerResult_Ensure32Bits = 0x7FFFFFFF } Power Manager specific return codes.
enum	MLPowerManagerComponent { MLPowerManagerComponent_None = 0, MLPowerManagerComponent_Controller = 1, MLPowerManagerComponent_Ensure32Bits = 0x7FFFFFFF } Represents the different components which can be accessed/controlled using the Power Manager.
enum	MLPowerManagerError { MLPowerManagerError_InvalidSKU = 0, MLPowerManagerError_Ensure32Bits = 0x7FFFFFFF } Power Manager error codes.
enum	MLPowerManagerPowerState { MLPowerManagerPowerState_None = 0, MLPowerManagerPowerState_Normal = 1, MLPowerManagerPowerState_DisabledWhileCharging = 2, MLPowerManagerPowerState_Standby = 3, MLPowerManagerPowerState_Sleep = 4, MLPowerManagerPowerState_Ensure32Bits = 0x7FFFFFFF } Power states. Query MLPowerManagerGetAvailablePowerStates() to determine which power state is available for each component.
enum	MLPowerManagerChargingState { MLPowerManagerChargingState_NotCharging = 0, MLPowerManagerChargingState_ChargingNormally = 1, MLPowerManagerChargingState_Ensure32Bits = 0x7FFFFFFF } Power Manager charging states.
enum	MLPowerManagerConnectionState { MLPowerManagerConnectionState_Connected = 0, MLPowerManagerConnectionState_Disconnected = 1, MLPowerManagerConnectionState_Ensure32Bits = 0x7FFFFFFF } Connection state of the component.
enum	MLPowerManagerBatteryInfo { MLPowerManagerBatteryInfo_OK = 0, MLPowerManagerBatteryInfo_BatteryLow = 1, MLPowerManagerBatteryInfo_BatteryCritical = 2, MLPowerManagerBatteryInfo_Ensure32Bits = 0x7FFFFFFF } Battery info/warning codes.
enum	MLPowerManagerPropertyType { MLPowerManagerPropertyType_BatteryInfo = 0, MLPowerManagerPropertyType_BatteryLevel = 1, MLPowerManagerPropertyType_ChargingState = 2, MLPowerManagerPropertyType_ConnectionState = 3, MLPowerManagerPropertyType_Ensure32Bits = 0x7FFFFFFF } Power Manager property types. Query MLPowerManagerGetAvailableProperties() to determine which Power Manager properties are available for each component.

Functions

	Name
void	MLPowerManagerPropertyTypeInfoInit(MLPowerManagerPropertyTypeInfo * inout_property_type_info) Initializes the default values for MLPowerManagerPropertyTypeInfo.
void	MLPowerManagerPropertyInfoInit(MLPowerManagerPropertyInfo * inout_property_info) Initializes the default values for MLPowerManagerPropertyInfo.
void	MLPowerManagerPowerStateSettingsInit(MLPowerManagerPowerStateSettings * inout_power_settings) Initializes the default values for MLPowerManagerPowerStateSettings.
void	MLPowerManagerPowerStateInfoInit(MLPowerManagerPowerStateInfo * inout_power_info) Initializes the default values for MLPowerManagerPowerStateInfo.
void	MLPowerManagerCallbacksInit(MLPowerManagerCallbacks * inout_cb) Initializes the default values for MLPowerManagerCallbacks.
MLResult	MLPowerManagerCreate(MLPowerManagerComponent component, MLHandle * out_handle) Creates a Power Manager handle for a specified component.
MLResult	MLPowerManagerDestroy(MLHandle handle) Destroys a Power Manager handle.
MLResult	MLPowerManagerSetCallbacks(MLHandle handle, MLPowerManagerCallbacks cb, void user_data) Register Power Manager callbacks for a specific handle.
MLResult	MLPowerManagerSetPowerState(MLHandle handle, const MLPowerManagerPowerStateSettings * settings) Sets the power state of a component. The new power state of a component will persist if the application loses focus, or exits.
MLResult	MLPowerManagerGetComponentProperties(MLHandle handle, const MLPowerManagerPropertyInfo in_info, MLPowerManagerPropertyData out_properties) Gets the power manager properties of a component.
MLResult	MLPowerManagerReleasePropertyData(MLHandle handle, MLPowerManagerPropertyData * properties) Releases specified MLPowerManagerPropertyData.
MLResult	MLPowerManagerGetAvailablePowerStates(MLHandle handle, const MLPowerManagerPowerStateInfo in_info, MLPowerManagerPowerStateData out_states) Query available power states for a component.
MLResult	MLPowerManagerGetPowerState(MLHandle handle, const MLPowerManagerPowerStateInfo in_info, MLPowerManagerPowerStateData out_state) Gets the power state of a component.
MLResult	MLPowerManagerReleasePowerStateData(MLHandle handle, MLPowerManagerPowerStateData * power_states) Releases specified MLPowerManagerPowerStateData.
MLResult	MLPowerManagerGetAvailableProperties(MLHandle handle, const MLPowerManagerPropertyTypeInfo in_info, MLPowerManagerPropertyTypeData out_properties) Request a list of the available MLPowerManagerPropertyType.
MLResult	MLPowerManagerReleasePropertyTypeData(MLHandle handle, MLPowerManagerPropertyTypeData * properties) Releases specified MLPowerManagerPropertyTypeData.
const char *	MLPowerManagerGetResultString(MLResult result_code) Returns an ASCII string for each result code.

Enums Documentation

Anonymous Enum 24

Enumerator	Value	Description
MLResultAPIPrefix_PowerManager	( 0x4c8a << 16)	Defines the prefix for Power Manager return codes.

MLPowerManagerResult

Enumerator	Value	Description
MLPowerManagerResult_NotConnected	MLResultAPIPrefix_PowerManager	Indicates the component is not connected.
MLPowerManagerResult_InvalidStateTransition		Indicates the component does not currently support transitioning to requested state.
MLPowerManagerResult_StateTransitionsDisabled		Indicates the component does not currently support transitioning to a different state.
MLPowerManagerResult_UnsupportedState		Indicates the component does not support the requested power state.
MLPowerManagerResult_Ensure32Bits	0x7FFFFFFF	Ensure enum is represented as 32 bits.

Power Manager specific return codes.

API Level:

MLPowerManagerComponent

Enumerator	Value	Description
MLPowerManagerComponent_None	0	Invalid or no component.
MLPowerManagerComponent_Controller	1	Controller.
MLPowerManagerComponent_Ensure32Bits	0x7FFFFFFF	Ensure enum is represented as 32 bits.

Represents the different components which can be accessed/controlled using the Power Manager.

API Level:

MLPowerManagerError

Enumerator	Value	Description
MLPowerManagerError_InvalidSKU	0	Controller component could not be connected due to Invalid SKU.
MLPowerManagerError_Ensure32Bits	0x7FFFFFFF	Ensure enum is represented as 32 bits.

Power Manager error codes.

API Level:

MLPowerManagerPowerState

Enumerator	Value	Description
MLPowerManagerPowerState_None	0	Invalid or no power state.
MLPowerManagerPowerState_Normal	1	Normal mode, this is the default or active state of the component.
MLPowerManagerPowerState_DisabledWhileCharging	2	Charging only mode. When charging component it cannot be used.
MLPowerManagerPowerState_Standby	3	Standby mode.
MLPowerManagerPowerState_Sleep	4	Sleep mode.
MLPowerManagerPowerState_Ensure32Bits	0x7FFFFFFF	Ensure enum is represented as 32 bits.

Power states. Query MLPowerManagerGetAvailablePowerStates() to determine which power state is available for each component.

Component	Power State	Description
Controller	Normal	Controller is active
Disabled While Charging	Certain SKUs cannot use controller while charging
Standby	Controller is turned on but inactive, press home button to switch to active manually
Sleep	Not supported for this component

API Level:

MLPowerManagerChargingState

Enumerator	Value	Description
MLPowerManagerChargingState_NotCharging	0	Not charging.
MLPowerManagerChargingState_ChargingNormally	1	Charging normally.
MLPowerManagerChargingState_Ensure32Bits	0x7FFFFFFF	Ensure enum is represented as 32 bits.

Power Manager charging states.

API Level:

MLPowerManagerConnectionState

Enumerator	Value	Description
MLPowerManagerConnectionState_Connected	0	Component is connected.
MLPowerManagerConnectionState_Disconnected	1	Component is disconnected.
MLPowerManagerConnectionState_Ensure32Bits	0x7FFFFFFF	Ensure enum is represented as 32 bits.

Connection state of the component.

API Level:

MLPowerManagerBatteryInfo

Enumerator	Value	Description
MLPowerManagerBatteryInfo_OK	0	No issues reported.
MLPowerManagerBatteryInfo_BatteryLow	1	Charge the component soon.
MLPowerManagerBatteryInfo_BatteryCritical	2	Charge the component immediately.
MLPowerManagerBatteryInfo_Ensure32Bits	0x7FFFFFFF	Ensure enum is represented as 32 bits.

Battery info/warning codes.

API Level:

MLPowerManagerPropertyType

Enumerator	Value	Description
MLPowerManagerPropertyType_BatteryInfo	0	Extra info about battery, as represented by MLPowerManagerBatteryInfo.
MLPowerManagerPropertyType_BatteryLevel	1	Battery level. Range is between 0 and 100.
MLPowerManagerPropertyType_ChargingState	2	Charging state.
MLPowerManagerPropertyType_ConnectionState	3	Connection state.
MLPowerManagerPropertyType_Ensure32Bits	0x7FFFFFFF	Ensure enum is represented as 32 bits.

Power Manager property types. Query MLPowerManagerGetAvailableProperties() to determine which Power Manager properties are available for each component.

API Level:

Types Documentation

MLPowerManagerComponentProperty

typedef struct MLPowerManagerComponentProperty MLPowerManagerComponentProperty;

A structure to encapsulate the data for each MLPowerManagerPropertyType.

This struct and union is used as a flexible way for each component to output an array containing distinct types of data.

The below code shows how a Controller could output battery_info, battery_level, charging_state or connection_state. Where data is an instance of MLPowerManagerPropertyData returned from MLPowerManagerGetComponentProperties.

auto properties = data.properties;
  for (int num = 0; num < data.size; num++) {
    switch (properties[num]->property_type) {
      case (MLPowerManagerPropertyType_BatteryInfo):
        // Process properties[num]->battery_info enum
        break;
      case (MLPowerManagerPropertyType_BatteryLevel):
        // Process properties[num]->battery_level as integer
        break;
      case (MLPowerManagerPropertyType_ChargingState):
        // Process properties[num]->charging_state as enum
        break;
      case (MLPowerManagerPropertyType_ConnectionState):
        // Process properties[num]->connection_state as enum
        break;
      default:
        // Error handle if default case
        break;
    }
  }

More Info

API Level:

MLPowerManagerPropertyData

typedef struct MLPowerManagerPropertyData MLPowerManagerPropertyData;

A structure to encapsulate output data when getting the current properties.

More Info

API Level:

MLPowerManagerPropertyTypeData

typedef struct MLPowerManagerPropertyTypeData MLPowerManagerPropertyTypeData;

A structure to encapsulate output data when getting a component's available property types.

More Info

API Level:

MLPowerManagerPropertyTypeInfo

typedef struct MLPowerManagerPropertyTypeInfo MLPowerManagerPropertyTypeInfo;

A structure to encapsulate information used by the Power Manager when getting the available property types.

This structure must be initialized by calling MLPowerManagerPropertyTypeInfoInit before use.

More Info

API Level:

MLPowerManagerPropertyInfo

typedef struct MLPowerManagerPropertyInfo MLPowerManagerPropertyInfo;

A structure to encapsulate info data used by the Power Manager when getting the current properties.

This structure must be initialized by calling MLPowerManagerPropertyInfoInit before use.

More Info

API Level:

MLPowerManagerPowerStateSettings

typedef struct MLPowerManagerPowerStateSettings MLPowerManagerPowerStateSettings;

A structure to encapsulate settings used by the Power Manager when requesting the power state to be changed.

This structure must be initialized by calling MLPowerManagerPowerStateSettingsInit before use.

More Info

API Level:

MLPowerManagerPowerStateInfo

typedef struct MLPowerManagerPowerStateInfo MLPowerManagerPowerStateInfo;

A structure to encapsulate info data used by the Power Manager when getting the current power state.

This structure must be initialized by calling MLPowerManagerPowerStateInfoInit before use.

More Info

API Level:

MLPowerManagerPowerStateData

typedef struct MLPowerManagerPowerStateData MLPowerManagerPowerStateData;

A structure to encapsulate output data when either getting available power states, or the current power state.

More Info

API Level:

MLPowerManagerCallbacks

typedef struct MLPowerManagerCallbacks MLPowerManagerCallbacks;

A structure containing Power Manager callback events. Individual callbacks which are not required by the Power Manager can be NULL.

More Info

API Level:

Functions Documentation

MLPowerManagerPropertyTypeInfoInit

static inline void MLPowerManagerPropertyTypeInfoInit(
    MLPowerManagerPropertyTypeInfo * inout_property_type_info
)

Initializes the default values for MLPowerManagerPropertyTypeInfo.

Parameters


MLPowerManagerPropertyTypeInfo *	inout_property_type_info	The object to initialize with default values.

API Level:

MLPowerManagerPropertyInfoInit

static inline void MLPowerManagerPropertyInfoInit(
    MLPowerManagerPropertyInfo * inout_property_info
)

Initializes the default values for MLPowerManagerPropertyInfo.

Parameters


MLPowerManagerPropertyInfo *	inout_property_info	The object to initialize with default values.

API Level:

MLPowerManagerPowerStateSettingsInit

static inline void MLPowerManagerPowerStateSettingsInit(
    MLPowerManagerPowerStateSettings * inout_power_settings
)

Initializes the default values for MLPowerManagerPowerStateSettings.

Parameters


MLPowerManagerPowerStateSettings *	inout_power_settings	The object to initialize with default values.

API Level:

MLPowerManagerPowerStateInfoInit

static inline void MLPowerManagerPowerStateInfoInit(
    MLPowerManagerPowerStateInfo * inout_power_info
)

Initializes the default values for MLPowerManagerPowerStateInfo.

Parameters


MLPowerManagerPowerStateInfo *	inout_power_info	The object to initialize with default values.

API Level:

MLPowerManagerCallbacksInit

static inline void MLPowerManagerCallbacksInit(
    MLPowerManagerCallbacks * inout_cb
)

Initializes the default values for MLPowerManagerCallbacks.

Parameters


MLPowerManagerCallbacks *	inout_cb	The object to initialize with default values.

API Level:

MLPowerManagerCreate

MLResult MLPowerManagerCreate(
    MLPowerManagerComponent component,
    MLHandle * out_handle
)

Creates a Power Manager handle for a specified component.

Parameters


MLPowerManagerComponent	component	The component specific to the handle to be created.
MLHandle *	out_handle	The handle to be created.

Returns


MLResult	MLResult_InvalidParam	Failed due to an invalid parameter.
MLResult	MlResult_HandleExists	Handle for this component already exists.
MLResult	MLResult_Ok	Power Manager handle was successfully created.
MLResult	MLResult_UnspecifiedFailure	Power Manager handle failed to be created.

Required Permissions:

none

In a single application multiple calls to this API method, for the same component type will return a new handle each time. The handle is valid until MLPowerManagerDestroy for that specific handle is called.

API Level:

MLPowerManagerDestroy

MLResult MLPowerManagerDestroy(
    MLHandle handle
)

Destroys a Power Manager handle.

Parameters


MLHandle	handle	The Power Manager handle for a specific component to be destroyed.

Returns


MLResult	MLResult_InvalidParam	Passed handle was invalid.
MLResult	MLResult_Ok	Power Manager handle was successfully destroyed.

Required Permissions:

None

API Level:

MLPowerManagerSetCallbacks

MLResult MLPowerManagerSetCallbacks(
    MLHandle handle,
    MLPowerManagerCallbacks * cb,
    void * user_data
)

Parameters


MLHandle	handle	Power Manager handle for component to set MLPowerManagerCallbacks for.
MLPowerManagerCallbacks *	cb	Callbacks to receive Power Manager events. Set this to NULL to unregister callbacks.
void *	user_data	The caller can pass in user context data that will be returned in the callback (can be NULL).

Returns


MLResult	MLResult_InvalidParam	Failed due to an invalid parameter.
MLResult	MLResult_Ok	The callbacks have been registered.
MLResult	MLResult_UnspecifiedFailure	The operation failed with an unspecified error.

Required Permissions:

None

The MLPowerManagerCallbacks structure can be set for each handle, whether those handles are for the same or different component types.

API Level:

MLPowerManagerSetPowerState

MLResult MLPowerManagerSetPowerState(
    MLHandle handle,
    const MLPowerManagerPowerStateSettings * settings
)

Sets the power state of a component. The new power state of a component will persist if the application loses focus, or exits.

Parameters


MLHandle	handle	Power Manager handle for component to set power state for.
const MLPowerManagerPowerStateSettings *	settings	Settings used by the Power Manager updating a component's power state.

Returns


MLResult	MLResult_IllegalState	The component does not support the requested power state.
MLResult	MLResult_InvalidParam	Failed due to an invalid parameter.
MLResult	MLPowerManagerResult_InvalidStateTransition	The component does not support transitioning to the requested state.
MLResult	MLPowerManagerResult_NotConnected	The component is not connected.
MLResult	MLResult_Ok	The power state of the controller was set successfully.
MLResult	MLPowerManagerResult_StateTransitionsDisabled	The component currently does not support transitioning to a different state.
MLResult	MLResult_UnspecifiedFailure	The operation failed with an unspecified error.
MLResult	MLPowerManagerResult_UnsupportedState	The component does not support the requested power state.

Required Permissions:

None

API Level:

MLPowerManagerGetComponentProperties

MLResult MLPowerManagerGetComponentProperties(
    MLHandle handle,
    const MLPowerManagerPropertyInfo * in_info,
    MLPowerManagerPropertyData * out_properties
)

Gets the power manager properties of a component.

Parameters


MLHandle	handle	Power Manager handle for component to get properties of.
const MLPowerManagerPropertyInfo *	in_info	MLPowerManagerPropertyInfo struct filled with information about the power manager properties of a component to request.
MLPowerManagerPropertyData *	out_properties	Information about the properties of a component. Must be released using MLPowerManagerReleasePropertyData after each successful call.

Returns


MLResult	MLResult_AllocFailed	Failed due to memory allocation failure.
MLResult	MLResult_InvalidParam	Failed due to an invalid parameter.
MLResult	MLResult_Ok	The property of the controller was retrieved successfully.
MLResult	MLResult_UnspecifiedFailure	The operation failed with an unspecified error.

Required Permissions:

None

API Level:

MLPowerManagerReleasePropertyData

MLResult MLPowerManagerReleasePropertyData(
    MLHandle handle,
    MLPowerManagerPropertyData * properties
)

Releases specified MLPowerManagerPropertyData.

Parameters


MLHandle	handle	Power Manager handle for component relating to MLPowerManagerPropertyData.
MLPowerManagerPropertyData *	properties	Pointer to a MLPowerManagerPropertyData returned from MLPowerManagerGetComponentProperties.

Returns


MLResult	MLResult_Ok	Successfully released MLPowerManagerPropertyData.
MLResult	MLResult_InvalidParam	properties parameter was not valid (NULL).
MLResult	MLResult_UnspecifiedFailure	Failed due to internal error.

Required Permissions:

None

This function should be called exactly once for each successful call to MLPowerManagerGetComponentProperties.

MLPowerManagerGetAvailablePowerStates

MLResult MLPowerManagerGetAvailablePowerStates(
    MLHandle handle,
    const MLPowerManagerPowerStateInfo * in_info,
    MLPowerManagerPowerStateData * out_states
)

Query available power states for a component.

Parameters


MLHandle	handle	Power Manager handle for component to get list of all available power states for.
const MLPowerManagerPowerStateInfo *	in_info	MLPowerManagerPowerStateInfo struct filled with data to be used by the Power Manager when requesting/receiving all available power states.
MLPowerManagerPowerStateData *	out_states	MLPowerManagerPowerStateData holding list of available power states. Must be released using MLPowerManagerReleasePowerStateData after each successful call.

Returns


MLResult	MLResult_AllocFailed	Failed due to memory allocation failure.
MLResult	MLResult_InvalidParam	Failed due to an invalid parameter.
MLResult	MLResult_Ok	Query completed and out_states has been populated.
MLResult	MLResult_UnspecifiedFailure	The operation failed with an unspecified error.

Required Permissions:

None

API Level:

MLPowerManagerGetPowerState

MLResult MLPowerManagerGetPowerState(
    MLHandle handle,
    const MLPowerManagerPowerStateInfo * in_info,
    MLPowerManagerPowerStateData * out_state
)

Gets the power state of a component.

Parameters


MLHandle	handle	Power Manager handle for component to get power state from.
const MLPowerManagerPowerStateInfo *	in_info	MLPowerManagerPowerStateInfo struct filled with data to be used by the Power Manager when requesting/receiving power state.
MLPowerManagerPowerStateData *	power_state	MLPowerManagerPowerStateData with the current power state. Must be released using MLPowerManagerReleasePowerStateData after each successful call.

Returns


MLResult	MLPowerManagerResult_NotConnected	The component is not connected.
MLResult	MLResult_InvalidParam	Failed due to an invalid parameter.
MLResult	MLResult_Ok	The power state of the controller was retrieved successfully.
MLResult	MLResult_UnspecifiedFailure	The operation failed with an unspecified error.

Required Permissions:

None

API Level:

MLPowerManagerReleasePowerStateData

MLResult MLPowerManagerReleasePowerStateData(
    MLHandle handle,
    MLPowerManagerPowerStateData * power_states
)

Releases specified MLPowerManagerPowerStateData.

Parameters


MLHandle	handle	Power Manager handle for component relating to MLPowerManagerPowerStateData.
MLPowerManagerPowerStateData *	power_states	Pointer to a MLPowerManagerPowerStateData.

Returns


MLResult	MLResult_Ok	Successfully released MLPowerManagerPowerStateData.
MLResult	MLResult_InvalidParam	power_states parameter was not valid (NULL).
MLResult	MLResult_UnspecifiedFailure	Failed due to internal error.

Required Permissions:

None

This function should be called exactly once for each successful call to MLPowerManagerGetAvailablePowerStates.

MLPowerManagerGetAvailableProperties

MLResult MLPowerManagerGetAvailableProperties(
    MLHandle handle,
    const MLPowerManagerPropertyTypeInfo * in_info,
    MLPowerManagerPropertyTypeData * out_properties
)

Request a list of the available MLPowerManagerPropertyType.

Parameters


MLHandle	handle	Power Manager handle for component to get properties from.
const MLPowerManagerPropertyTypeInfo *	in_info	MLPowerManagerPropertyTypeInfo struct filled with data to be used by the Power Manager when requesting/receiving available property types.
MLPowerManagerPropertyTypeData *	out_properties	Information about the properties of a component. Must be released using MLPowerManagerReleasePropertyTypeData after each successful call.

Returns


MLResult	MLResult_AllocFailed	Failed due to memory allocation failure.
MLResult	MLResult_InvalidParam	Failed due to an invalid parameter.
MLResult	MLResult_Ok	Query completed and out_properties has been populated.
MLResult	MLResult_UnspecifiedFailure	The operation failed with an unspecified error.

Required Permissions:

None

API Level:

MLPowerManagerReleasePropertyTypeData

MLResult MLPowerManagerReleasePropertyTypeData(
    MLHandle handle,
    MLPowerManagerPropertyTypeData * properties
)

Releases specified MLPowerManagerPropertyTypeData.

Parameters


MLHandle	handle	Power Manager handle for component relating to MLPowerManagerPropertyTypeData.
MLPowerManagerPropertyTypeData *	properties	Pointer to a MLPowerManagerPropertyTypeData.

Returns


MLResult	MLResult_Ok	Successfully MLPowerManagerPropertyTypeData.
MLResult	MLResult_InvalidParam	properties parameter was not valid (NULL).
MLResult	MLResult_UnspecifiedFailure	Failed due to internal error.

Required Permissions:

None

This function should be called exactly once for each successful call to MLPowerManagerGetAvailableProperties.

MLPowerManagerGetResultString

const char * MLPowerManagerGetResultString(
    MLResult result_code
)

Returns an ASCII string for each result code.

Parameters


MLResult	result_code	MLResult to select the result code.

Returns


const char *	ASCII	string containing readable version of result code.

Required Permissions:

None

API Level:

Source code

// %BANNER_BEGIN%
// ---------------------------------------------------------------------
// %COPYRIGHT_BEGIN%
// Copyright (c) 2023 Magic Leap, Inc. All Rights Reserved.
// Use of this file is governed by the Software License Agreement,
// located here: https://www.magicleap.com/software-license-agreement-ml2
// Terms and conditions applicable to third-party materials accompanying
// this distribution may also be found in the top-level NOTICE file
// appearing herein.
// %COPYRIGHT_END%
// ---------------------------------------------------------------------
// %BANNER_END%


#pragma once

#include "ml_api.h"
#include "ml_types.h"
#include <string.h>

ML_EXTERN_C_BEGIN

enum {
  MLResultAPIPrefix_PowerManager = MLRESULT_PREFIX(0x4c8a),
};

typedef enum MLPowerManagerResult {
  MLPowerManagerResult_NotConnected = MLResultAPIPrefix_PowerManager,

  MLPowerManagerResult_InvalidStateTransition,

  MLPowerManagerResult_StateTransitionsDisabled,

  MLPowerManagerResult_UnsupportedState,

  MLPowerManagerResult_Ensure32Bits = 0x7FFFFFFF
} MLPowerManagerResult;

typedef enum MLPowerManagerComponent {
  MLPowerManagerComponent_None = 0,

  MLPowerManagerComponent_Controller = 1,

  MLPowerManagerComponent_Ensure32Bits = 0x7FFFFFFF
} MLPowerManagerComponent;

typedef enum MLPowerManagerError {
  MLPowerManagerError_InvalidSKU = 0,

  MLPowerManagerError_Ensure32Bits = 0x7FFFFFFF
} MLPowerManagerError;

typedef enum MLPowerManagerPowerState {
  MLPowerManagerPowerState_None = 0,

  MLPowerManagerPowerState_Normal = 1,

  MLPowerManagerPowerState_DisabledWhileCharging = 2,

  MLPowerManagerPowerState_Standby = 3,

  MLPowerManagerPowerState_Sleep = 4,

  MLPowerManagerPowerState_Ensure32Bits = 0x7FFFFFFF
} MLPowerManagerPowerState;

typedef enum MLPowerManagerChargingState {

  MLPowerManagerChargingState_NotCharging = 0,

  MLPowerManagerChargingState_ChargingNormally = 1,

  MLPowerManagerChargingState_Ensure32Bits = 0x7FFFFFFF
} MLPowerManagerChargingState;

typedef enum MLPowerManagerConnectionState {
  MLPowerManagerConnectionState_Connected = 0,

  MLPowerManagerConnectionState_Disconnected = 1,

  MLPowerManagerConnectionState_Ensure32Bits = 0x7FFFFFFF
} MLPowerManagerConnectionState;

typedef enum MLPowerManagerBatteryInfo {
  MLPowerManagerBatteryInfo_OK = 0,

  MLPowerManagerBatteryInfo_BatteryLow = 1,

  MLPowerManagerBatteryInfo_BatteryCritical = 2,

  MLPowerManagerBatteryInfo_Ensure32Bits = 0x7FFFFFFF
} MLPowerManagerBatteryInfo;

typedef enum MLPowerManagerPropertyType {

  MLPowerManagerPropertyType_BatteryInfo = 0,

  MLPowerManagerPropertyType_BatteryLevel = 1,

  MLPowerManagerPropertyType_ChargingState = 2,

  MLPowerManagerPropertyType_ConnectionState = 3,

  MLPowerManagerPropertyType_Ensure32Bits = 0x7FFFFFFF
} MLPowerManagerPropertyType;

typedef struct MLPowerManagerComponentProperty {
  MLPowerManagerPropertyType property_type;

  union {
    MLPowerManagerBatteryInfo battery_info;

    uint8_t battery_level;

    MLPowerManagerChargingState charging_state;

    MLPowerManagerConnectionState connection_state;
  };
} MLPowerManagerComponentProperty;

typedef struct MLPowerManagerPropertyData {
  uint8_t size;

  MLPowerManagerComponentProperty *properties;

} MLPowerManagerPropertyData;

typedef struct MLPowerManagerPropertyTypeData {
  uint8_t size;

  MLPowerManagerPropertyType *property_types;

} MLPowerManagerPropertyTypeData;

typedef struct MLPowerManagerPropertyTypeInfo {
  uint32_t version;

} MLPowerManagerPropertyTypeInfo;


ML_STATIC_INLINE void MLPowerManagerPropertyTypeInfoInit(MLPowerManagerPropertyTypeInfo *inout_property_type_info) {
  if (inout_property_type_info) {
    memset(inout_property_type_info, 0, sizeof(MLPowerManagerPropertyTypeInfo));
    inout_property_type_info->version = 1u;
  }
}


typedef struct MLPowerManagerPropertyInfo {
  uint32_t version;

} MLPowerManagerPropertyInfo;

ML_STATIC_INLINE void MLPowerManagerPropertyInfoInit(MLPowerManagerPropertyInfo *inout_property_info) {
  if (inout_property_info) {
    memset(inout_property_info, 0, sizeof(MLPowerManagerPropertyInfo));
    inout_property_info->version = 1u;
  }
}

typedef struct MLPowerManagerPowerStateSettings {
  uint32_t version;

  MLPowerManagerPowerState power_state;

} MLPowerManagerPowerStateSettings;

ML_STATIC_INLINE void MLPowerManagerPowerStateSettingsInit(MLPowerManagerPowerStateSettings *inout_power_settings) {
  if (inout_power_settings) {
    memset(inout_power_settings, 0, sizeof(MLPowerManagerPowerStateSettings));
    inout_power_settings->version = 1u;
    inout_power_settings->power_state = MLPowerManagerPowerState_None;
  }
}

typedef struct MLPowerManagerPowerStateInfo {
  uint32_t version;

} MLPowerManagerPowerStateInfo;


ML_STATIC_INLINE void MLPowerManagerPowerStateInfoInit(MLPowerManagerPowerStateInfo *inout_power_info) {
  if (inout_power_info) {
    memset(inout_power_info, 0, sizeof(MLPowerManagerPowerStateInfo));
    inout_power_info->version = 1u;
  }
}


typedef struct MLPowerManagerPowerStateData {
  uint8_t size;

  MLPowerManagerPowerState *power_states;

} MLPowerManagerPowerStateData;


typedef struct MLPowerManagerCallbacks {
  uint32_t version;

  void (*on_power_state_changed)(MLPowerManagerPowerState state, void *user_data);

  void (*on_properties_changed)(const MLPowerManagerPropertyData *properties, void *user_data);

  void (*on_error_occurred)(MLPowerManagerError error, void *user_data);

} MLPowerManagerCallbacks;

ML_STATIC_INLINE void MLPowerManagerCallbacksInit(MLPowerManagerCallbacks *inout_cb) {
  if (inout_cb) {
    memset(inout_cb, 0, sizeof(MLPowerManagerCallbacks));
    inout_cb->version = 1u;
    inout_cb->on_power_state_changed = NULL;
    inout_cb->on_properties_changed = NULL;
    inout_cb->on_error_occurred = NULL;
  }
}


ML_API MLResult ML_CALL MLPowerManagerCreate(MLPowerManagerComponent component, MLHandle* out_handle);

ML_API MLResult ML_CALL MLPowerManagerDestroy(MLHandle handle);

ML_API MLResult ML_CALL MLPowerManagerSetCallbacks(MLHandle handle, MLPowerManagerCallbacks *cb,
                                                   void *user_data);

ML_API MLResult ML_CALL MLPowerManagerSetPowerState(MLHandle handle,
                                                    const MLPowerManagerPowerStateSettings *settings);

ML_API MLResult ML_CALL MLPowerManagerGetComponentProperties(MLHandle handle,
                                                             const MLPowerManagerPropertyInfo *in_info,
                                                             MLPowerManagerPropertyData *out_properties);


ML_API MLResult ML_CALL MLPowerManagerReleasePropertyData(MLHandle handle,
                                                          MLPowerManagerPropertyData *properties);

ML_API MLResult ML_CALL MLPowerManagerGetAvailablePowerStates(MLHandle handle,
                                                              const MLPowerManagerPowerStateInfo *in_info,
                                                              MLPowerManagerPowerStateData *out_states);

ML_API MLResult ML_CALL MLPowerManagerGetPowerState(MLHandle handle,
                                                    const MLPowerManagerPowerStateInfo *in_info,
                                                    MLPowerManagerPowerStateData *out_state);

ML_API MLResult ML_CALL MLPowerManagerReleasePowerStateData(MLHandle handle,
                                                            MLPowerManagerPowerStateData *power_states);

ML_API MLResult ML_CALL MLPowerManagerGetAvailableProperties(MLHandle handle,
                                                             const MLPowerManagerPropertyTypeInfo *in_info,
                                                             MLPowerManagerPropertyTypeData *out_properties);

ML_API MLResult ML_CALL MLPowerManagerReleasePropertyTypeData(MLHandle handle,
                                                              MLPowerManagerPropertyTypeData *properties);

ML_API const char *ML_CALL MLPowerManagerGetResultString(MLResult result_code);

ML_EXTERN_C_END

ml_power_manager.h

Classes​

Types​

Enums​

Functions​

Enums Documentation​

Anonymous Enum 24​

MLPowerManagerResult​

MLPowerManagerComponent​

MLPowerManagerError​

MLPowerManagerPowerState​

MLPowerManagerChargingState​

MLPowerManagerConnectionState​

MLPowerManagerBatteryInfo​

MLPowerManagerPropertyType​

Types Documentation​

MLPowerManagerComponentProperty​

MLPowerManagerPropertyData​

MLPowerManagerPropertyTypeData​

MLPowerManagerPropertyTypeInfo​

MLPowerManagerPropertyInfo​

MLPowerManagerPowerStateSettings​

MLPowerManagerPowerStateInfo​

MLPowerManagerPowerStateData​

MLPowerManagerCallbacks​

Functions Documentation​

MLPowerManagerPropertyTypeInfoInit​

MLPowerManagerPropertyInfoInit​

MLPowerManagerPowerStateSettingsInit​

MLPowerManagerPowerStateInfoInit​

MLPowerManagerCallbacksInit​

MLPowerManagerCreate​

MLPowerManagerDestroy​

MLPowerManagerSetCallbacks​

MLPowerManagerSetPowerState​

MLPowerManagerGetComponentProperties​

MLPowerManagerReleasePropertyData​

MLPowerManagerGetAvailablePowerStates​

MLPowerManagerGetPowerState​

MLPowerManagerReleasePowerStateData​

MLPowerManagerGetAvailableProperties​

MLPowerManagerReleasePropertyTypeData​

MLPowerManagerGetResultString​

Source code​

Classes

Types

Enums

Functions

Enums Documentation

Anonymous Enum 24

MLPowerManagerResult

MLPowerManagerComponent

MLPowerManagerError

MLPowerManagerPowerState

MLPowerManagerChargingState

MLPowerManagerConnectionState

MLPowerManagerBatteryInfo

MLPowerManagerPropertyType

Types Documentation

MLPowerManagerComponentProperty

MLPowerManagerPropertyData

MLPowerManagerPropertyTypeData

MLPowerManagerPropertyTypeInfo

MLPowerManagerPropertyInfo

MLPowerManagerPowerStateSettings

MLPowerManagerPowerStateInfo

MLPowerManagerPowerStateData

MLPowerManagerCallbacks

Functions Documentation

MLPowerManagerPropertyTypeInfoInit

MLPowerManagerPropertyInfoInit

MLPowerManagerPowerStateSettingsInit

MLPowerManagerPowerStateInfoInit

MLPowerManagerCallbacksInit

MLPowerManagerCreate

MLPowerManagerDestroy

MLPowerManagerSetCallbacks

MLPowerManagerSetPowerState

MLPowerManagerGetComponentProperties

MLPowerManagerReleasePropertyData

MLPowerManagerGetAvailablePowerStates

MLPowerManagerGetPowerState

MLPowerManagerReleasePowerStateData

MLPowerManagerGetAvailableProperties

MLPowerManagerReleasePropertyTypeData

MLPowerManagerGetResultString

Source code