NativeService

ANativeService APIs allow you to implement Services declared as.

Summary

android:nativeService=true
using only native code.

Because most NDK APIs rely on the Android Runtime (ART), the APIs available to native services (which may not have the ART loaded inside their processes) are limited to a specific subset. The current set of supported APIs is:

  • AFont_*
  • AFontMatcher_*
  • AIBinder_*
    • except AIBinder_fromJavaBinder and AIBinder_toJavaBinder
  • ALooper_*
  • ANativeService_*
  • AParcel_*
    • except AParcel_fromJavaParcel
  • APersistableBundle_*
  • ASharedMemory_*
    • except ASharedMemory_dupFromJava
  • AStatus_*
  • ASystemFontIterator_*
  • ATrace_*

Enumerations
ANativeServiceTrimMemoryLevel{
  ANATIVE_SERVICE_TRIM_MEMORY_UI_HIDDEN = 20,
  ANATIVE_SERVICE_TRIM_MEMORY_BACKGROUND = 40
} 		enum
The levels for ANativeService_onTrimMemoryCallback indicating the context of the trim, giving a hint of the amount of trimming the application may like to perform.

Typedefs
ANativeService typedef
typedef__BEGIN_DECLS struct ANativeService
An opaque struct representing a native service instance.
ANativeServiceTrimMemoryLevel typedef
The levels for ANativeService_onTrimMemoryCallback indicating the context of the trim, giving a hint of the amount of trimming the application may like to perform.
ANativeService_createFunc(ANativeService *_Nonnull service) typedef
void
The function type signature definition of the entry point function of the service.
ANativeService_onBindCallback)(ANativeService *_Nonnull service, uint64_t bindToken, char const *_Nullable action, char const *_Nullable data) typedef
AIBinder *_Nullable(*
The function type signature definition of the "onBind" callback function called when someone is binding to the service, with the given action and data on the intent.
ANativeService_onDestroyCallback)(ANativeService *_Nonnull service) typedef
void(*
The function type signature definition of the "onDestroy" callback function called when the service is being destroyed.
ANativeService_onRebindCallback)(ANativeService *_Nonnull service, uint64_t bindToken) typedef
void(*
The function type signature definition of the "onRebind" callback function called when someone is rebinding to the service.
ANativeService_onTrimMemoryCallback)(ANativeService *_Nonnull service, ANativeServiceTrimMemoryLevel level) typedef
void(*
The function type signature definition of the "onTrimMemory" callback function called when the operating system has determined that it is a good time for a process to trim unneeded memory from its process.
ANativeService_onUnbindCallback)(ANativeService *_Nonnull service, uint64_t bindToken) typedef
bool(*
The function type signature definition of the "onUnbind" callback function called when all clients have disconnected from a particular interface published by the service.

Variables
ANativeService_onCreate
The default name of the entry point function.

Functions
ANativeService_setOnBindCallback(ANativeService *_Nonnull service, ANativeService_onBindCallback _Nonnull callback)
void
Sets the "onBind" callback function for the service.
ANativeService_setOnDestroyCallback(ANativeService *_Nonnull service, ANativeService_onDestroyCallback_Nullable callback)
void
Sets the "onDestroy" callback function for the service.
ANativeService_setOnRebindCallback(ANativeService *_Nonnull service, ANativeService_onRebindCallback_Nullable callback)
void
Sets the "onRebind" callback function for the service.
ANativeService_setOnTrimMemoryCallback(ANativeService *_Nonnull service, ANativeService_onTrimMemoryCallback_Nullable callback)
void
Sets the "onTrimMemory" callback function for the service.
ANativeService_setOnUnbindCallback(ANativeService *_Nonnull service, ANativeService_onUnbindCallback_Nullable callback)
void
Sets the "onUnbind" callback function for the service.

Enumerations

ANativeServiceTrimMemoryLevel

Declared in android/native_service.h 
 ANativeServiceTrimMemoryLevel

The levels for ANativeService_onTrimMemoryCallback indicating the context of the trim, giving a hint of the amount of trimming the application may like to perform.

Introduced in API 37.

Properties
ANATIVE_SERVICE_TRIM_MEMORY_BACKGROUND

The process has gone on to the LRU list.

This is a good opportunity to clean up resources that can efficiently and quickly be re-built if the user returns to the app.

Introduced in API 37.

ANATIVE_SERVICE_TRIM_MEMORY_UI_HIDDEN

The process had been showing a user interface, and is no longer doing so.

Large allocations with the UI should be released at this point to allow memory to be better managed.

Introduced in API 37.

Typedefs

ANativeService

Declared in android/native_service.h 
typedef__BEGIN_DECLS struct ANativeService ANativeService

An opaque struct representing a native service instance.

The framework creates a unique instance of this struct for each service. A handle to this same instance is passed to every callback function of the service.

Introduced in API 37.

ANativeServiceTrimMemoryLevel

Declared in android/native_service.h 
enum ANativeServiceTrimMemoryLevel ANativeServiceTrimMemoryLevel

The levels for ANativeService_onTrimMemoryCallback indicating the context of the trim, giving a hint of the amount of trimming the application may like to perform.

Introduced in API 37.

ANativeService_createFunc

Declared in android/native_service.h 
void ANativeService_createFunc(ANativeService *_Nonnull service)

The function type signature definition of the entry point function of the service.

service must be initialized in this function.

This function will run on the main thread of the process.

Introduced in API 37.

Details
Parameters
service
ANativeService associated with the service.

ANativeService_onBindCallback

Declared in android/native_service.h 
AIBinder *_Nullable(* ANativeService_onBindCallback)(ANativeService *_Nonnull service, uint64_t bindToken, char const *_Nullable action, char const *_Nullable data)

The function type signature definition of the "onBind" callback function called when someone is binding to the service, with the given action and data on the intent.

This may return NULL if clients cannot bind to the service, or a pointer to a valid AIBinder. If an AIBinder is returned, its ownership is transferred to the system, which is responsible for decrementing the reference count of the instance.

This callback function will run on the main thread of the process.

Introduced in API 37.

Details
Parameters
service
ANativeService associated with the service.
bindToken
A token representing this service binding. The same token is passed to onUnbind and onRebind callbacks to identify which binding triggered the callback.
action
The action specified in the intent passed to Context.bindService encoded as UTF-8 or null if not specified.
data
The data specified in the intent passed to Context.bindService. This is an encoded URI based on RFC 2396 using UTF-8 or null if not specified.
Returns
an AIBinder pointer through which clients can call on to the service. Ownership is transferred to the system.

ANativeService_onDestroyCallback

Declared in android/native_service.h 
void(* ANativeService_onDestroyCallback)(ANativeService *_Nonnull service)

The function type signature definition of the "onDestroy" callback function called when the service is being destroyed.

This callback function will run on the main thread of the process.

Introduced in API 37.

Details
Parameters
service
ANativeService associated with the service.

ANativeService_onRebindCallback

Declared in android/native_service.h 
void(* ANativeService_onRebindCallback)(ANativeService *_Nonnull service, uint64_t bindToken)

The function type signature definition of the "onRebind" callback function called when someone is rebinding to the service.

This callback is called only when onUnbind() returned true before.

This callback function will run on the main thread of the process.

Introduced in API 37.

Details
Parameters
service
ANativeService associated with the service.
bindToken
A token representing a service binding, which allows the callback to identify which binding triggered it.

ANativeService_onTrimMemoryCallback

Declared in android/native_service.h 
void(* ANativeService_onTrimMemoryCallback)(ANativeService *_Nonnull service, ANativeServiceTrimMemoryLevel level)

The function type signature definition of the "onTrimMemory" callback function called when the operating system has determined that it is a good time for a process to trim unneeded memory from its process.

You should never compare to exact values of the level, since new intermediate values may be added you will typically want to compare if the value is greater or equal to a level you are interested in.

This callback function will run on the main thread of the process.

Introduced in API 37.

Details
Parameters
service
ANativeService associated with the service.
level
ANativeServiceTrimMemoryLevel indicating the context of the trim, giving a hint of the amount of trimming the application may like to perform.

ANativeService_onUnbindCallback

Declared in android/native_service.h 
bool(* ANativeService_onUnbindCallback)(ANativeService *_Nonnull service, uint64_t bindToken)

The function type signature definition of the "onUnbind" callback function called when all clients have disconnected from a particular interface published by the service.

Return true if you would like to have the service's onRebind() method later called when new clients bind to it.

This callback function will run on the main thread of the process.

Introduced in API 37.

Details
Parameters
service
ANativeService associated with the service.
bindToken
A token representing a service binding, which allows the callback to identify which binding triggered it.
Returns
true if you would like to have the service's ANativeService_onRebindCallback callback later called when new clients bind to it, otherwise false.

Variables

ANativeService_onCreate

Declared in android/native_service.h 
ANativeService_createFunc ANativeService_onCreate

The default name of the entry point function.

You can specify a different function name through android.app.PROPERTY_NATIVE_SERVICE_FUNCTION_NAME property in your manifest.

Introduced in API 37.

Functions

ANativeService_setOnBindCallback

Declared in android/native_service.h 
void ANativeService_setOnBindCallback(
  ANativeService *_Nonnull service,
  ANativeService_onBindCallback _Nonnull callback
)

Sets the "onBind" callback function for the service.

Introduced in API 37.

Details
Parameters
service
ANativeService associated with the service.
callback
A pointer to an implementation of ANativeService_onBindCallback.

ANativeService_setOnDestroyCallback

Declared in android/native_service.h 
void ANativeService_setOnDestroyCallback(
  ANativeService *_Nonnull service,
  ANativeService_onDestroyCallback_Nullable callback
)

Sets the "onDestroy" callback function for the service.

If NULL is specified as the callback, then the system skips calling the callback when the event happens.

Introduced in API 37.

Details
Parameters
service
ANativeService associated with the service.
callback
A pointer to an implementation of ANativeService_onDestroyCallback.

ANativeService_setOnRebindCallback

Declared in android/native_service.h 
void ANativeService_setOnRebindCallback(
  ANativeService *_Nonnull service,
  ANativeService_onRebindCallback_Nullable callback
)

Sets the "onRebind" callback function for the service.

If NULL is specified as the callback, then the system skips calling the callback when the event happens.

Introduced in API 37.

Details
Parameters
service
ANativeService associated with the service.
callback
A pointer to an implementation ANativeService_onRebindCallback.

ANativeService_setOnTrimMemoryCallback

Declared in android/native_service.h 
void ANativeService_setOnTrimMemoryCallback(
  ANativeService *_Nonnull service,
  ANativeService_onTrimMemoryCallback_Nullable callback
)

Sets the "onTrimMemory" callback function for the service.

If NULL is specified as the callback, then the system skips calling the callback when the event happens.

Introduced in API 37.

Details
Parameters
service
ANativeService associated with the service.
callback
A pointer to an implementation of ANativeService_onTrimMemoryCallback.

ANativeService_setOnUnbindCallback

Declared in android/native_service.h 
void ANativeService_setOnUnbindCallback(
  ANativeService *_Nonnull service,
  ANativeService_onUnbindCallback_Nullable callback
)

Sets the "onUnbind" callback function for the service.

If NULL is specified as the callback, then the system runs the default implementation which does nothing and returns false.

Introduced in API 37.

Details
Parameters
service
ANativeService associated with the service.
callback
A pointer to an implementation of ANativeService_onUnbindCallback.