luna-service2 Library API Reference

API Summary

Luna-service2 (LS2) provides a bus-based IPC mechanism used between components in webOS. It is composed of:

Client library: Provides APIs to register a service on the Luna bus. Also, provides APIs for services to communicate with other components.
Central hub daemon: Provides a central clearing house for all communication. It includes utilities for monitoring and debugging the luna bus.

Overview of the API

Sample Client Usage (calling the 'listContacts()' method from a registered service):

bool retVal;
LSError lserror;
LSErrorInit (&lserror);
LSMessageToken token = LSMESSAGE_TOKEN_INVALID;
LSHandle *serviceHandle;
retVal = LSRegister (NULL, &serviceHandle, &lserror);
if (!retVal) goto done;
retVal = LSCallOneReply (serviceHandle, "luna://com.webos.contacts/category/listContacts","{\"json payload\"}", listContactsHandler, userData, &token, &lserror);
if (!retVal) goto done;
LSGmainAttach (serviceHandle, loop, &lserror);
g_main_loop_run(loop);

Sample Service Usage

//callback
static bool listContacts( LSHandle *sh, LSMessage *message, void *categoryContext)
{
bool retVal;
LSError lserror;
LSErrorInit (&lserror);
retVal = LSMessageReply (sh, message, "{JSON REPLY PAYLOAD}" , &lserror);
if (!retVal)
{
LSErrorPrint (&lserror, stderr);
LSErrorFree (&lserror);
}
return retVal;
}
static LSMethod ipcMethods[] = {
{ "listContacts" , listContacts },
{ },
};
bool retVal;
LSError lserror;
LSErrorInit (&lserror);
LSHandle *serviceHandle = NULL;
retVal = LSRegister ( "com.webos.contacts" , &serviceHandle, &lserror);
if (!retVal) goto error;

retVal = LSRegisterCategory (serviceHandle, "/category" , ipcMethods, NULL, NULL, &lserror);
if (!retVal) goto error;

retVal = LSCategorySetData (serviceHandle, "/category" , userData, &lserror);
if (!retVal) goto error;

retVal = LSGmainAttach (serviceHandle, mainLoop, &lserror);
if (!retVal) goto error;

g_main_loop_run(mainLoop);

Storing a message for replying in another thread.

Queue messageQueue;
...
static bool listContacts(LSHandle *sh, LSMessage *message)
{
bool retVal;
LSError lserror;
LSErrorInit (&lserror);
LSMessageRef (message);
queue (messageQueue, message);
}
...
void SomeOtherThread()
{
LSError lserror;
LSErrorInit (&lserror);
LSMessage *message = dequeue(messageQueue);
...
if (! LSMessageReply (sh, message, "{PAYLOAD IN JSON}" , lserror))
{
LSErrorLog (loggingCtx, msgId, &lserror);
LSErrorFree (&lserror);
}
....
}

Type Definitions

Alias	Type Definition	Description
_LSTransport	struct LSTransport	Indicates the transport object
_LSTransportMessage	struct LSTransportMessage	Indicates the underlying transport message.
LSMessageToken	unsigned long	Indicates the message token.
LSHandle	struct LSHandle	Indicates the handle to service
LSPalmService	struct LSPalmService	Indicates the handle to public service.
LSMethodFunction	bool()(LSHandle sh, LSMessage msg, void category_context)	Table registration of callbacks. sh: Indicates the handle to service msg: Indicates the message object category_context: Indicates the category context true: If message has been processed successfully. false: if some error has occurred and the user would like the callback to be called again later.
LSPropertyGetFunction	bool()(LSHandle sh, LSMessage msg, void category_context)	Indicates the type for property get callback. Returns same as LSMethodFunction() sh: Indicates the handle to service msg: Indicates the message object category_context: Indicates the category context
LSPropertySetFunction	bool()(LSHandle sh, LSMessage msg, void category_context)	Type for property set callback. Returns Same as LSMethodFunction() sh: Indicates the handle to service msg: Indicates the message object category_context: Indicates the category context
LSSubscriptionIter	struct LSSubscriptionIter	Iterator to iterate through the subscription for key
LSServerStatusFunc	bool()(LSHandle sh, const char serviceName, bool connected, void ctx)	Function callback to be called when serviceName connects or disconnects. Returns true on success, otherwise false sh: Indicates the service handle(LSHandle) serviceName: Indicates the name of the service that was brought up/down. connected: Indicates the service that was brought up if true.
LSFilterFunc	bool()(LSHandle sh, LSMessage reply, void ctx)	Callback function called on incoming message. Returns true if message is handled. sh: Indicates the service handle(LSHandle) reply: Indicates the incoming message void: * context
LSCancelNotificationFunc	bool()(LSHandle sh, const char uniqueToken, void ctx)	Indicates the function will be called when call originator cancels a call. Returns true if message is cancelled sh: Indicates the service handle(LSHandle) uniqueToken: Indicates the token of cancelled message. ctx: Indicates the context for function callback.
LSDisconnectHandler	void()(LSHandle sh, void *user_data)	Disconnection event observer
LSMessageToken	unsigned long	Indicates the message token.
LSHandle	struct LSHandle	Indicates the handle to service.
LSMethodFunction	bool()(LSHandle sh, LSMessage msg, void category_context)	Table registration of callbacks. sh: Indicates the handle to service msg: Indicates the message object category_context: Indicates the category context true: If message successfully processed. false: If some error occurred and you would like the callback to be called again later.
LSPropertyGetFunction	bool()(LSHandle sh, LSMessage msg, void category_context)	Indicates the type for property get callback. Returns same as LSMethodFunction() sh: Indicates the handle to service msg: Indicates the message object category_context: Indicates the category context
LSPropertySetFunction	bool()(LSHandle sh, LSMessage msg, void category_context)	Indicates the type for property set callback. Returns same as LSMethodFunction() sh: Indicates the handle to service msg: Indicates the message object category_context: Indicates the category context
LSServerStatusFunc	bool()(LSHandle sh, const char serviceName, bool connected, void ctx)	Indicates the function callback to be called when serviceName connects or disconnects. Returns true on success, otherwise false sh: Service handle(LSHandle) serviceName: Name of the service that was brought up/down. connected: Service was brought up if true.
LSFilterFunc	bool()(LSHandle sh, LSMessage reply, void ctx)	Indicates the callback function called on incoming message. Returns true if message is handled. sh: Indicates the service handle(LSHandle) reply: Indicates the incoming message void: * context
LSCancelNotificationFunc	bool()(LSHandle sh, const char uniqueToken, void ctx)	The function will be called when call originator cancels a call. Returns true if message is cancelled sh: Indicates the service handle(LSHandle) uniqueToken: Indicates the token of cancelled message. ctx: Indicates the context for function callback.

Enumerators

LSMethodFlags

Flags are used during method definition in a category. Can be used to enable incoming message validation against provided schema

LSSignalFlags

Flags are used during signal definition in a category. Can be used to mark signal as deprecated

LSPropertyFlags

Flags are used during property definition in a category. Can be used to mark property as deprecated

Methods

AddWatch

Description

Adds a watch to a channel and attach it to the main context.

Syntax

AddWatch(_LSTransportChannel * channel, GIOCondition condition, GMainContext * context, GIOFunc transport_cb, void * user_data, GDestroyNotify destroy_cb, GSource ** out_watch)

Parameters

