Skip to main content
Version: 21 Aug 2024

ml_api.h

Classes

Name
structMLVersion

Types

Name
typedef uint64_tMLHandle
Integer handle type used to reference many things returned by the API, instead of returning pointers directly. Use MLHandleIsValid() to check if a handle is valid or not.
typedef struct MLVersionMLVersion
typedef int32_tMLResult

Enums

Name
enumAnonymous Enum 0
{
ML_INVALID_HANDLE = 0xFFFFFFFFFFFFFFFF
}
enumAnonymous Enum 1
{
MLVersion_BuildIdMaxLength = 128
}
enumAnonymous Enum 2
{
MLResultAPIPrefix_Global = ( 0 << 16)
}
enumMLResultGlobal
{
MLResult_Ok = MLResultAPIPrefix_Global,
MLResult_Pending,
MLResult_Timeout,
MLResult_Locked,
MLResult_UnspecifiedFailure,
MLResult_InvalidParam,
MLResult_AllocFailed,
MLResult_PermissionDenied,
MLResult_NotImplemented,
MLResult_ClientLimitExceeded,
MLResult_PoseNotFound,
MLResult_IncompatibleSKU,
MLResult_PerceptionSystemNotStarted,
MLResult_IllegalState,
MLResult_LicenseError,
MLResult_InvalidTimestamp,
MLResult_Unauthenticated,
MLResult_Ensure32Bits = 0x7FFFFFFF
}

Functions

Name
const char *MLGetResultString(MLResult result_code)
Returns an ASCII string for MLResultGlobal codes.
const char *MLGlobalGetResultString(MLResult result_code)
Returns an ASCII string for MLResult codes.
boolMLHandleIsValid(MLHandle handle)
Check if a handle is valid.
const char *MLGetVersionName()
Get SDK version as c-style string.
MLVersionMLGetVersion()
Get SDK version as a struct with major, minor, revision, and build_id.

Defines

Name
ML_API
ML_CALL
ML_DEPRECATED_MSG(msg)
ML_DEPRECATED
ML_STATIC_INLINE
ML_EXTERN_C_BEGIN
ML_EXTERN_C_END
MLRESULT_PREFIX(val)

Enums Documentation

Anonymous Enum 0

EnumeratorValueDescription
ML_INVALID_HANDLE0xFFFFFFFFFFFFFFFFValue of an invalid handle. To test if a handle is invalid use MLHandleIsValid().

Anonymous Enum 1

EnumeratorValueDescription
MLVersion_BuildIdMaxLength128Maximum character length of MLVersion build ID.

Anonymous Enum 2

EnumeratorValueDescription
MLResultAPIPrefix_Global( 0 << 16)Defines the prefix for global MLResult codes.

MLResultGlobal

EnumeratorValueDescription
MLResult_OkMLResultAPIPrefix_GlobalOperation completed successfully.
MLResult_PendingAsynchronous operation has not completed.
MLResult_TimeoutOperation has timed out.
MLResult_LockedRequest to lock a shared resource that is already locked.
MLResult_UnspecifiedFailureOperation failed due to an unspecified internal error.
MLResult_InvalidParamOperation failed due to an invalid parameter being supplied.
MLResult_AllocFailedOperation failed because memory failed to be allocated.
MLResult_PermissionDeniedOperation failed because a required permission has not been granted.
MLResult_NotImplementedOperation failed because it is not currently implemented.
MLResult_ClientLimitExceededOperation failed because the client count exceeded the number of clients available.
MLResult_PoseNotFoundOperation failed because the requested pose is not available.
MLResult_IncompatibleSKUOperation failed because feature isn't supported on current device version.
MLResult_PerceptionSystemNotStartedOperation failed because the Perception System was not started.
MLResult_IllegalStateOperation failed because it has been invoked at the wrong time.
MLResult_LicenseErrorOperation failed because of missing/incompatible license.
MLResult_InvalidTimestampOperation failed because the timestamp parameter was outside the expected range.
MLResult_UnauthenticatedOperation failed because the user authentication did not pass.
MLResult_Ensure32Bits0x7FFFFFFFEnsure enum is represented as 32 bits.

