Skip to main content
Version: 21 Aug 2024

ml_power_manager.h

Classes

Name
structMLPowerManagerComponentProperty
A structure to encapsulate the data for each MLPowerManagerPropertyType.
structMLPowerManagerPropertyData
A structure to encapsulate output data when getting the current properties.
structMLPowerManagerPropertyTypeData
A structure to encapsulate output data when getting a component's available property types.
structMLPowerManagerPropertyTypeInfo
A structure to encapsulate information used by the Power Manager when getting the available property types.
structMLPowerManagerPropertyInfo
A structure to encapsulate info data used by the Power Manager when getting the current properties.
structMLPowerManagerPowerStateSettings
A structure to encapsulate settings used by the Power Manager when requesting the power state to be changed.
structMLPowerManagerPowerStateInfo
A structure to encapsulate info data used by the Power Manager when getting the current power state.
structMLPowerManagerPowerStateData
A structure to encapsulate output data when either getting available power states, or the current power state.
structMLPowerManagerCallbacks
A structure containing Power Manager callback events. Individual callbacks which are not required by the Power Manager can be NULL.
unionMLPowerManagerComponentProperty.unnamed

Types

Name
typedef struct MLPowerManagerComponentPropertyMLPowerManagerComponentProperty
A structure to encapsulate the data for each MLPowerManagerPropertyType.
typedef struct MLPowerManagerPropertyDataMLPowerManagerPropertyData
A structure to encapsulate output data when getting the current properties.
typedef struct MLPowerManagerPropertyTypeDataMLPowerManagerPropertyTypeData
A structure to encapsulate output data when getting a component's available property types.
typedef struct MLPowerManagerPropertyTypeInfoMLPowerManagerPropertyTypeInfo
A structure to encapsulate information used by the Power Manager when getting the available property types.
typedef struct MLPowerManagerPropertyInfoMLPowerManagerPropertyInfo
A structure to encapsulate info data used by the Power Manager when getting the current properties.
typedef struct MLPowerManagerPowerStateSettingsMLPowerManagerPowerStateSettings
A structure to encapsulate settings used by the Power Manager when requesting the power state to be changed.
typedef struct MLPowerManagerPowerStateInfoMLPowerManagerPowerStateInfo
A structure to encapsulate info data used by the Power Manager when getting the current power state.
typedef struct MLPowerManagerPowerStateDataMLPowerManagerPowerStateData
A structure to encapsulate output data when either getting available power states, or the current power state.
typedef struct MLPowerManagerCallbacksMLPowerManagerCallbacks
A structure containing Power Manager callback events. Individual callbacks which are not required by the Power Manager can be NULL.

Enums