Name	Required	Type	Description
channel	Required	_LSTransportChannel *	IN channel to watch
condition	Required	GIOCondition	IN condition to watch
context	Required	GMainContext *	IN main context
transport_cb	Required	GIOFunc	IN callback when watch is triggered
user_data	Required	void *	IN context passed to callback
destroy_cb	Required	GDestroyNotify	IN callback when watch is destroyed
out_watch	Required	GSource **	OUT newly created watch

Returns

None

Examples

None

LSCall

Description

Sends payload to service at the specified URI.

Special signals usage:

LSCall(sh, "luna://com.webos.service.bus/signal/registerServerStatus", "{"serviceName": "com.webos.media"}", callback, ctx, lserror);

LSCall(sh, "luna://com.webos.service.bus/signal/addmatch", "{"category": "/com/palm/power"," " "method": "shutdown"}", callback, ctx, lserror);

LSCall(sh, "luna://com.webos.service.bus/signal/addmatch", "{"category": "/com/palm/power"}", callback, ctx, lserror);

Syntax

LSCall(LSHandle * sh, const char * uri, const char * payload, LSFilterFunc callback, void * ctx, LSMessageToken * ret_token, LSError * lserror)

Parameters

Name	Required	Type	Description
sh	Required	LSHandle *	IN handle to service
uri	Required	const char *	IN fully qualified path to service's method
payload	Required	const char *	IN some string, usually following JSON object semantics.
callback	Required	LSFilterFunc	IN function callback to be called when responses arrive
ctx	Required	void *	IN user data to be passed to callback
ret_token	Required	LSMessageToken *	OUT token which identifies responses to this call
lserror	Required	LSError *	OUT set on error

Returns

Name	Required	Type	Description
retVal	Required	bool	Returns true on success, false on failure.

Examples

None

LSCallCancel

Description

Sends a cancel message to service to end call session and also unregisters any callback associated with call.

Syntax

LSCallCancel(LSHandle * sh, LSMessageToken token, LSError * lserror)

Parameters

Name	Required	Type	Description
sh	Required	LSHandle *	IN handle to service
token	Required	LSMessageToken	IN message token
lserror	Required	LSError *	OUT set on error

Returns

Name	Required	Type	Description
retVal	Required	bool	Returns true on success, false on failure.

Examples

None

LSCallCancelNotificationAdd

Description

Registers a callback to be called when remote service has canceled the call.

Note:

The callback is called when the client cancels a call via LSCallCancel().
The callback is called irrespective of a call being added to the subscription catalog or not. This is useful for a case when a notification needs to be received without adding subscribers to the catalog.
Unique token of a message and user context is passed to a function callback as arguments.
Users can register multiple callbacks, which are called in order of registration.

Syntax

LSCallCancelNotificationAdd(LSHandle * sh, LSCancelNotificationFunc cancelNotifyFunction, void * ctx, LSError * lserror)

Parameters

Name	Required	Type	Description
sh	Required	LSHandle *	IN handle to service
cancelNotifyFunction	Required	LSCancelNotificationFunc	IN callback function
ctx	Required	void *	IN user data to be passed to callback
lserror	Required	LSError *	OUT set on error

Returns

Name	Required	Type	Description
retVal	Required	bool	Returns true on success, false on failure.

Examples

None

LSCallCancelNotificationAdd

Description

Registers a callback to be called when remote service has canceled the call.

Note:

The callback is called when the client cancels a call via LSCallCancel().
The callback is called irrespective of a call being added to the subscription catalog or not. This is useful for a case when a notification needs to be received without adding subscribers to the catalog.
Unique token of a message and user context is passed to a function callback as arguments.
Users can register multiple callbacks, which are called in order of registration.

Syntax

LSCallCancelNotificationAdd(LSHandle * sh, LSCancelNotificationFunc cancelNotifyFunction, void * ctx, LSError * lserror)

Parameters

Name	Required	Type	Description
sh	Required	LSHandle *	IN handle to service
cancelNotifyFunction	Required	LSCancelNotificationFunc	IN callback function
ctx	Required	void *	IN user data to be passed to callback
lserror	Required	LSError *	OUT set on error

Returns

Name	Required	Type	Description
retVal	Required	bool	Returns true on success, false on failure.

Examples

None

LSCallCancelNotificationRemove

Description

Removes previously registered callback on call cancellation.

Note:

Function callback is removed from the list without changing relative order of other elements.
Both function callback and context should be the same as for registration.

Syntax

LSCallCancelNotificationRemove(LSHandle * sh, LSCancelNotificationFunc cancelNotifyFunction, void * ctx, LSError * lserror)

Parameters

Name	Required	Type	Description
sh	Required	LSHandle *	IN handle to service
cancelNotifyFunction	Required	LSCancelNotificationFunc	IN callback function
ctx	Required	void *	IN user data to be passed to callback
lserror	Required	LSError *	OUT set on error

Returns

Name	Required	Type	Description
retVal	Required	bool	Returns true on success, false on failure.

Examples

None

LSCallCancelNotificationRemove

Description

Removes previously registered callback on call cancellation.

Note:

Function callback is removed from the list without changing the relative order of other elements.
Both function callback and context should be the same as for registration.

Syntax

LSCallCancelNotificationRemove(LSHandle * sh, LSCancelNotificationFunc cancelNotifyFunction, void * ctx, LSError * lserror)

Parameters

Name	Required	Type	Description
sh	Required	LSHandle *	IN handle to service
cancelNotifyFunction	Required	LSCancelNotificationFunc	IN callback function
ctx	Required	void *	IN user data to be passed to callback
lserror	Required	LSError *	OUT set on error

Returns

Name	Required	Type	Description
retVal	Required	bool	Returns true on success, false on failure.

Examples

None

LSCallFromApplication

Description

A Special LSCall() that sends an application id.

Syntax

LSCallFromApplication(LSHandle * sh, const char * uri, const char * payload, const char * applicationID, LSFilterFunc callback, void * ctx, LSMessageToken * ret_token, LSError * lserror)

Parameters

Name	Required	Type	Description
sh	Required	LSHandle *	IN handle to service
uri	Required	const char *	IN fully qualified path to service's method
payload	Required	const char *	IN some string, usually following JSON object semantics
applicationID	Required	const char *	IN application id.
callback	Required	LSFilterFunc	IN function callback to be called when responses arrive.
ctx	Required	void *	IN user data to be passed to callback.
ret_token	Required	LSMessageToken *	OUT token which identifies responses to this call.
lserror	Required	LSError *	OUT set on error

Returns

Name	Required	Type	Description
retVal	Required	bool	Returns true on success, false on failure.

Examples

None

LSCallFromApplicationOneReply

Description

A special LSCallOneReply() that sends an application ID.

Syntax

LSCallFromApplicationOneReply(LSHandle * sh, const char * uri, const char * payload, const char * applicationID, LSFilterFunc callback, void * ctx, LSMessageToken * ret_token, LSError * lserror)

Parameters

Name	Required	Type	Description
sh	Required	LSHandle *	IN handle to service
uri	Required	const char *	IN fully qualified path to service's method
payload	Required	const char *	IN some string, usually following JSON object semantics
applicationID	Required	const char *	IN Application ID.
callback	Required	LSFilterFunc	IN function callback to be called when responses arrive
ctx	Required	void *	IN user data to be passed to callback
ret_token	Required	LSMessageToken *	OUT token which identifies responses to this call
lserror	Required	LSError *	OUT set on error

Returns

Name	Required	Type	Description
retVal	Required	bool	Returns true on success, false on failure.

Examples

None

LSCallOneReply

Description

