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 clearinghouse for all communication. It includes utilities for monitoring and debugging the 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

_LSTransportstruct LSTransport

Indicates the transport object

_LSTransportMessagestruct LSTransportMessage

Indicates the underlying transport message.

LSMessageTokenunsigned long

Indicates the message token.

LSHandlestruct LSHandle

Indicates the handle to service

LSPalmServicestruct LSPalmService

Indicates the handle to public service.

LSMethodFunctionbool(*)(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.
LSPropertyGetFunctionbool(*)(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 
LSPropertySetFunctionbool(*)(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
LSSubscriptionIterstruct LSSubscriptionIter

Iterator to iterate through the subscription for key

LSServerStatusFuncbool(*)(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.
LSFilterFuncbool(*)(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
LSCancelNotificationFuncbool(*)(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.
LSDisconnectHandlervoid(*)(LSHandle *sh, void *user_data)

Disconnection event observer

LSMessageTokenunsigned long

Indicates the message token.

LSHandlestruct LSHandle

Indicates the handle to service.

LSMethodFunctionbool(*)(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.
LSPropertyGetFunctionbool(*)(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
LSPropertySetFunctionbool(*)(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
LSServerStatusFuncbool(*)(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.
LSFilterFuncbool(*)(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
LSCancelNotificationFuncbool(*)(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

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

channelRequired_LSTransportChannel *IN channel to watch
conditionRequiredGIOConditionIN condition to watch
contextRequiredGMainContext *IN main context
transport_cbRequiredGIOFuncIN callback when watch is triggered
user_dataRequiredvoid *IN context passed to callback
destroy_cbRequiredGDestroyNotifyIN callback when watch is destroyed
out_watchRequiredGSource **OUT newly created watch

Returns

None

Examples

None

LSCall

Description

Sends payload to service at the specified URI.

Special signals usage:

Register for any ServerStatus signals:

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

Register for any signals from (category, method):

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

Register for any signals from category:

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

shRequiredLSHandle *IN handle to service
uriRequiredconst char *IN fully qualified path to service's method
payloadRequiredconst char *IN some string, usually following json object semantics
callbackRequiredLSFilterFuncIN function callback to be called when responses arrive
ctxRequiredvoid *IN user data to be passed to callback
ret_tokenRequiredLSMessageToken *OUT token which identifies responses to this call
lserrorRequiredLSError *OUT set on error

Returns

Name

Required

Type

Description

retValRequiredbool

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

shRequiredLSHandle *IN handle to service
tokenRequiredLSMessageTokenIN message token
lserrorRequiredLSError *OUT set on error

Returns

Name

Required

Type

Description

retValRequiredbool

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

shRequiredLSHandle *IN handle to service
cancelNotifyFunctionRequiredLSCancelNotificationFuncIN callback function
ctxRequiredvoid *IN user data to be passed to callback
lserrorRequiredLSError *OUT set on error

Returns

Name

Required

Type

Description

retValRequiredbool

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

shRequiredLSHandle *IN handle to service
cancelNotifyFunctionRequiredLSCancelNotificationFuncIN callback function
ctxRequiredvoid *IN user data to be passed to callback
lserrorRequiredLSError *OUT set on error

Returns

Name

Required

Type

Description

retValRequiredbool

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

shRequiredLSHandle *IN handle to service
cancelNotifyFunctionRequiredLSCancelNotificationFuncIN callback function
ctxRequiredvoid *IN user data to be passed to callback
lserrorRequiredLSError *OUT set on error

Returns

Name

Required

Type

Description

retValRequiredbool

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

shRequiredLSHandle *IN handle to service
cancelNotifyFunctionRequiredLSCancelNotificationFuncIN callback function
ctxRequiredvoid *IN user data to be passed to callback
lserrorRequiredLSError *OUT set on error

Returns

Name

Required

Type

Description

retValRequiredbool

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

shRequiredLSHandle *IN handle to service
uriRequiredconst char *IN fully qualified path to service's method
payloadRequiredconst char *IN some string, usually following json object semantics
applicationIDRequiredconst char *

IN application ID.

callbackRequiredLSFilterFunc

IN function callback to be called when responses arrive.

ctxRequiredvoid *

IN user data to be passed to callback.

ret_tokenRequiredLSMessageToken *

OUT token which identifies responses to this call.

lserrorRequiredLSError *OUT set on error

Returns

Name

Required

Type

Description

retValRequiredbool

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

shRequiredLSHandle *

IN handle to service

uriRequiredconst char *

IN fully qualified path to service's method

payloadRequiredconst char *IN some string, usually following json object semantics
applicationIDRequiredconst char *IN application id
callbackRequiredLSFilterFuncIN function callback to be called when responses arrive
ctxRequiredvoid *IN user data to be passed to callback
ret_tokenRequiredLSMessageToken *OUT token which identifies responses to this call
lserrorRequiredLSError *OUT set on error

Returns

Name

Required

Type

Description

retValRequiredbool

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

shRequiredLSHandle *

IN Handle to service.

uriRequiredconst char *

IN Fully qualified path to service's method.

payloadRequiredconst char *

IN Some string, usually following json object semantics.

callbackRequiredLSFilterFunc

IN Function callback to be called when responses arrive.

ctxRequiredvoid *

IN User data to be passed to the callback.

ret_tokenRequiredLSMessageToken *

OUT Token which identifies responses to this call.

lserrorRequiredLSError *

OUT Set on error.

Returns

Name

Required

Type

Description

retValRequiredbool

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

shRequiredLSHandle *IN handle to service
tokenRequiredLSMessageTokenIN message token
timeout_msRequiredintIN timeout in ms
lserrorRequiredLSError *OUT set on error

Returns

Name

Required

Type

Description

retValRequiredbool

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

shRequiredLSHandle *IN handle to service
cookieRequiredvoid *IN token obtained during registration, can't be NULL
lserrorRequiredLSError *OUT set on error

Returns

Name

Required

Type

Description

retValRequiredbool

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

shRequiredLSHandle *IN handle to service
cookieRequiredvoid *IN token obtained during registration, can't be NULL
lserrorRequiredLSError *OUT set on error

Returns

Name

Required

Type

Description

retValRequiredbool

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

shRequiredLSHandle *IN handle to service
categoryRequiredconst char *IN category name
user_dataRequiredvoid *IN user data to set
lserrorRequiredLSError *OUT set on error

Returns

Name

Required

Type

Description

retValRequiredbool

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

shRequiredLSHandle *

Indicates the handle that identifies the registered service on the bus.

categoryRequiredconst char *

Indicates the identifier of the category this information provided for.

descriptionRequiredjvalue_ref

Indicates information itself (no ownership transfer). See / category for example.

errorRequiredLSError *

Indicates the output buffer for error description if applicable.

Returns

Name

Required

Type

Description

retValRequiredbool

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

lserrorRequiredLSError *IN LSError structure to free

Returns

None

Examples

None

LSErrorInit

Description

Initializes a LSError.

Syntax

LSErrorInit(LSError * lserror)

Parameters

Name

Required

Type

Description

lserrorRequiredLSError *IN LSError structure to initialize

Returns

Name

Required

Type

Description

retValRequiredbool

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

lserrorRequiredLSError *IN LSError structure to check

Returns

Name

Required

Type

Description

retValRequiredbool

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

contextRequiredPmLogContextIN log context
message_idRequiredconst char *IN message id
lserrorRequiredLSError *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_idRequiredconst char *IN message id
lserrorRequiredLSError *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

lserrorRequiredLSError *IN LSError structure to print
outRequiredFILE *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

shRequiredLSHandle *IN handle to service
mainLoopRequiredGMainLoop *IN loop to attach
lserrorRequiredLSError *OUT set on error

Returns

Name

Required

Type

Description

retValRequiredbool

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

shRequiredLSHandle *IN handle to service
mainContextRequiredGMainContext *IN context
lserrorRequiredLSError *OUT set on error

Returns

Name

Required

Type

Description

retValRequiredbool

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

shRequiredLSHandle *IN handle to service
lserrorRequiredLSError *OUT set on error

Returns

Name

Required

Type

Description

retValRequiredbool

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

shRequiredLSHandle *IN handle to service
lserrorRequiredLSError *OUT set on error

Returns

Name

Required

Type

Description

GMainContext *RequiredGMainContext *

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

shRequiredLSHandle *IN handle to service
priorityRequiredintIN priority level
lserrorRequiredLSError *OUT set on error

Returns

Name

Required

Type

Description

retValRequiredbool

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

shRequiredLSHandle *

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

timeoutRequiredunsigned intIN time of inactivity (in ms) before callback invocation
callbackRequiredvoid(*)(void *)IN user callback
userdataRequiredvoid *IN user provided data, that will be passed into callback
contextRequiredGMainContext *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_dirRequiredconst char *IN directory where the pid file should reside
lock_file_nameRequiredconst char *

IN file to be checked

Returns

Name

Required

Type

Description

retValRequiredbool

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

fdRequiredint

Indicates the file descriptor.

Returns

Name

Required

Type

Description

retValRequiredbool

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

messageRequiredLSMessage *IN message

Returns

Name

Required

Type

Description

payloadRequiredLSPayload *

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

messageRequiredLSMessage *IN message

Returns

Name

Required

Type

Description

app_idRequiredconst 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

messageRequiredLSMessage *IN message

Returns

Name

Required

Type

Description

categoryRequiredconst 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

messageRequiredLSMessage *IN message

Returns

Name

Required

Type

Description

shRequiredLSHandle *

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

messageRequiredLSMessage *IN message

Returns

Name

Required

Type

Description

intRequiredint

Returns file descriptor.

Examples

None

LSMessageGetKind

Description

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

Syntax

LSMessageGetKind(LSMessage * message)

Parameters

Name

Required

Type

Description

messageRequiredLSMessage *IN message

Returns

Name

Required

Type

Description

message_kindRequiredconst 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

messageRequiredLSMessage *IN message

Returns

Name

Required

Type

Description

methodRequiredconst 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

messageRequiredLSMessage *IN message

Returns

Name

Required

Type

Description

payloadRequiredconst 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

replyRequiredLSMessage *IN message

Returns

Name

Required

Type

Description

tokenRequiredLSMessageToken

Indicates the message token.

Examples

None

LSMessageGetSender

Description

Obtains a unique token identifying the sender.

Syntax

LSMessageGetSender(LSMessage * message)

Parameters

Name

Required

Type

Description

messageRequiredLSMessage *IN message

Returns

Name

Required

Type

Description

service_nameRequiredconst 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

messageRequiredLSMessage *IN message

Returns

Name

Required

Type

Description

service_nameRequiredconst 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

messageRequiredLSMessage *IN message

Returns

Name

Required

Type

Description

tokenRequiredLSMessageToken

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

messageRequiredLSMessage *IN message

Returns

Name

Required

Type

Description

tokenRequiredconst 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

messageRequiredLSMessage *IN message to chech

Returns

Name

Required

Type

Description

retValRequiredbool

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

messageRequiredLSMessage *IN message

Returns

Name

Required

Type

Description

retValRequiredbool

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

messageRequiredLSMessage *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

messageRequiredLSMessage *IN message to print
outRequiredFILE *IN file to print

Returns

Name

Required

Type

Description

retValRequiredbool

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

messageRequiredLSMessage *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

shRequiredLSHandle *IN handle to service
lsmsgRequiredLSMessage *IN message
jsonRequiredconst char *IN json as payload
lserrorRequiredLSError *OUT set one error

Returns

Name

Required

Type

Description

retValRequiredbool

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

messageRequiredLSMessage *IN message
jsonRequiredconst char *IN payload to send
lserrorRequiredLSError *OUT set on error

Returns

Name

Required

Type

Description

retValRequiredbool

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

messageRequiredLSMessage *IN message
payloadRequiredLSPayload *IN payload to send
lserrorRequiredLSError *OUT set on error

Returns

Name

Required

Type

Description

retValRequiredbool

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

messageRequiredLSMessage *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

shRequiredLSHandle *IN handle to service
categoryRequiredconst char *IN category name
methodRequiredconst char *IN method name
user_dataRequiredvoid *IN user data to set
lserrorRequiredLSError *OUT set on error

Returns

Name

Required

Type

Description

retValRequiredbool

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

payloadRequiredLSPayload *

Indicates a new LSPayload structure.

fdRequiredint

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

payloadRequiredLSPayload *

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

typeRequiredconst char *

Indicates the string identifier of the binary data type.

ptrRequiredvoid *

Indicates the data pointer.

sizeRequiredsize_t

Indicates the size of the binary data.

Returns

Name

Required

Type

Description

LSPayload *RequiredLSPayload *

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

jsonRequiredconst char *

Indicates the string representation of the JSON.

Returns

Name

Required

Type

Description

LSPayload *RequiredLSPayload *

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

valueRequiredjvalue_ref

Indicates the pbnjson representation of the JSON.

Returns

Name

Required

Type

Description

LSPayload *RequiredLSPayload *

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

payloadRequiredconst LSPayload *

Indicates a new LSPayload structure.

sizeRequiredsize_t *

Indicates a pointer to size_t in which size of data will be stored.

Returns

Name

Required

Type

Description

ptrRequiredvoid *

Pointer to data.

Examples

None

LSPayloadGetDataType

Description

Gets the string identifier of LSPayload data.

Syntax

LSPayloadGetDataType(const LSPayload * payload)

Parameters

Name

Required

Type

Description

payloadRequiredconst LSPayload *

Indicates a new LSPayload structure.

Returns

Name

Required

Type

Description

const char *Requiredconst 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

payloadRequiredconst LSPayload *

Indicates a new LSPayload structure.

Returns

Name

Required

Type

Description

fdRequiredint

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

payloadRequiredconst LSPayload *

Indicates a new LSPayload structure.

Returns

Name

Required

Type

Description

const char *Requiredconst 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

payloadRequiredconst LSPayload *

Indicates a new LSPayload structure.

Returns

Name

Required

Type

Description

jvalue_refRequiredjvalue_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

shRequiredLSHandle *IN handle (already connected with LSRegister())
role_pathRequiredconst char *IN full path to role file
lserrorRequiredLSError *OUT set on error

Returns

Name

Required

Type

Description

retValRequiredbool

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

nameRequiredconst char *IN service name
shRequiredLSHandle **

IN handle to service

lserrorRequiredLSError *OUT set on error

Returns

Name

Required

Type

Description

retValRequiredbool

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

nameRequiredconst char *IN service name
app_idRequiredconst char *IN application Id
shRequiredLSHandle **

IN handle to service

lserrorRequiredLSError *OUT set on error

Returns

Name

Required

Type

Description

retValRequiredbool

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

shRequiredLSHandle *IN handle to service
categoryRequiredconst char *IN may be NULL for default '/' category.
methodsRequiredLSMethod *IN table of methods.
signalsRequiredLSSignal *IN table of signals.
propertiesRequiredLSProperty *IN table of properties.
lserrorRequiredLSError *OUT set on error

Returns

Name

Required

Type

Description

retValRequiredbool

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

shRequiredLSHandle *IN handle to service
categoryRequiredconst char *IN category name
methodsRequiredLSMethod *IN array of methods
signalsRequiredLSSignal *IN array of signals
lserrorRequiredLSError *OUT set on error

Returns

Name

Required

Type

Description

retValRequiredbool

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

shRequiredLSHandle *IN handle to service
serviceNameRequiredconst char *IN service name to monitor for connect/disconnect.
funcRequiredLSServerStatusFuncIN function callback
ctxtRequiredvoid *

IN context

cookieRequiredvoid **OUT token to use for to unregister the callback
lserrorRequiredLSError *OUT set on error

Returns

Name

Required

Type

Description

retValRequiredbool

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

shRequiredLSHandle *IN handle to service
serviceNameRequiredconst char *IN service name to monitor for connect/disconnect.
funcRequiredLSServerStatusFuncIN function callback
ctxRequiredvoid *IN user data to be passed to callback
cookieRequiredvoid **OUT token to use for to unregister the callback
lserrorRequiredLSError *OUT set on error

Returns

Name

Required

Type

Description

retValRequiredbool

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

shRequiredLSHandle *IN handle to service
disconnect_handlerRequiredLSDisconnectHandlerIN function callback
user_dataRequiredvoid *IN user data to be passed to callback
lserrorRequiredLSError *OUT set on error

Returns

Name

Required

Type

Description

retValRequiredbool

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

shRequiredLSHandle *IN handle to service
uriRequiredconst char *IN fully qualified path to service's method
payloadRequiredconst char *IN some string, usually following json object semantics
lserrorRequiredLSError *OUT set on error

Returns

Name

Required

Type

Description

retValRequiredbool

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

shRequiredLSHandle *IN handle to service
keyRequiredconst char *IN key
ret_iterRequiredLSSubscriptionIter **

OUT Iterator to iterate through the subscription for key

lserrorRequiredLSError *OUT set on error

Returns

Name

Required

Type

Description

retValRequiredbool

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

shRequiredLSHandle *IN handle to service
keyRequiredconst char *IN key
messageRequiredLSMessage *IN message object
lserrorRequiredLSError *OUT set on error

Returns

Name

Required

Type

Description

retValRequiredbool

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

shRequiredLSHandle *

IN handle to service

keyRequiredconst char *

IN key

Returns

Name

Required

Type

Description

subscriber_countRequiredunsigned 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

iterRequiredLSSubscriptionIter *IN Subscription iterator to check

Returns

Name

Required

Type

Description

retValRequiredbool

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

iterRequiredLSSubscriptionIter *IN Subscription iterator to obtain from

Returns

Name

Required

Type

Description

LSMessage *RequiredLSMessage *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

shRequiredLSHandle *IN service handle
messageRequiredLSMessage *IN message object
subscribedRequiredbool *

OUT flag to check if subscribed

lserrorRequiredLSError *OUT set on error

Returns

Name

Required

Type

Description

retValRequiredbool

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

iterRequiredLSSubscriptionIter *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

iterRequiredLSSubscriptionIter *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

shRequiredLSHandle *IN handle to service
keyRequiredconst char *IN key
payloadRequiredconst char *IN some string, usually following json object semantics
lserrorRequiredLSError *OUT set on error

Returns

Name

Required

Type

Description

retValRequiredbool

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

shRequiredLSHandle *IN handle to service
cancelFunctionRequiredLSFilterFuncIN callback function
ctxRequiredvoid *IN user data to be passed to callback
lserrorRequiredLSError *OUT set on error

Returns

Name

Required

Type

Description

retValRequiredbool

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

shRequiredLSHandle *IN handle to service
lserrorRequiredLSError *OUT set on error

Returns

Name

Required

Type

Description

retValRequiredbool

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

channelRequired_LSTransportChannel *IN channel that watch is on
out_watchRequiredGSource **IN/OUT watch (set to NULL after destroying)

Returns

None

Examples

None

Contents