Global MLResult codes that any API can optionally return.


Types Documentation

MLHandle

typedef uint64_t MLHandle;

Integer handle type used to reference many things returned by the API, instead of returning pointers directly. Use MLHandleIsValid() to check if a handle is valid or not.


MLVersion

typedef struct MLVersion MLVersion;

SDK version: '[major].[minor].[revision].[build_id]'.

More Info


MLResult

typedef int32_t MLResult;

MLResult type that all functions in the APIs return.


Functions Documentation

MLGetResultString

static inline const char * MLGetResultString(
MLResult result_code
)

Returns an ASCII string for MLResultGlobal codes.

Parameters

MLResultresult_codeThe input MLResult enum from ML API functions.

Required Permissions:

  • None

Return: ASCII string containing readable version of result code.


MLGlobalGetResultString

const char * MLGlobalGetResultString(
MLResult result_code
)

Returns an ASCII string for MLResult codes.

Parameters

MLResultresult_codeThe input MLResult enum from ML API functions.

Required Permissions:

  • None

Return: ASCII string containing readable version of result code.

API Level:

  • 20

MLHandleIsValid

static inline bool MLHandleIsValid(
MLHandle handle
)

Check if a handle is valid.

Parameters

MLHandlehandleThe handle to check.

Required Permissions:

  • None

Return: true if the handle is valid.


MLGetVersionName

static inline const char * MLGetVersionName()

Get SDK version as c-style string.

Required Permissions:

  • None

Return: SDK version as c-style string.


MLGetVersion

static inline MLVersion MLGetVersion()

Get SDK version as a struct with major, minor, revision, and build_id.

Required Permissions:

  • None

Return: SDK version as a struct.


Macros Documentation

ML_API

#define ML_API 

ML_CALL

#define ML_CALL 

ML_DEPRECATED_MSG

#define ML_DEPRECATED_MSG(
msg
)
__attribute__((deprecated(msg)))

Parameters

msg

ML_DEPRECATED

#define ML_DEPRECATED __attribute__((deprecated))

ML_STATIC_INLINE

#define ML_STATIC_INLINE static inline

ML_EXTERN_C_BEGIN

#define ML_EXTERN_C_BEGIN 

ML_EXTERN_C_END

#define ML_EXTERN_C_END 

MLRESULT_PREFIX

#define MLRESULT_PREFIX(
val
)
(val << 16)

Parameters

val

Macro to set a the prefix bytes of an API specific MLResult code.


Source code

// %BANNER_BEGIN%
// ---------------------------------------------------------------------
// %COPYRIGHT_BEGIN%
// Copyright (c) 2017 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 <stdint.h>
#include <stdbool.h>
#include <stddef.h>

#if defined(_MSC_VER) && _MSC_VER
#ifdef ML_EXPORT
#define ML_API __declspec(dllexport)
#else
#define ML_API __declspec(dllimport)
#endif
#define ML_CALL __cdecl
#if defined(ML_NO_DEPRECATION_WARNING)
#define ML_DEPRECATED_MSG(msg)
#define ML_DEPRECATED
#if !defined(ML_NO_DEPRECATION_DISABLED_MSG)
#pragma message("Magic Leap C SDK - API deprecation warnings are disabled.")
#endif
#else
#define ML_DEPRECATED_MSG(msg) __declspec(deprecated(msg))
#define ML_DEPRECATED __declspec(deprecated)
#endif
#define ML_STATIC_INLINE __inline
#else
#define ML_API
#define ML_CALL
#if defined(ML_NO_DEPRECATION_WARNING)
#define ML_DEPRECATED_MSG(msg)
#define ML_DEPRECATED
#if !defined(ML_NO_DEPRECATION_DISABLED_MSG)
#pragma message("Magic Leap C SDK - API deprecation warnings are disabled.")
#endif
#else
#define ML_DEPRECATED_MSG(msg) __attribute__((deprecated(msg)))
#define ML_DEPRECATED __attribute__((deprecated))
#endif
#define ML_STATIC_INLINE static inline
#endif