Sends a message to service like LSCall().

Note: This method only accepts one response and does not need to be canceled via LSCallCancel().

Syntax

LSCallOneReply(LSHandle * sh, const char * uri, const char * payload, LSFilterFunc callback, void * ctx, LSMessageToken * ret_token, LSError * lserror)

Parameters

Name	Required	Type	Description
sh	Required	LSHandle *	IN Handle to service.
uri	Required	const char *	IN Fully qualified path to service's method.
payload	Required	const char *	IN Some string, usually following JSON object semantics.
callback	Required	LSFilterFunc	IN Function callback to be called when responses arrive.
ctx	Required	void *	IN User data to be passed to the callback.
ret_token	Required	LSMessageToken *	OUT Token which identifies responses to this call.
lserror	Required	LSError *	OUT Set on error.

Returns

Name	Required	Type	Description
retVal	Required	bool	Returns true on success, false on failure.

Examples

None

LSCallSetTimeout

Description

Sets timeout for a method call.

Note: The call is canceled if no reply is received after the timeout_ms milliseconds.

Syntax

LSCallSetTimeout(LSHandle * sh, LSMessageToken token, int timeout_ms, LSError * lserror)

Parameters

Name	Required	Type	Description
sh	Required	LSHandle *	IN handle to service
token	Required	LSMessageToken	IN message token
timeout_ms	Required	int	IN timeout in ms
lserror	Required	LSError *	OUT set on error

Returns

Name	Required	Type	Description
retVal	Required	bool	Returns true on success, false on failure.

Examples

None

LSCancelServerStatus

Description

Cancels receiving notifications about server status.

Note:

If unlikely false is returned, the subscription hasn't been canceled, and the associated memory hasn't been freed yet. This can happen if the system suffers from low memory.
The call can be repeated until true is returned. Once that happens, the value of the cookie is invalid, and should not be used.

Syntax

LSCancelServerStatus(LSHandle * sh, void * cookie, LSError * lserror)

Parameters

Name	Required	Type	Description
sh	Required	LSHandle *	IN handle to service
cookie	Required	void *	IN token obtained during registration, can't be NULL
lserror	Required	LSError *	OUT set on error

Returns

Name	Required	Type	Description
retVal	Required	bool	Returns true on success, false on failure.

Examples

None

LSCancelServerStatus

Description

Cancels receiving notifications about server status.

Note:

If unlikely false is returned, the subscription hasn't been canceled, and the associated memory hasn't been freed yet. This can happen if the system suffers from low memory.
The call can be repeated until true is returned. Once that happens, the value of the cookie is invalid, and should not be used.

Syntax

LSCancelServerStatus(LSHandle * sh, void * cookie, LSError * lserror)

Parameters

Name	Required	Type	Description
sh	Required	LSHandle *	IN handle to service
cookie	Required	void *	IN token obtained during registration, can't be NULL
lserror	Required	LSError *	OUT set on error

Returns

Name	Required	Type	Description
retVal	Required	bool	Returns true on success, false on failure.

Examples

None

LSCategorySetData

Description

Sets the user_data that is delivered to each callback registered to the category.

Note: If user_data is set using LSMethodSetData, it overrides category data.

Syntax

LSCategorySetData(LSHandle * sh, const char * category, void * user_data, LSError * lserror)

Parameters

Name	Required	Type	Description
sh	Required	LSHandle *	IN handle to service
category	Required	const char *	IN category name
user_data	Required	void *	IN user data to set
lserror	Required	LSError *	OUT set on error

Returns

Name	Required	Type	Description
retVal	Required	bool	Returns true on success, false on failure.

Examples

None

LSCategorySetDescription

Description

Specifies meta information about the category. Sets JSON value that describes specified category. Provides validation schema for input params and replies. Gives some description for calls and so on.

Note: Services with dynamically registered methods may wish to call this function after each LSRegisterCategoryAppend.

Syntax

LSCategorySetDescription(LSHandle * sh, const char * category, jvalue_ref description, LSError * error)

Parameters

Name	Required	Type	Description
sh	Required	LSHandle *	Indicates the handle that identifies the registered service on the bus.
category	Required	const char *	Indicates the identifier of the category this information provided for.
description	Required	jvalue_ref	Indicates information itself (no ownership transfer). See / category for example.
error	Required	LSError *	Indicates the output buffer for error description if applicable.

Returns

Name	Required	Type	Description
retVal	Required	bool	Returns false in case of error.

Examples

Example code

{
   // probably the easiest way is to load whole json and use specific parts
   // for specific categories
   "/" : {
       "definitions" : {
           "sender" : {
               "type" : "object" ,
               "properties" : {
                   "id" : { "type" : "string" },
                   "name" : { "type" : "string" },
                   "organization" : { "type" : "string" }
               },
               "required" : [ "id" ],
               "additionalProperties" : false
           },
           "messageInfo" : {
               "type" : "object" ,
               "properties" : {
                   "id" : "integer" ,
                   "sender" : { "$ref" : "#/definitions/sender" },
                   "subject" : { "type" : "string" }
               },
               "required" : [ "id" ],
               "additionalProperties" : false
           }
       },
       "methods" : {
           "leaveMessage" : {
               "call" : {
                   "type" : "object" ,
                   "properties" : {
                       "sender" : { "$ref" : "#/definitions/sender" },
                       "subject" : { "type" : "string" },
                       "body" : { "type" : "string" }
                   },
                   "additionalProperties" : false
               },
               "reply" : { // since "firstReply" ommited "reply" used for all answers
                   "type" : "integer" ,
                   "description" : "message id"
               }
           },
           "unreadMessages" : {
               "call" : {
                   "type" : "object" ,
                   "properties" : {
                       "lastId" : {
                           "type" : "integer" ,
                           "description" : "last read message id (0 if none)" ,
                           "default" : 0
                       }
                   },
                   "additionalProperties" : false
               },
               "firstReply" : { // first reply consist of bunch of messages since last request
                   "type" : "object" ,
                   "properties" : {
                       "unread" : {
                           "type" : "array" ,
                           "items" : { "$ref" : "#/definitions/messageInfo" }
                       },
                       "lastId" : { "type" : "integer" }
                   }
               },
               // further subscription replies are simply messageInfo's
               "reply" : { "$ref" : "#/definitions/messageInfo" },
           }
       }
   }
}

LSErrorFree

Description

Frees the internal structures of LSError if an error has been handled.

Note: This method must be called on an error if set.

Syntax

LSErrorFree(LSError * lserror)

Parameters

Name	Required	Type	Description
lserror	Required	LSError *	IN LSError structure to free

Returns

None

Examples

None

LSErrorInit

Description

Initializes a LSError.

Syntax

LSErrorInit(LSError * lserror)

Parameters

Name	Required	Type	Description
lserror	Required	LSError *	IN LSError structure to initialize

Returns

Name	Required	Type	Description
retVal	Required	bool	Returns true on success, false on failure.

Examples

None

LSErrorIsSet

Description

Checks the status of an LSError.

Syntax

LSErrorIsSet(LSError * lserror)

Parameters

Name	Required	Type	Description
lserror	Required	LSError *	IN LSError structure to check

Returns

Name	Required	Type	Description
retVal	Required	bool	Returns true if the LSError contains an error code/message.

Examples

None

LSErrorLog

Description

Logs an LSError with PmLogLib.

Syntax

LSErrorLog(PmLogContext context, const char * message_id, LSError * lserror)

Parameters