Name
enumAnonymous Enum 24
{
MLResultAPIPrefix_PowerManager = ( 0x4c8a << 16)
}
enumMLPowerManagerResult
{
MLPowerManagerResult_NotConnected = MLResultAPIPrefix_PowerManager,
MLPowerManagerResult_InvalidStateTransition,
MLPowerManagerResult_StateTransitionsDisabled,
MLPowerManagerResult_UnsupportedState,
MLPowerManagerResult_Ensure32Bits = 0x7FFFFFFF
}
Power Manager specific return codes.
enumMLPowerManagerComponent
{
MLPowerManagerComponent_None = 0,
MLPowerManagerComponent_Controller = 1,
MLPowerManagerComponent_Ensure32Bits = 0x7FFFFFFF
}
Represents the different components which can be accessed/controlled using the Power Manager.
enumMLPowerManagerError
{
MLPowerManagerError_InvalidSKU = 0,
MLPowerManagerError_Ensure32Bits = 0x7FFFFFFF
}
Power Manager error codes.
enumMLPowerManagerPowerState
{
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.
enumMLPowerManagerChargingState
{
MLPowerManagerChargingState_NotCharging = 0,
MLPowerManagerChargingState_ChargingNormally = 1,
MLPowerManagerChargingState_Ensure32Bits = 0x7FFFFFFF
}
Power Manager charging states.
enumMLPowerManagerConnectionState
{
MLPowerManagerConnectionState_Connected = 0,
MLPowerManagerConnectionState_Disconnected = 1,
MLPowerManagerConnectionState_Ensure32Bits = 0x7FFFFFFF
}
Connection state of the component.
enumMLPowerManagerBatteryInfo
{
MLPowerManagerBatteryInfo_OK = 0,
MLPowerManagerBatteryInfo_BatteryLow = 1,
MLPowerManagerBatteryInfo_BatteryCritical = 2,
MLPowerManagerBatteryInfo_Ensure32Bits = 0x7FFFFFFF
}
Battery info/warning codes.
enumMLPowerManagerPropertyType
{
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
voidMLPowerManagerPropertyTypeInfoInit(MLPowerManagerPropertyTypeInfo * inout_property_type_info)
Initializes the default values for MLPowerManagerPropertyTypeInfo.
voidMLPowerManagerPropertyInfoInit(MLPowerManagerPropertyInfo * inout_property_info)
Initializes the default values for MLPowerManagerPropertyInfo.
voidMLPowerManagerPowerStateSettingsInit(MLPowerManagerPowerStateSettings * inout_power_settings)
Initializes the default values for MLPowerManagerPowerStateSettings.
voidMLPowerManagerPowerStateInfoInit(MLPowerManagerPowerStateInfo * inout_power_info)
Initializes the default values for MLPowerManagerPowerStateInfo.
voidMLPowerManagerCallbacksInit(MLPowerManagerCallbacks * inout_cb)
Initializes the default values for MLPowerManagerCallbacks.
MLResultMLPowerManagerCreate(MLPowerManagerComponent component, MLHandle * out_handle)
Creates a Power Manager handle for a specified component.
MLResultMLPowerManagerDestroy(MLHandle handle)
Destroys a Power Manager handle.
MLResultMLPowerManagerSetCallbacks(MLHandle handle, MLPowerManagerCallbacks cb, void user_data)
Register Power Manager callbacks for a specific handle.
MLResultMLPowerManagerSetPowerState(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.
MLResultMLPowerManagerGetComponentProperties(MLHandle handle, const MLPowerManagerPropertyInfo in_info, MLPowerManagerPropertyData out_properties)
Gets the power manager properties of a component.
MLResultMLPowerManagerReleasePropertyData(MLHandle handle, MLPowerManagerPropertyData * properties)
Releases specified MLPowerManagerPropertyData.
MLResultMLPowerManagerGetAvailablePowerStates(MLHandle handle, const MLPowerManagerPowerStateInfo in_info, MLPowerManagerPowerStateData out_states)
Query available power states for a component.
MLResultMLPowerManagerGetPowerState(MLHandle handle, const MLPowerManagerPowerStateInfo in_info, MLPowerManagerPowerStateData out_state)
Gets the power state of a component.
MLResultMLPowerManagerReleasePowerStateData(MLHandle handle, MLPowerManagerPowerStateData * power_states)
Releases specified MLPowerManagerPowerStateData.
MLResultMLPowerManagerGetAvailableProperties(MLHandle handle, const MLPowerManagerPropertyTypeInfo in_info, MLPowerManagerPropertyTypeData out_properties)
Request a list of the available MLPowerManagerPropertyType.
MLResultMLPowerManagerReleasePropertyTypeData(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

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

MLPowerManagerResult

EnumeratorValueDescription
MLPowerManagerResult_NotConnectedMLResultAPIPrefix_PowerManagerIndicates the component is not connected.
MLPowerManagerResult_InvalidStateTransitionIndicates the component does not currently support transitioning to requested state.
MLPowerManagerResult_StateTransitionsDisabledIndicates the component does not currently support transitioning to a different state.
MLPowerManagerResult_UnsupportedStateIndicates the component does not support the requested power state.
MLPowerManagerResult_Ensure32Bits0x7FFFFFFFEnsure enum is represented as 32 bits.

Power Manager specific return codes.

API Level:

  • 27

MLPowerManagerComponent

EnumeratorValueDescription
MLPowerManagerComponent_None0Invalid or no component.
MLPowerManagerComponent_Controller1Controller.
MLPowerManagerComponent_Ensure32Bits0x7FFFFFFFEnsure enum is represented as 32 bits.

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

API Level:

  • 27

MLPowerManagerError

EnumeratorValueDescription
MLPowerManagerError_InvalidSKU0Controller component could not be connected due to Invalid SKU.
MLPowerManagerError_Ensure32Bits0x7FFFFFFFEnsure enum is represented as 32 bits.

Power Manager error codes.

API Level:

  • 27

MLPowerManagerPowerState

EnumeratorValueDescription
MLPowerManagerPowerState_None0Invalid or no power state.
MLPowerManagerPowerState_Normal1Normal mode, this is the default or active state of the component.
MLPowerManagerPowerState_DisabledWhileCharging2Charging only mode. When charging component it cannot be used.
MLPowerManagerPowerState_Standby3Standby mode.
MLPowerManagerPowerState_Sleep4Sleep mode.
MLPowerManagerPowerState_Ensure32Bits0x7FFFFFFFEnsure enum is represented as 32 bits.

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

ComponentPower StateDescription
ControllerNormalController is active
Disabled While ChargingCertain SKUs cannot use controller while charging
StandbyController is turned on but inactive, press home button to switch to active manually
SleepNot supported for this component

API Level:

  • 27

MLPowerManagerChargingState

EnumeratorValueDescription
MLPowerManagerChargingState_NotCharging0Not charging.
MLPowerManagerChargingState_ChargingNormally1Charging normally.
MLPowerManagerChargingState_Ensure32Bits0x7FFFFFFFEnsure enum is represented as 32 bits.

Power Manager charging states.

API Level:

  • 27

MLPowerManagerConnectionState

EnumeratorValueDescription
MLPowerManagerConnectionState_Connected0Component is connected.
MLPowerManagerConnectionState_Disconnected1Component is disconnected.
MLPowerManagerConnectionState_Ensure32Bits0x7FFFFFFFEnsure enum is represented as 32 bits.

Connection state of the component.

API Level:

  • 27

MLPowerManagerBatteryInfo

EnumeratorValueDescription
MLPowerManagerBatteryInfo_OK0No issues reported.
MLPowerManagerBatteryInfo_BatteryLow1Charge the component soon.
MLPowerManagerBatteryInfo_BatteryCritical2Charge the component immediately.
MLPowerManagerBatteryInfo_Ensure32Bits0x7FFFFFFFEnsure enum is represented as 32 bits.

Battery info/warning codes.

API Level:

  • 27

MLPowerManagerPropertyType

EnumeratorValueDescription
MLPowerManagerPropertyType_BatteryInfo0Extra info about battery, as represented by MLPowerManagerBatteryInfo.
MLPowerManagerPropertyType_BatteryLevel1Battery level. Range is between 0 and 100.
MLPowerManagerPropertyType_ChargingState2Charging state.
MLPowerManagerPropertyType_ConnectionState3Connection state.
MLPowerManagerPropertyType_Ensure32Bits0x7FFFFFFFEnsure 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:

  • 27

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:

  • 27

MLPowerManagerPropertyData

typedef struct MLPowerManagerPropertyData MLPowerManagerPropertyData;

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

More Info

API Level:

  • 27

MLPowerManagerPropertyTypeData

typedef struct MLPowerManagerPropertyTypeData MLPowerManagerPropertyTypeData;

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

More Info

API Level:

  • 27

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:

  • 27

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:

  • 27

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:

  • 27

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:

  • 27

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:

  • 27

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:

  • 27

Functions Documentation

MLPowerManagerPropertyTypeInfoInit

static inline void MLPowerManagerPropertyTypeInfoInit(
MLPowerManagerPropertyTypeInfo * inout_property_type_info
)

Initializes the default values for MLPowerManagerPropertyTypeInfo.

Parameters

MLPowerManagerPropertyTypeInfo *inout_property_type_infoThe object to initialize with default values.

API Level:

  • 27

MLPowerManagerPropertyInfoInit

static inline void MLPowerManagerPropertyInfoInit(
MLPowerManagerPropertyInfo * inout_property_info
)

Initializes the default values for MLPowerManagerPropertyInfo.

Parameters

MLPowerManagerPropertyInfo *inout_property_infoThe object to initialize with default values.

API Level:

  • 27

MLPowerManagerPowerStateSettingsInit

static inline void MLPowerManagerPowerStateSettingsInit(
MLPowerManagerPowerStateSettings * inout_power_settings
)

Initializes the default values for MLPowerManagerPowerStateSettings.

Parameters

MLPowerManagerPowerStateSettings *inout_power_settingsThe object to initialize with default values.

API Level:

  • 27

MLPowerManagerPowerStateInfoInit

static inline void MLPowerManagerPowerStateInfoInit(
MLPowerManagerPowerStateInfo * inout_power_info
)

Initializes the default values for MLPowerManagerPowerStateInfo.

Parameters

MLPowerManagerPowerStateInfo *inout_power_infoThe object to initialize with default values.

API Level:

  • 27

MLPowerManagerCallbacksInit

static inline void MLPowerManagerCallbacksInit(
MLPowerManagerCallbacks * inout_cb
)

Initializes the default values for MLPowerManagerCallbacks.

Parameters

MLPowerManagerCallbacks *inout_cbThe object to initialize with default values.

API Level:

  • 27

MLPowerManagerCreate

MLResult MLPowerManagerCreate(
MLPowerManagerComponent component,
MLHandle * out_handle
)

Creates a Power Manager handle for a specified component.

Parameters

MLPowerManagerComponentcomponentThe component specific to the handle to be created.
MLHandle *out_handleThe handle to be created.

Returns

MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMlResult_HandleExistsHandle for this component already exists.
MLResultMLResult_OkPower Manager handle was successfully created.
MLResultMLResult_UnspecifiedFailurePower 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:

  • 27

MLPowerManagerDestroy

MLResult MLPowerManagerDestroy(
MLHandle handle
)

Destroys a Power Manager handle.

Parameters

MLHandlehandleThe Power Manager handle for a specific component to be destroyed.

Returns

MLResultMLResult_InvalidParamPassed handle was invalid.
MLResultMLResult_OkPower Manager handle was successfully destroyed.

Required Permissions:

  • None

API Level:

  • 27

MLPowerManagerSetCallbacks

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

Register Power Manager callbacks for a specific handle.

Parameters

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

Returns

MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkThe callbacks have been registered.
MLResultMLResult_UnspecifiedFailureThe 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:

  • 27

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

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

Returns

MLResultMLResult_IllegalStateThe component does not support the requested power state.
MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLPowerManagerResult_InvalidStateTransitionThe component does not support transitioning to the requested state.
MLResultMLPowerManagerResult_NotConnectedThe component is not connected.
MLResultMLResult_OkThe power state of the controller was set successfully.
MLResultMLPowerManagerResult_StateTransitionsDisabledThe component currently does not support transitioning to a different state.
MLResultMLResult_UnspecifiedFailureThe operation failed with an unspecified error.
MLResultMLPowerManagerResult_UnsupportedStateThe component does not support the requested power state.

Required Permissions:

  • None

API Level:

  • 27

MLPowerManagerGetComponentProperties

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

Gets the power manager properties of a component.

Parameters

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

Returns

MLResultMLResult_AllocFailedFailed due to memory allocation failure.
MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkThe property of the controller was retrieved successfully.
MLResultMLResult_UnspecifiedFailureThe operation failed with an unspecified error.

Required Permissions:

  • None

API Level:

  • 27

MLPowerManagerReleasePropertyData

MLResult MLPowerManagerReleasePropertyData(
MLHandle handle,
MLPowerManagerPropertyData * properties
)

Releases specified MLPowerManagerPropertyData.

Parameters

MLHandlehandlePower Manager handle for component relating to MLPowerManagerPropertyData.
MLPowerManagerPropertyData *propertiesPointer to a MLPowerManagerPropertyData returned from MLPowerManagerGetComponentProperties.

Returns

MLResultMLResult_OkSuccessfully released MLPowerManagerPropertyData.
MLResultMLResult_InvalidParamproperties parameter was not valid (NULL).
MLResultMLResult_UnspecifiedFailureFailed 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

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

Returns

MLResultMLResult_AllocFailedFailed due to memory allocation failure.
MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkQuery completed and out_states has been populated.
MLResultMLResult_UnspecifiedFailureThe operation failed with an unspecified error.

Required Permissions:

  • None

API Level:

  • 27

MLPowerManagerGetPowerState

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

Gets the power state of a component.

Parameters

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

Returns

MLResultMLPowerManagerResult_NotConnectedThe component is not connected.
MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkThe power state of the controller was retrieved successfully.
MLResultMLResult_UnspecifiedFailureThe operation failed with an unspecified error.

Required Permissions:

  • None

API Level:

  • 27

MLPowerManagerReleasePowerStateData

MLResult MLPowerManagerReleasePowerStateData(
MLHandle handle,
MLPowerManagerPowerStateData * power_states
)

Releases specified MLPowerManagerPowerStateData.

Parameters

MLHandlehandlePower Manager handle for component relating to MLPowerManagerPowerStateData.
MLPowerManagerPowerStateData *power_statesPointer to a MLPowerManagerPowerStateData.

Returns

MLResultMLResult_OkSuccessfully released MLPowerManagerPowerStateData.
MLResultMLResult_InvalidParampower_states parameter was not valid (NULL).
MLResultMLResult_UnspecifiedFailureFailed 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

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

Returns

MLResultMLResult_AllocFailedFailed due to memory allocation failure.
MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkQuery completed and out_properties has been populated.
MLResultMLResult_UnspecifiedFailureThe operation failed with an unspecified error.

Required Permissions:

  • None

API Level:

  • 27

MLPowerManagerReleasePropertyTypeData

MLResult MLPowerManagerReleasePropertyTypeData(
MLHandle handle,
MLPowerManagerPropertyTypeData * properties
)

Releases specified MLPowerManagerPropertyTypeData.

Parameters

MLHandlehandlePower Manager handle for component relating to MLPowerManagerPropertyTypeData.
MLPowerManagerPropertyTypeData *propertiesPointer to a MLPowerManagerPropertyTypeData.

Returns

MLResultMLResult_OkSuccessfully MLPowerManagerPropertyTypeData.
MLResultMLResult_InvalidParamproperties parameter was not valid (NULL).
MLResultMLResult_UnspecifiedFailureFailed 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

MLResultresult_codeMLResult to select the result code.

Returns

const char *ASCIIstring containing readable version of result code.

Required Permissions:

  • None

API Level:

  • 27

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