#ifdef __cplusplus
#define ML_EXTERN_C_BEGIN extern "C" {
#define ML_EXTERN_C_END }
#else
#define ML_EXTERN_C_BEGIN
#define ML_EXTERN_C_END
#endif

#include "ml_coordinate_frame_uid.h"
#include "ml_version.h"

ML_EXTERN_C_BEGIN

typedef uint64_t MLHandle;

enum {
ML_INVALID_HANDLE = 0xFFFFFFFFFFFFFFFF
};

enum {
MLVersion_BuildIdMaxLength = 128
};

typedef struct MLVersion {
uint32_t major;
uint32_t minor;
uint32_t revision;
char build_id[MLVersion_BuildIdMaxLength];
} MLVersion;

#define MLRESULT_PREFIX(val) (val << 16)

enum {
MLResultAPIPrefix_Global = MLRESULT_PREFIX(0),
};

typedef enum MLResultGlobal {
MLResult_Ok = MLResultAPIPrefix_Global,
MLResult_Pending,
MLResult_Timeout,
MLResult_Locked,
MLResult_UnspecifiedFailure,
MLResult_InvalidParam,
MLResult_AllocFailed,
MLResult_PermissionDenied,
MLResult_NotImplemented,
MLResult_ClientLimitExceeded,
MLResult_PoseNotFound,
MLResult_IncompatibleSKU,
MLResult_PerceptionSystemNotStarted,
MLResult_IllegalState,
MLResult_LicenseError,
MLResult_InvalidTimestamp,
MLResult_Unauthenticated,
MLResult_Ensure32Bits = 0x7FFFFFFF
} MLResultGlobal;

typedef int32_t MLResult;

ML_STATIC_INLINE const char* ML_CALL MLGetResultString(MLResult result_code) {
switch (result_code) {
case MLResult_Ok: return "MLResult_Ok";
case MLResult_Pending: return "MLResult_Pending";
case MLResult_Timeout: return "MLResult_Timeout";
case MLResult_Locked: return "MLResult_Locked";
case MLResult_UnspecifiedFailure: return "MLResult_UnspecifiedFailure";
case MLResult_InvalidParam: return "MLResult_InvalidParam";
case MLResult_AllocFailed: return "MLResult_AllocFailed";
case MLResult_PermissionDenied: return "MLResult_PermissionDenied";
case MLResult_NotImplemented: return "MLResult_NotImplemented";
case MLResult_ClientLimitExceeded: return "MLResult_ClientLimitExceeded";
case MLResult_IncompatibleSKU: return "MLResult_IncompatibleSKU";
case MLResult_PoseNotFound: return "MLResult_PoseNotFound";
case MLResult_PerceptionSystemNotStarted: return "MLResult_PerceptionSystemNotStarted";
case MLResult_IllegalState: return "MLResult_IllegalState";
case MLResult_LicenseError: return "MLResult_LicenseError";
case MLResult_InvalidTimestamp: return "MLResult_InvalidTimestamp";
case MLResult_Unauthenticated: return "MLResult_Unauthenticated";
default: return "Unknown";
}
}

ML_API const char* ML_CALL MLGlobalGetResultString(MLResult result_code);

ML_STATIC_INLINE bool MLHandleIsValid(MLHandle handle) {
return handle != ML_INVALID_HANDLE;
}

ML_STATIC_INLINE const char *ML_CALL MLGetVersionName() {
return MLSDK_VERSION_NAME;
}

ML_STATIC_INLINE MLVersion MLGetVersion() {
MLVersion version = {MLSDK_VERSION_MAJOR,
MLSDK_VERSION_MINOR,
MLSDK_VERSION_REVISION,
MLSDK_VERSION_BUILD_ID};
return version;
}

ML_EXTERN_C_END