Name	Required	Type	Description
context	Required	PmLogContext	IN log context
message_id	Required	const char *	IN Message ID.
lserror	Required	LSError *	IN LSError structure to log

Returns

None

Examples

None

LSErrorLogDefault

Description

Logs an LSError by default.

Syntax

LSErrorLogDefault(const char * message_id, LSError * lserror)

Parameters

Name	Required	Type	Description
message_id	Required	const char *	IN Message ID.
lserror	Required	LSError *	IN LSError structure to log

Returns

None

Examples

None

LSErrorPrint

Description

Convenience function to print a LSError.

Syntax

LSErrorPrint(LSError * lserror, FILE * out)

Parameters

Name	Required	Type	Description
lserror	Required	LSError *	IN LSError structure to print
out	Required	FILE *	IN handle to file

Returns

None

Examples

None

LSGmainAttach

Description

Attaches a service to a Glib mainloop.

Syntax

LSGmainAttach(LSHandle * sh, GMainLoop * mainLoop, LSError * lserror)

Parameters

Name	Required	Type	Description
sh	Required	LSHandle *	IN handle to service
mainLoop	Required	GMainLoop *	IN loop to attach
lserror	Required	LSError *	OUT set on error

Returns

Name	Required	Type	Description
retVal	Required	bool	Returns true on success, false on failure.

Examples

None

LSGmainContextAttach

Description

Attaches a service to a GLib mainloop.

Syntax

LSGmainContextAttach(LSHandle * sh, GMainContext * mainContext, LSError * lserror)

Parameters

Name	Required	Type	Description
sh	Required	LSHandle *	IN handle to service
mainContext	Required	GMainContext *	IN context
lserror	Required	LSError *	OUT set on error

Returns

Name	Required	Type	Description
retVal	Required	bool	Returns true on success, false on failure.

Examples

None

LSGmainDetach

Description

Detaches a service from a GLib mainloop.

Note:

Never use this function unless you are fork()'ing without exec()'ing.
This will perform nearly all the same cleanup as LSUnregister(), with the exception that it will not send out shutdown messages or flush any buffers.
It is intended to be used only when fork()'ing so that your child process can continue without interfering with the parent's file descriptors, since open file descriptors are duplicated during a fork().

Syntax

LSGmainDetach(LSHandle * sh, LSError * lserror)

Parameters

Name	Required	Type	Description
sh	Required	LSHandle *	IN handle to service
lserror	Required	LSError *	OUT set on error

Returns

Name	Required	Type	Description
retVal	Required	bool	true on success, otherwise false

Examples

None

LSGmainGetContext

Description

Gets a GLib mainloop context for service.

Syntax

LSGmainGetContext(LSHandle * sh, LSError * lserror)

Parameters

Name	Required	Type	Description
sh	Required	LSHandle *	IN handle to service
lserror	Required	LSError *	OUT set on error

Returns

Name	Required	Type	Description
GMainContext *	Required	GMainContext *	Indicates the GMainContextglib mainloop context.

Examples

None

LSGmainSetPriority

Description

Sets the priority level on the associated GSources for the service connection.

Note:

This should be called after LSGmainAttach().
See GLib documentation for GSource priority levels.

Syntax

LSGmainSetPriority(LSHandle * sh, int priority, LSError * lserror)

Parameters

Name	Required	Type	Description
sh	Required	LSHandle *	IN handle to service
priority	Required	int	IN priority level
lserror	Required	LSError *	OUT set on error

Returns

Name	Required	Type	Description
retVal	Required	bool	Returns true on success, false on failure.

Examples

None

LSHandleGetName

Description

Returns the name of a luna service handle.

Syntax

LSHandleGetName(LSHandle * sh)

Parameters

Name	Required	Type	Description
sh	Required	LSHandle *	IN handle to service

Returns

None

Examples

None

LSIdleTimeout

Description

Registers a callback that will be called after certain milliseconds of inactivity specified by the timeout parameter.

Note:

Any stored LSMessage, active subscription (created by LSSubscriptionAdd) or message sent or received is considered as an activity. An exception is LSMessage marked as inactive with function LSMessageMarkInactive.
This function should be called before any LSRegister call.
This requirement is for ease of implementation and not enforced but strongly recommended.

Syntax

LSIdleTimeout(unsigned int timeout, void(*)(void *) callback, void * userdata, GMainContext * context)

Parameters

Name	Required	Type	Description
timeout	Required	unsigned int	IN time of inactivity (in ms) before callback invocation
callback	Required	void()(void )	IN user callback
userdata	Required	void *	IN user provided data, that will be passed into callback
context	Required	GMainContext *	IN context, which will be used to hold timer

Returns

None

Examples

Example code

void callBackFunc( void *data) { }

LSIdleTimeout (TIMEOUT, callBackFunc, loop, gMainContext);

LSRegister ( "com.name.service" , &lsHandle, &error);

LSIsRunning

Description

Checks if an instance of this executable is running.

Syntax

LSIsRunning(const char * pid_dir, const char * lock_file_name)

Parameters

Name	Required	Type	Description
pid_dir	Required	const char *	IN directory where the pid file should reside
lock_file_name	Required	const char *	IN file to be checked

Returns

retVal

Required

bool

Indicates the return value.

Possible values are:

true: Executable is running (matching pid file found).
false: Executable is not running.

Examples

None

LSLockFile

Description

Sets a lock on the specified file.

Syntax

LSLockFile(int fd)

Parameters

Name	Required	Type	Description
fd	Required	int	Indicates the file descriptor.

Returns

Name	Required	Type	Description
retVal	Required	bool	Returns true on success, false on failure.

Examples

None

LSMessageAccessPayload

Description

Gets the payload of this message.

Syntax

LSMessageAccessPayload(LSMessage * message)

Parameters

Name	Required	Type	Description
message	Required	LSMessage *	IN message

Returns

Name	Required	Type	Description
payload	Required	LSPayload *	Indicates the payload.

Examples

None

LSMessageGetApplicationID

Description

Obtains the application ID.

Note: This only applies to JS Applications' LSCallFromApplication().

Syntax

LSMessageGetApplicationID(LSMessage * message)

Parameters

Name	Required	Type	Description
message	Required	LSMessage *	IN message

Returns

Name	Required	Type	Description
app_id	Required	const char *	Indicates the application id.

Examples

None

LSMessageGetCategory

Description

Gets the category of this message.

Note: This method only applies to request messages on the service side like a method call, method cancel, signal call. It doesn't apply to response messages.

Syntax

LSMessageGetCategory(LSMessage * message)

Parameters

Name	Required	Type	Description
message	Required	LSMessage *	IN message

Returns

Name	Required	Type	Description
category	Required	const char *	Indicates the category name.

Examples

None

LSMessageGetConnection

Description

Returns a handle to the connection-to-bus through which the message was sent.

Syntax

LSMessageGetConnection(LSMessage * message)

Parameters

Name	Required	Type	Description
message	Required	LSMessage *	IN message

Returns

Name	Required	Type	Description
sh	Required	LSHandle *	Returns the handle to the connection-to-bus.

Examples

None

LSMessageGetFd

Description

Retrieves a message only if it contains an FD (file descriptor).

Syntax

LSMessageGetFd(LSMessage * message)

Parameters

Name	Required	Type	Description
message	Required	LSMessage *	IN message

Returns

Name	Required	Type	Description
int	Required	int	Returns file descriptor.

Examples

None

LSMessageGetKind

Description

Returns the kind of the message (category + method).

Syntax

LSMessageGetKind(LSMessage * message)

Parameters

Name	Required	Type	Description
message	Required	LSMessage *	IN message

Returns

Name	Required	Type	Description
message_kind	Required	const char *	Indicates the kind of the message.

Examples

None

LSMessageGetMethod

Description

Gets the method name of the message.

Note: This only applies to request messages on the service side like a method call, method cancel, signal call. It doesn't apply to response messages.

Syntax

LSMessageGetMethod(LSMessage * message)

Parameters

Name	Required	Type	Description
message	Required	LSMessage *	IN message

Returns

Name	Required	Type	Description
method	Required	const char *	Indicates the name of a method.

Examples

None

LSMessageGetPayload

Description

Gets the payload of the message.

Syntax

LSMessageGetPayload(LSMessage * message)

Parameters

Name	Required	Type	Description
message	Required	LSMessage *	IN message

Returns

Name	Required	Type	Description
payload	Required	const char *	Indicates the payload.

Examples

None

LSMessageGetResponseToken

Description

Gets the response token associated with the message that matches the LSMessageGetToken() of the original call.

Note: For signals, the response token is supplanted with the original token returned from LSSignalCall().

Syntax

LSMessageGetResponseToken(LSMessage * reply)

Parameters

Name	Required	Type	Description
reply	Required	LSMessage *	IN message

Returns

Name	Required	Type	Description
token	Required	LSMessageToken	Indicates the message token.

Examples

None

LSMessageGetSender

Description

Obtains a unique token identifying the sender.

Syntax

LSMessageGetSender(LSMessage * message)

Parameters

Name	Required	Type	Description
message	Required	LSMessage *	IN message

Returns

Name	Required	Type	Description
service_name	Required	const char *	Returns the sender's service_name.

Examples

None

LSMessageGetSenderServiceName

Description

Gets the name of the service that sent the message.

Note: This method returns NULL if the sender has not registered the service name.

Syntax

LSMessageGetSenderServiceName(LSMessage * message)

Parameters

Name	Required	Type	Description
message	Required	LSMessage *	IN message

Returns

Name	Required	Type	Description
service_name	Required	const char *	Returns the service_name if service sending the message has a name, NULL otherwise.

Examples

None

LSMessageGetToken

Description

Gets the unique serial of this message.

Note: Do not confuse with LSMessageGetResponseToken().

Syntax

LSMessageGetToken(LSMessage * message)

Parameters

Name	Required	Type	Description
message	Required	LSMessage *	IN message

Returns

Name	Required	Type	Description
token	Required	LSMessageToken	Indicates the message token.

Examples

None

LSMessageGetUniqueToken

Description

Returns a string that uniquely represents this message.

Syntax

LSMessageGetUniqueToken(LSMessage * message)

Parameters

Name	Required	Type	Description
message	Required	LSMessage *	IN message

Returns

Name	Required	Type	Description
token	Required	const char *	Indicates a unique token.

Examples

None

LSMessageIsHubErrorMessage

Description

Returns true if the message is an error message from the hub.

Syntax

LSMessageIsHubErrorMessage(LSMessage * message)

Parameters

Name	Required	Type	Description
message	Required	LSMessage *	IN message to chech

Returns

Name	Required	Type	Description
retVal	Required	bool	Returns true, if the error message is from the hub, false otherwise.

Examples

None

LSMessageIsSubscription

Description

Checks if the message has a subscription field with subscribe set as true.

Syntax

LSMessageIsSubscription(LSMessage * message)

Parameters

Name	Required	Type	Description
message	Required	LSMessage *	IN message

Returns

Name	Required	Type	Description
retVal	Required	bool	true if has subscribe=true, false otherwise

Examples

None

LSMessageMarkInactive

Description

Marks specific message as "weak" (no activity associated with it).

Note:

Marking the same LSMessage as inactive more than once is undefined behavior Message is treated as active by default.
Service with active messages(subscriptions) will not receive idle timeout callback.
Message marked as inactive does not prevent idle timeout from being called effectively prohibit treatment of this message presence as an activity on LS2 bus.

Syntax

LSMessageMarkInactive(LSMessage * message)

Parameters

Name	Required	Type	Description
message	Required	LSMessage *	IN message to mark it as "weak"

Returns

None

Examples

None

LSMessagePrint

Description

Convenience function to pretty print a message.

Syntax

LSMessagePrint(LSMessage * message, FILE * out)

Parameters

Name	Required	Type	Description
message	Required	LSMessage *	IN message to print
out	Required	FILE *	IN file to print

Returns

Name	Required	Type	Description
retVal	Required	bool	Returns true on success, false on failure.

Examples

None

LSMessageRef

Description

Increments ref count on the message object.

Note:

This method must be called only to store LSMessage internally.
A LSMessageRef() must be paired with a LSMessageUnref().

Syntax

LSMessageRef(LSMessage * message)

Parameters

Name	Required	Type	Description
message	Required	LSMessage *	IN message to ref

Returns

None

Examples

None

LSMessageReply

Description

Sends a reply to a message using the bus identified by LSHandle.

Note: To use the same bus upon which the message arrived, it is recommended to use LSMessageRespond().

Syntax

LSMessageReply(LSHandle * sh, LSMessage * lsmsg, const char * json, LSError * lserror)

Parameters

Name	Required	Type	Description
sh	Required	LSHandle *	IN handle to service
lsmsg	Required	LSMessage *	IN message
json	Required	const char *	IN JSON as payload
lserror	Required	LSError *	OUT set one error

Returns

Name	Required	Type	Description
retVal	Required	bool	Returns true on success, false on failure.

Examples

None

LSMessageRespond

Description

Sends a reply to the message using the same bus that had sent it.

Syntax

LSMessageRespond(LSMessage * message, const char * json, LSError * lserror)

Parameters

Name	Required	Type	Description
message	Required	LSMessage *	IN message
json	Required	const char *	IN payload to send
lserror	Required	LSError *	OUT set on error

Returns

Name	Required	Type	Description
retVal	Required	bool	Returns true on success, false on failure.

Examples

None

LSMessageRespondWithPayload

Description

Sends a reply to the message with a payload.

Syntax

LSMessageRespondWithPayload(LSMessage * message, LSPayload * payload, LSError * lserror)

Parameters

Name	Required	Type	Description
message	Required	LSMessage *	IN message
payload	Required	LSPayload *	IN payload to send
lserror	Required	LSError *	OUT set on error

Returns

Name	Required	Type	Description
retVal	Required	bool	Returns true on success, false on failure.

Examples

None

LSMessageUnref

Description

Decrements ref count on the message object.

Note: The object is freed if ref goes to zero.

Syntax

LSMessageUnref(LSMessage * message)

Parameters

Name	Required	Type	Description
message	Required	LSMessage *	IN message to unref

Returns

None

Examples

None

LSMethodSetData

Description

Sets the userdata that is delivered to callback registered to the method.

Note:

It's recommended to set method user data before method registration, otherwise, if mainloop is running, there is a chance to get callback called with category data.
Overrides category data as callback context.

Syntax

LSMethodSetData(LSHandle * sh, const char * category, const char * method, void * user_data, LSError * lserror)

Parameters

Name	Required	Type	Description
sh	Required	LSHandle *	IN handle to service
category	Required	const char *	IN category name
method	Required	const char *	IN method name
user_data	Required	void *	IN user data to set
lserror	Required	LSError *	OUT set on error

Returns

Name	Required	Type	Description
retVal	Required	bool	Returns true on success, false on failure.

Examples

None

LSPayloadAttachFd

Description

Attaches file descriptor to passed LSPayload.

Note: File descriptor should outlive created payload.

Syntax

LSPayloadAttachFd(LSPayload * payload, int fd)

Parameters

Name	Required	Type	Description
payload	Required	LSPayload *	Indicates a new LSPayload structure.
fd	Required	int	Indicates the file descriptor to be attached.

Returns

None

Examples

None

LSPayloadFree

Description

Contains LSPayloadFree() and its internal data.

Syntax

LSPayloadFree(LSPayload * payload)

Parameters

Name	Required	Type	Description
payload	Required	LSPayload *	Indicates a new LSPayload structure.

Returns

None

Examples

None

LSPayloadFromData

Description

Creates the LSPayload from the binary data.

Note: Binary data should outlive created payload.

Syntax

LSPayloadFromData(const char * type, void * ptr, size_t size)

Parameters

Name	Required	Type	Description
type	Required	const char *	Indicates the string identifier of the binary data type.
ptr	Required	void *	Indicates the data pointer.
size	Required	size_t	Indicates the size of the binary data.

Returns

Name	Required	Type	Description
LSPayload *	Required	LSPayload *	Indicates a new LSPayload structure.

Examples

None

LSPayloadFromJson

Description

Creates the LSPayload from the string.

Note: String should outlive created payload.

Syntax

LSPayloadFromJson(const char * json)

Parameters

Name	Required	Type	Description
json	Required	const char *	Indicates the string representation of the JSON.

Returns

Name	Required	Type	Description
LSPayload *	Required	LSPayload *	Indicates a new LSPayload structure.

Examples

None

LSPayloadFromJValue

Description

Creates an LSPayload from jvalue.

Note: jvalue should outlive created payload.

Syntax

LSPayloadFromJValue(jvalue_ref value)

Parameters

Name	Required	Type	Description
value	Required	jvalue_ref	Indicates the pbnjson representation of the JSON.

Returns

Name	Required	Type	Description
LSPayload *	Required	LSPayload *	Indicates a new LSPayload structure.

Examples

None

LSPayloadGetData

Description

Gets the raw LSPayload data.

Syntax

LSPayloadGetData(const LSPayload * payload, size_t * size)

Parameters

Name	Required	Type	Description
payload	Required	const LSPayload *	Indicates a new LSPayload structure.
size	Required	size_t *	Indicates a pointer to size_t in which size of data will be stored.

Returns

Name	Required	Type	Description
ptr	Required	void *	Pointer to data.

Examples

None

LSPayloadGetDataType

Description

Gets the string identifier of LSPayload data.

Syntax

LSPayloadGetDataType(const LSPayload * payload)

Parameters

Name	Required	Type	Description
payload	Required	const LSPayload *	Indicates a new LSPayload structure.

Returns

Name	Required	Type	Description
const char *	Required	const char *	Indicates the string identifier.

Examples

None

LSPayloadGetFd

Description

Gets the file descriptor attached to passed LSPayload.

Syntax

LSPayloadGetFd(const LSPayload * payload)

Parameters

Name	Required	Type	Description
payload	Required	const LSPayload *	Indicates a new LSPayload structure.

Returns

Name	Required	Type	Description
fd	Required	int	Returns file descriptor if attached or -1 if file descriptor is not attached.

Examples

None

LSPayloadGetJson

Description

Gets the string representation of JSON in LSPayload.

Syntax

LSPayloadGetJson(const LSPayload * payload)

Parameters

Name	Required	Type	Description
payload	Required	const LSPayload *	Indicates a new LSPayload structure.

Returns

Name	Required	Type	Description
const char *	Required	const char *	Indicates that the JSON string or the NULL if string cannot be retrieved

Examples

None

LSPayloadGetJValue

Description

Gets the jvalue_ref representation of JSON in LSPayload.

Syntax

LSPayloadGetJValue(const LSPayload * payload)

Parameters

Name	Required	Type	Description
payload	Required	const LSPayload *	Indicates a new LSPayload structure.

Returns

Name	Required	Type	Description
jvalue_ref	Required	jvalue_ref	Indicates that the jvalue_ref or NULL if jvalue_ref cannot be retrieved.

Examples

None

LSPushRole

Description

Pushes a role file for this process.

Note: Once the role file has been pushed with this function, the process will be restricted to the constraints of the provided role file.

Syntax

LSPushRole(LSHandle * sh, const char * role_path, LSError * lserror)

Parameters

Name	Required	Type	Description
sh	Required	LSHandle *	IN handle (already connected with LSRegister())
role_path	Required	const char *	IN full path to role file
lserror	Required	LSError *	OUT set on error

Returns

Name	Required	Type	Description
retVal	Required	bool	Returns true on success, false on failure.

Examples

None

LSRegister

Description

Registers a service on the private bus.

Note:

Services may make outgoing service calls using LSCall() or handle incoming messages for handlers registered via LSRegisterCategory(), and send replies via LSMessageReply() or LSSubscriptionPost().
A traditional client may register with a NULL name if it never expects to be sent messages.

Syntax

LSRegister(const char * name, LSHandle ** sh, LSError * lserror)

Parameters

Name	Required	Type	Description
name	Required	const char *	IN service name
sh	Required	LSHandle **	IN handle to service
lserror	Required	LSError *	OUT set on error

Returns

Name	Required	Type	Description
retVal	Required	bool	Returns true on success, false on failure.

Examples

None

LSRegisterApplicationService

Description

Registers a service on the private bus with the application id.

For details see LSRegister description.

Syntax

LSRegisterApplicationService(const char * name, const char * app_id, LSHandle ** sh, LSError * lserror)

Parameters

Name	Required	Type	Description
name	Required	const char *	IN service name
app_id	Required	const char *	IN application Id
sh	Required	LSHandle **	IN handle to service
lserror	Required	LSError *	OUT set on error

Returns

Name	Required	Type	Description
retVal	Required	bool	Returns true on success, false on failure.

Examples

None

LSRegisterCategory

Description

Registers tables of callbacks associated with the message category.

Syntax

LSRegisterCategory(LSHandle * sh, const char * category, LSMethod * methods, LSSignal * signals, LSProperty * properties, LSError * lserror)

Parameters

Name	Required	Type	Description
sh	Required	LSHandle *	IN handle to service
category	Required	const char *	IN may be NULL for default '/' category.
methods	Required	LSMethod *	IN table of methods.
signals	Required	LSSignal *	IN table of signals.
properties	Required	LSProperty *	IN table of properties.
lserror	Required	LSError *	OUT set on error

Returns

Name	Required	Type	Description
retVal	Required	bool	Returns true on success, false on failure.

Examples

None

LSRegisterCategoryAppend

Description

Appends methods to the category. Creates a category if needed.

Syntax

LSRegisterCategoryAppend(LSHandle * sh, const char * category, LSMethod * methods, LSSignal * signals, LSError * lserror)

Parameters

Name	Required	Type	Description
sh	Required	LSHandle *	IN handle to service
category	Required	const char *	IN category name
methods	Required	LSMethod *	IN array of methods
signals	Required	LSSignal *	IN array of signals
lserror	Required	LSError *	OUT set on error

Returns

Name	Required	Type	Description
retVal	Required	bool	Returns true on success, false on failure.

Examples

None

LSRegisterServerStatusEx

Description

Registers a callback to be called when the server goes up or comes down. Performs LSCall(sh, "luna://com.webos.service.bus/signal/registerServerStatus").

Note: Callback may be called in this context if the server is already up.

Syntax

LSRegisterServerStatusEx(LSHandle * sh, const char * serviceName, LSServerStatusFunc func, void * ctxt, void ** cookie, LSError * lserror)

Parameters

Name	Required	Type	Description
sh	Required	LSHandle *	IN handle to service
serviceName	Required	const char *	IN service name to monitor for connect/disconnect.
func	Required	LSServerStatusFunc	IN function callback
ctxt	Required	void *	IN context
cookie	Required	void **	OUT token to use for to unregister the callback
lserror	Required	LSError *	OUT set on error

Returns

Name	Required	Type	Description
retVal	Required	bool	Returns true on success, false on failure.

Examples

None

LSRegisterServerStatusEx

Description

Registers a callback to be called when the server goes up or comes down. Performs LSCall(sh, "luna://com.webos.service.bus/signal/registerServerStatus").

Note: Callback may be called in this context if the server is already up.

Syntax

LSRegisterServerStatusEx(LSHandle * sh, const char * serviceName, LSServerStatusFunc func, void * ctx, void ** cookie, LSError * lserror)

Parameters

Name	Required	Type	Description
sh	Required	LSHandle *	IN handle to service
serviceName	Required	const char *	IN service name to monitor for connect/disconnect.
func	Required	LSServerStatusFunc	IN function callback
ctx	Required	void *	IN user data to be passed to callback
cookie	Required	void **	OUT token to use for to unregister the callback
lserror	Required	LSError *	OUT set on error

Returns

Name	Required	Type	Description
retVal	Required	bool	Returns true on success, false on failure.

Examples

None

LSSetDisconnectHandler

Description

Sets a function to be called if disconnected from the bus.

Syntax

LSSetDisconnectHandler(LSHandle * sh, LSDisconnectHandler disconnect_handler, void * user_data, LSError * lserror)

Parameters

Name	Required	Type	Description
sh	Required	LSHandle *	IN handle to service
disconnect_handler	Required	LSDisconnectHandler	IN function callback
user_data	Required	void *	IN user data to be passed to callback
lserror	Required	LSError *	OUT set on error

Returns

Name	Required	Type	Description
retVal	Required	bool	Returns true on success, false on failure.

Examples

None

LSSignalSend

Description

Sends a signal.

Syntax

LSSignalSend(LSHandle * sh, const char * uri, const char * payload, LSError * lserror)

Parameters

Name	Required	Type	Description
sh	Required	LSHandle *	IN handle to service
uri	Required	const char *	IN fully qualified path to service's method
payload	Required	const char *	IN some string, usually following JSON object semantics
lserror	Required	LSError *	OUT set on error

Returns

Name	Required	Type	Description
retVal	Required	bool	Returns true on success, false on failure.

Examples

None

LSSubscriptionAcquire

Description

Acquires an iterator to iterate through the subscription for 'key'.

Syntax

LSSubscriptionAcquire(LSHandle * sh, const char * key, LSSubscriptionIter ** ret_iter, LSError * lserror)

Parameters

Name	Required	Type	Description
sh	Required	LSHandle *	IN handle to service
key	Required	const char *	IN key
ret_iter	Required	LSSubscriptionIter **	OUT Iterator to iterate through the subscription for key
lserror	Required	LSError *	OUT set on error

Returns

Name	Required	Type	Description
retVal	Required	bool	Returns true on success, false on failure.

Examples

None

LSSubscriptionAdd

Description

Adds a subscription to a list associated with 'key'.

Note: The call may fail if the client has been disconnected. However, if the call succeeds, the code can install callback to get notification about client
disconnection or call cancel via LSSubscriptionSetCancelFunction().

Syntax

LSSubscriptionAdd(LSHandle * sh, const char * key, LSMessage * message, LSError * lserror)

Parameters

Name	Required	Type	Description
sh	Required	LSHandle *	IN handle to service
key	Required	const char *	IN key
message	Required	LSMessage *	IN message object
lserror	Required	LSError *	OUT set on error

Returns

Name	Required	Type	Description
retVal	Required	bool	Returns true on success, false on failure.

Examples

None

LSSubscriptionGetHandleSubscribersCount

Description

Returns number of subscribers with name 'key'.

Note:

LSSubscriptionReply has no overhead for empty subscribers list.
Function can be used to avoid LSSubscriptionIter or payload creation.

Syntax

LSSubscriptionGetHandleSubscribersCount(LSHandle * sh, const char * key)

Parameters

Name	Required	Type	Description
sh	Required	LSHandle *	IN handle to service
key	Required	const char *	IN key

Returns

Name	Required	Type	Description
subscriber_count	Required	unsigned int	Indicates unsigned int, number of subscribers.

Examples

None

LSSubscriptionHasNext

Description

Returns whether there is a next item in subscription.

Syntax

LSSubscriptionHasNext(LSSubscriptionIter * iter)

Parameters

Name	Required	Type	Description
iter	Required	LSSubscriptionIter *	IN Subscription iterator to check

Returns

Name	Required	Type	Description
retVal	Required	bool	Returns true on success, false on failure.

Examples

None

LSSubscriptionNext

Description

Obtains the next subscription message.

Syntax

LSSubscriptionNext(LSSubscriptionIter * iter)

Parameters

Name	Required	Type	Description
iter	Required	LSSubscriptionIter *	IN Subscription iterator to obtain from

Returns

Name	Required	Type	Description
LSMessage *	Required	LSMessage *	LSMessage subscription message

Examples

None

LSSubscriptionProcess

Description

Adds the message to the subscription list using the default key '/category/method', if the message contains subscribe: true.

Note: This is equivalent to LSSubscriptionAdd(sh, key, message, lserror) where the key is LSMessageGetKind(message).

Syntax

LSSubscriptionProcess(LSHandle * sh, LSMessage * message, bool * subscribed, LSError * lserror)

Parameters

Name	Required	Type	Description
sh	Required	LSHandle *	IN service handle
message	Required	LSMessage *	IN message object
subscribed	Required	bool *	OUT flag to check if subscribed
lserror	Required	LSError *	OUT set on error

Returns

Name	Required	Type	Description
retVal	Required	bool	Returns true on success, false on failure.

Examples

None

LSSubscriptionRelease

Description

Frees up resources for LSSubscriptionIter.

Syntax

LSSubscriptionRelease(LSSubscriptionIter * iter)

Parameters

Name	Required	Type	Description
iter	Required	LSSubscriptionIter *	IN Subscription iterator to free

Returns

None

Examples

None

LSSubscriptionRemove

Description

Removes the last subscription returned by LSSubscriptionNext().

Syntax

LSSubscriptionRemove(LSSubscriptionIter * iter)

Parameters

Name	Required	Type	Description
iter	Required	LSSubscriptionIter *	IN Subscription iterator

Returns

None

Examples

None

LSSubscriptionReply

Description

Sends a message to subscription list with name 'key'.

Syntax

LSSubscriptionReply(LSHandle * sh, const char * key, const char * payload, LSError * lserror)

Parameters

Name	Required	Type	Description
sh	Required	LSHandle *	IN handle to service
key	Required	const char *	IN key
payload	Required	const char *	IN some string, usually following JSON object semantics
lserror	Required	LSError *	OUT set on error

Returns

Name	Required	Type	Description
retVal	Required	bool	Returns true on success, false on failure.

Examples

None

LSSubscriptionSetCancelFunction

Description

Registers a callback to be called when the subscription is canceled.

Note:

The callback service may be called when the client cancels subscription via LSCallCancel() or if the client drops off the bus.
The callback service will not be called if LSSubscriptionAdd() failed for any reason.

Syntax

LSSubscriptionSetCancelFunction(LSHandle * sh, LSFilterFunc cancelFunction, void * ctx, LSError * lserror)

Parameters

Name	Required	Type	Description
sh	Required	LSHandle *	IN handle to service
cancelFunction	Required	LSFilterFunc	IN callback function
ctx	Required	void *	IN user data to be passed to callback
lserror	Required	LSError *	OUT set on error

Returns

Name	Required	Type	Description
retVal	Required	bool	Returns true on success, false on failure.

Examples

None

LSUnregister

Description

Unregisters a service.

Syntax

LSUnregister(LSHandle * sh, LSError * lserror)

Parameters

Name	Required	Type	Description
sh	Required	LSHandle *	IN handle to service
lserror	Required	LSError *	OUT set on error

Returns

Name	Required	Type	Description
retVal	Required	bool	Returns true on success, false on failure.

Examples

None

RemoveWatch

Description

Removes a watch from a channel.

Syntax

RemoveWatch(_LSTransportChannel * channel, GSource ** out_watch)

Parameters

Name	Required	Type	Description
channel	Required	_LSTransportChannel *	IN channel that watch is on
out_watch	Required	GSource **	IN/OUT watch (set to NULL after destroying)

Returns

None

Examples

None

LSMessageGetSenderExePath

Description

Gets the executable path of the sender that sent the message.

Syntax

LSMessageGetSenderExePath(char message)

Parameters

Name	Required	Type	Description
message	Required	char	IN message

Returns

Name	Required	Type	Description
exe_path	Required	const char *	exe_path of the sender

Examples

None

LSCallProxy

Description

Sends payload to service at the specified URI.

This API facilitates proxy luna calls.

Note: It is valid only for services that wish to act as mediators.

Syntax

LSCallProxy(typedef LSHandle sh, const char * callee_exe, const char * callee_id	, const char * callee_name, const char * uri, const char * payload, typedef LSFilterFunc callback, void * ctx, typedef LSMessageToken ret_token, struct LSError * lserror)

Parameters

Name	Required	Type	Description
sh	Required	typedef LSHandle	In handle
callee_exe	Required	const char *	IN absolute exe path of callee, if callee is service else NULL
callee_id	Required	const char *	IN app_id of the callee, if callee is app else NULL
callee_name	Required	const char *	IN service name of the callee, NULL not accepted
uri	Required	const char *	IN fully qualified path to service's method
payload	Required	const char *	IN some string, usually following JSON object semantics
callback	Required	typedef LSFilterFunc	IN function callback to be called when responses arrive
ctx	Required	void *	IN user data to be passed to callback
ret_token	Required	typedef LSMessageToken	OUT token which identifies responses to this call
lserror	Required	struct LSError *	OUT set on error

Returns

Name	Required	Type	Description
retVal	Required	bool	true on success, otherwise false

Examples

None

LSCallProxyOneReply

Description

Sends payload to service at the specified URI as callee source.

This API facilitates proxy luna calls and only accepts one response.

Note: It is valid only for services that wish to act as mediators.

Syntax

LSCallProxyOneReply(typedef LSHandle sh, const char * callee_exe, const char * callee_id, const char * callee_name, const char * uri, const char * payload, typedef LSFilterFunc callback, void * ctx, typedef LSMessageToken ret_token, struct LSError * lserror)

Parameters

Name	Required	Type	Description
sh	Required	typedef LSHandle	IN Handle.
callee_exe	Required	const char *	IN absolute exe path of callee, if callee is service else NULL
callee_id	Required	const char *	IN app_id of the callee, if callee is app else NULL
callee_name	Required	const char *	IN service name of the callee, NULL not accepted
uri	Required	const char *	IN fully qualified path to service's method
payload	Required	const char *	IN some string, usually following JSON object semantics
callback	Required	typedef LSFilterFunc	IN function callback to be called when responses arrive
ctx	Required	void *	IN user data to be passed to callback
ret_token	Required	typedef LSMessageToken	OUT token which identifies responses to this call
lserror	Required	struct LSError *	OUT set on error

Returns

Name	Required	Type	Description
retVal	Required	bool	true on success, otherwise false

Examples

None

LSCallProxyFromApplication

Description

Sends payload to service at the specified URI as callee source.

This API facilitates proxy luna calls from the application.

Note: It is valid only for apps that wish to act as mediators.

Syntax

LSCallProxyFromApplication(typedef LSHandle sh, const char * callee_exe, const char * callee_id, const char * callee_name, const char * uri, const char * payload, const char * applicationID, typedef LSFilterFunc callback, void * ctx, typedef LSMessageToken ret_token, struct LSError * lserror)

Parameters

Name	Required	Type	Description
sh	Required	typedef LSHandle	IN handle
callee_exe	Required	const char *	IN absolute exe path of callee, if callee is service else NULL
callee_id	Required	const char *	IN app_id of the callee, if callee is app else NULL
callee_name	Required	const char *	IN service name of the callee, NULL not accepted
uri	Required	const char *	IN fully qualified path to service's method
payload	Required	const char *	IN some string, usually following JSON object semantics
applicationID	Required	const char *	IN Application ID.
callback	Required	typedef LSFilterFunc	IN function callback to be called when responses arrive
ctx	Required	void *	IN user data to be passed to callback
ret_token	Required	typedef LSMessageToken	OUT token which identifies responses to this call
lserror	Required	struct LSError *	OUT set on error

Returns

Name	Required	Type	Description
retVal	Required	bool	true on success, otherwise false

Examples

None

LSCallProxyFromApplicationOneReply

Description

Sends payload to service at the specified URI as callee source.

This API facilitates proxy luna calls from the application and only accepts one response.

Note: It is valid only for apps that wish to act as mediators.

Syntax

LSCallProxyFromApplicationOneReply(typedef LSHandle sh, const char * callee_exe, const char * callee_id, const char * callee_name, const char * uri, const char * payload, const char * applicationID, typedef LSFilterFunc callback, void * ctx, typedef LSMessageToken ret_token, struct LSError * lserror)

Parameters

Name	Required	Type	Description
sh	Required	typedef LSHandle	IN handle
callee_exe	Required	const char *	IN absolute exe path of callee, if callee is service else NULL
callee_id	Required	const char *	IN app_id of the callee, if callee is app else NULL
callee_name	Required	const char *	IN service name of the callee, NULL not accepted
uri	Required	const char *	IN fully qualified path to service's method
payload	Required	const char *	IN some string, usually following JSON object semantics.
applicationID	Required	const char *	IN Application ID.
callback	Required	typedef LSFilterFunc	IN function callback to be called when responses arrive
ctx	Required	void *	IN user data to be passed to callback
ret_token	Required	typedef LSMessageToken	OUT token which identifies responses to this call
lserror	Required	struct LSError *	OUT set on error

Returns

Name	Required	Type	Description
retVal	Required	bool	true on success, otherwise false

Examples

None

LSMessageGetSenderTrustLevel

Description

Gets the trust level of the sender of the message.

Syntax

LSMessageGetSenderTrustLevel(struct LSMessage * message)

Parameters

Name	Required	Type	Description
message	Required	struct LSMessage *	IN message

Returns

Name	Required	Type	Description
trustLevel	Required	const char *	Trust level of the sender.

Examples

None