luna-service2++ Library API Reference

API Summary


The C++ wrapper for the webOS Luna System Bus that provides a bus-based IPC mechanism used between components in webOS. Luna-service2 is composed of a client library and a central hub daemon. The client library provides the API support to register on the bus and communicate with other components. The hub provides a central clearinghouse for all communication. Utilities for monitoring and debugging the bus are included.

Overview of the API

A bus-based Inter Process Communication (IPC) mechanism for components in the webOS. The Luna Service is composed of a client library and of a central hub daemon. The client library provides the API support to register on the bus and communicate with other components. The hub provides a central clearing house for all communication. Utilities for monitoring and debugging the bus are included. After having registered on the Luna Service Bus, services and applications can call public methods of other services and applications registered on the Luna Service Bus. The Luna Service API offers the mechanism that enables sending and receiving data within a single device. Both third-party and internal services can use Luna Service Bus. The operations that a service can perform on the Luna Service Bus are limited by the assigned security permissions.

Example for asynchronous client usage:

     try

     {

         auto  client  =  LS::registerService( nullptr );

         client.attachToLoop(mainLoop);

         auto  call  =  client.callOneReply( "luna://com.palm.contacts/category/listContacts" ,

                                         "{  \"json  payload\"  }" );

         call.setTimeout(1000);

         call.continueWith(listContactsHandler,  userData);

         g_main_loop_run(mainLoop);

     }

     catch  ( const  LS::Error  &e)

     {

         cerr  <<  e  <<  endl;

         throw ;

     }

Example for service usage:

 namespace  {

 //  callback

 bool  listContacts(LSHandle  *sh,  LSMessage  *raw_message,  void  *categoryContext)

 {

     LS::Message  message{raw_message};

     try

     {

         message.respond( "{  JSON  REPLY  PAYLOAD  }" );

     }

     catch  ( const  LS::Error  &e)

     {

         cerr  <<  e  <<  endl;

         return  false ;

     }

     return  true ;

 }

 static  LSMethod  ipcMethods[]  =  {

    {  "listContacts" ,  listContacts  },

    {  },

 };

 }  //namespace

     try

     {

         auto  service  =  LS::registerService( "com.palm.contacts" );

         service.registerCategory( "/category" ,  ipcMethods,  nullptr ,  nullptr );

         service.setCategoryData( "/category" ,  userData);

         service.attachToLoop(mainLoop);

         g_main_loop_run(mainLoop);

     }

     catch  ( const  LS::Error  &e)

     {

         cerr  <<  e  <<  endl;

         throw ;

     }

Example C++ service usage:

 class  Category

     :  private  LS::Handle

 {

 public :

     Category(GMainLoop  *mainLoop)

         :  LS::Handle(LS::registerService( "com.palm.contacts" ))

     {

         attachToLoop (mainLoop);

         LS_CATEGORY_BEGIN(Category,  "/category" )

             LS_CATEGORY_METHOD(listContacts)

         LS_CATEGORY_END

     }

private:

     bool  listContacts(LSMessage  &message)

     {

         LS::Message  request(&message);

         request.respond( "{  JSON  REPLY  PAYLOAD  }" );

         return  true ;

     }

 };

try

     {

         Category  category(mainLoop);

         g_main_loop_run(mainLoop);

     }

     catch  ( const  LS::Error  &e)

     {

         cerr  <<  e  <<  endl;

         throw ;

     }

LS::PayloadRef

A Reference wrapper for LSPayload, that does not own it.

Methods

PayloadRef

Description

Constructs a reference for the LSPayload.

Syntax

PayloadRef (LSPayload * payload)

Parameters

Name

Required

Type

Description

payloadRequiredLSPayload *

Indicates the underlying LSPayload to the reference.

Returns

None

~PayloadRef

Description

Destructs the reference payload.

Note: It does not free the reference payload.

Syntax

~PayloadRef ()

Parameters

None

Returns

None

attachFd

Description

Attaches the file descriptor to the payload.

Syntax

attachFd (int fd)

Parameters

Name

Required

Type

Description

fdRequiredint

Indicates the file descriptor to be attached.

Returns

None

getFd

Description

Gets the file descriptor attached to the payload.

Syntax

getFd ()

Parameters

None

Returns

Name

Required

Type

Description

intRequiredint

Returns the file descriptor if it is attached or -1 if not attached.

getJson

Description

Get string representation of json in payload.

Syntax

getJson ()

Parameters

None

Returns

Name

Required

Type

Description

const char *Requiredconst char *

Indicates the json string or the nullptr if the string can't be retrieved.

getJValue

Description

Gets the pbnjson::Jvalue from the json in the payload.

Syntax

getJValue ()

Parameters

None

Returns

Name

Required

Type

Description

pbnjson::JValueRequiredpbnjson::JValue

Indicates the new Jvalue or JNull if the Jvalue can't be retrieved.

getDataType

Description

Gets the string identifier of the payload data type.

Syntax

getDataType ()

Parameters

None

Returns

Name

Required

Type

Description

const char *Requiredconst char *

Gets the string identifier of the payload data.

getData

Description

Gets the raw data.

Syntax

getData (size_t & size)

Parameters

Name

Required

Type

Description

sizeRequiredsize_t &

Indicates the size_t that stores the size of the data.

Returns

Name

Required

Type

Description

void *Requiredvoid *

Indicates the data pointer.

LS::PalmService

A wrapper for the service that has both public and private representations.

Deprecated: Use LS::Handle instead

Methods

registerCategory

Description

Register tables of callbacks (private and public) associated with the message category.

Syntax

registerCategory (const char * category, LSMethod * methods_public, LSMethod * methods_private, LSSignal * ls_signals)

Parameters

Name

Required

Type

Description

categoryRequiredconst char *name
methods_publicRequiredLSMethod *LSMethod array that should end with {0}
methods_privateRequiredLSMethod *LSMethod array that should end with {0}
ls_signalsRequiredLSSignal *LSSignal array that should end with {0}

Returns

None

getPublicHandle

Description

Function to get public handle.

Syntax

getPublicHandle ()

Parameters

None

Returns

Name

Required

Type

Description

Handle &RequiredHandle &public service handle

getPublicHandle

Description

Function to get public handle.

Syntax

getPublicHandle ()

Parameters

None

Returns

Name

Required

Type

Description

const Handle &Requiredconst Handle &public service handle

getPrivateHandle

Description

Function to get private handle.

Syntax

getPrivateHandle ()

Parameters

None

Returns

Name

Required

Type

Description

Handle &RequiredHandle &private service handle

getPrivateHandle

Description

Function to get private handle.

Syntax

getPrivateHandle ()

Parameters

None

Returns

Name

Required

Type

Description

const Handle &Requiredconst Handle &private service handle

LS::SubscriptionPoint

Represents a publishing point for the sender service.

Methods

setServiceHandle

Description

Assigns a publisher service.

Syntax

setServiceHandle (Handle * service_handle)

Parameters

Name

Required

Type

Description

service_handleRequiredHandle *

Returns

None

subscribe

Description

Indicates the process subscription message. Subscribes sender of the given message.

Syntax

subscribe (LS::Message & message)

Parameters

Name

Required

Type

Description

messageRequiredLS::Message &

Indicates the subscription message to process.

Returns

Name

Required

Type

Description

boolRequiredbool

Indicates the subscribe status of the sender.

Possible values are:

  • true: The sender has been added to subscribe successfully
  • false: The sender has not been added to subscribe

post

Description

Posts the payload to all the subscribers.

Syntax

post (const char * payload)

Parameters

Name

Required

Type

Description

payloadRequiredconst char *

Indicates the posted data.

Returns

Name

Required

Type

Description

boolRequiredbool

Indicates the status of the post.

Possible values are:

  • true: The replies have been posted successfully
  • false: The replies have not been posted

getSubscribersCount

Description

Returns the number of service subscribers.

Syntax

getSubscribersCount ()

Parameters

None

Returns

Name

Required

Type

Description

std::vector< SubscriptionItem * >::size_typeRequiredstd::vector< SubscriptionItem * >::size_type

Indicates the number of subscribers.

PJSAXBounce

Callbacks adapter to parse JSON SAX events.

Possible types that facilitate the next method calls are:

  • (bool)jsonObjectOpen()
  • (bool)jsonObjectKey({str,len})
  • (bool)jsonObjectClose()
  • (bool)jsonArrayOpen()
  • (bool)jsonArrayClose()
  • (bool)jsonString({str,len})
  • (bool)jsonNumber({str,len})
  • (bool)jsonBoolean(boolVal)
  • (bool)jsonNull()
  • constchar*str;
  • size_tlen;
  • (bool)boolVal

Note: If the method returns something that implicitly casts to false is treated as the request to abort the parser.

Methods

callbacks

Description

Gets the PJSAX callbacks for the type T.

Syntax

callbacks ()

Parameters

None

Returns

None

LS::Payload

Wrapper for LSPayload.

Methods

Payload

Description

Construct from the string representation of the json.

Syntax

Payload (const char * json)

Parameters

Name

Required

Type

Description

jsonRequiredconst char *Description here

Returns

None

Payload

Description

Construct from pbnjson::JValue representation of json.

Syntax

Payload (pbnjson::JValue json)

Parameters

Name

Required

Type

Description

jsonRequiredpbnjson::JValue

Returns

None

Payload

Description

Construct from raw data.

Syntax

Payload (const char * type, void * data, size_t size)

Parameters

Name

Required

Type

Description

typeRequiredconst char *
dataRequiredvoid *
sizeRequiredsize_t

Returns

None

~Payload

Description

Destruct owning payload.

Syntax

~Payload ()

Parameters

None

Returns

None

LS::Message

Indicates the LSMessage wrapper.

Methods

accessPayload

Description

Indicates the access payload in the message.

Syntax

accessPayload ()

Parameters

None

Returns

Name

Required

Type

Description

LS::PayloadRefRequiredLS::PayloadRef

Indicates the payload reference.

respond

Description

Responds with payload via LS2. Throws an exception on failure.

Syntax

respond (LS::Payload payload)

Parameters

Name

Required

Type

Description

payloadRequiredLS::Payload

Indicates the payload to respond.

Returns

None

getSessionID

Description

Returns the session ID of the message.

Syntax

getSessionID ()

Parameters

None

Returns

Name

Required

Type

Description

sessionIDRequiredconst char *

Indicates the sessionID.

LS::Error

A class that wraps the LS errors.

Methods

what

Description

Gets the text representation of the error.

Syntax

what ()

Parameters

None

Returns

Name

Required

Type

Description

const char *Requiredconst char *

Indicates the error text message.

LS::Handle

A bus end-point base class that provides an API to control the service and client end-points of the luna hub.

The user can inherit or use it to create an own service. However the class has not been designed to be used as a precise low-level full functional wrapper for the API. Instead additional service and client wrappers could be created for easy use of the functionality.

Methods

methodWraper

Description

Maps a category method to some class method.

Note:

  • An object address which has the method should be passed as user_data parameter to setCategoryData method. All methods of a category should be methods of one class as of now.
  • It allows to obtain the LSMethod presentation of a given method. This is used to create a category method list.

Syntax

methodWraper (LSHandle * h, LSMessage * m, void * ctx, typedef ClassT, typedef MethT)

Parameters

Name

Required

Type

Description

hRequiredLSHandle *
mRequiredLSMessage *
ctxRequiredvoid *
ClassTRequiredtypedef

Specifies the class of category.

MethTRequiredtypedef

Specifies the method of the class ClassT.

Returns

None

Handle

Description

Creates an empty inactive instance.

Note: This handle is not registered.

Syntax

Handle ()

Parameters

None

Returns

None

Handle

Description

Registers a new service with the specified name.

Syntax

Handle (const char * name)

Parameters

Name

Required

Type

Description

nameRequiredconst char *

Indicates the service name.

Returns

None

Handle

Description

Registers a new service with a specified name and an application ID.

Syntax

Handle (const char * name, const char * app_id)

Parameters

Name

Required

Type

Description

nameRequiredconst char *

Indicates the service name.

app_idRequiredconst char *

Indicates the additional application identifier, which can be used to distinguish the applications, that work within one registration (HANDLE) on the bus.

Note: The recipient should be prepared to query app_from an incoming message.

Returns

None

get

Description

Gets the handle to the service.

Syntax

get ()

Parameters

None

Returns

Name

Required

Type

Description

LSHandle *RequiredLSHandle *

Indicates the service handle for libluna-service c API.

get

Description

Gets the handle to the service.

Syntax

get ()

Parameters

None

Returns

Name

Required

Type

Description

const LSHandle *Requiredconst LSHandle *

Indicates the service handle for the libluna-service c API.

getName

Description

Gets a LSHandle name.

Syntax

getName ()

Parameters

None

Returns

Name

Required

Type

Description

const char *Requiredconst char *

Indicates the service name.

operator bool

Description

Checks if the end-point registration was successfully performed.

Syntax

operator bool ()

Parameters

None

Returns

None

registerCategory

Description

Registers tables of the callbacks associated with the message category.

Syntax

registerCategory (const char * category, const LSMethod * methods, const LSSignal * ls_signals, const LSProperty * properties)

Parameters

Name

Required

Type

Description

categoryRequiredconst char *

Indicates the category name starting from '/'.

methodsRequiredconst LSMethod *

Indicates the c API style method describing the structure objects.

ls_signalsRequiredconst LSSignal *

Indicates the table of signals.

propertiesRequiredconst LSProperty *

Indicates the table of properties.

Returns

None

registerCategoryAppend

Description

Appends methods to the category.

Note: Creates a category if needed.

Syntax

registerCategoryAppend (const char * category, LSMethod * methods, LSSignal * ls_signals)

Parameters

Name

Required

Type

Description

categoryRequiredconst char *

Indicates the name of the category for the given end-point.

methodsRequiredLSMethod *

Indicates the c-style method list.

Note: The list should end with the zeroed item.

ls_signalsRequiredLSSignal *

Indicates the c-style signal list.

Note: The list should end with zeroed item.

Returns

None

setDisconnectHandler

Description

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

Syntax

setDisconnectHandler (LSDisconnectHandler disconnect_handler, void * user_data)

Parameters

Name

Required

Type

Description

disconnect_handlerRequiredLSDisconnectHandler

Indicates the function callback.

user_dataRequiredvoid *

Indicates the user data to be passed to callback.

Returns

None

setCategoryData

Description

Sets the user data that is delivered to each callback registered to the category.

Note: If the method user data is set using the setMethodData, it overrides the category data.

Syntax

setCategoryData (const char * category, void * user_data)

Parameters

Name

Required

Type

Description

categoryRequiredconst char *

Indicates the category name.

user_dataRequiredvoid *

Indicates the user data to be set.

Returns

None

setCategoryDescription

Description

Specifies the meta information about the category and sets the JSON value that describes specified category. Provides validation schema for input parameters and replies. Gives some description for calls.

Syntax

setCategoryDescription (const char * category, jvalue_ref description)

Parameters

Name

Required

Type

Description

categoryRequiredconst char *

Indicates the category.

descriptionRequiredjvalue_ref

Indicates the information (no ownership transfer) see / category in example.

Returns

None

setMethodData

Description

Sets the user data 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

setMethodData (const char * category, const char * method, void * user_data)

Parameters

Name

Required

Type

Description

categoryRequiredconst char *

Indicates the name of the category.

methodRequiredconst char *

Indicates the method.

user_dataRequiredvoid *

Indicates the user data to be set.

Returns

None

pushRole

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

pushRole (const char * role_path)

Parameters

Name

Required

Type

Description

role_pathRequiredconst char *

Specifies the complete path to the role file.

Returns

None

attachToLoop

Description

Attaches the service to the glib main loop context.

Syntax

attachToLoop (GMainContext * context)

Parameters

Name

Required

Type

Description

contextRequiredGMainContext *

Indicates the context to the glib main loop.

Returns

None

attachToLoop

Description

Attaches the service to the glib main loop.

Syntax

attachToLoop (GMainLoop * loop)

Parameters

Name

Required

Type

Description

loopRequiredGMainLoop *

Indicates the loop to attach.

Returns

None

detach

Description

Detaches the end-point from the glib mainloop.

Note: You should NEVER use this function unless you are fork()'ing without executing. 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

detach ()

Parameters

None

Returns

None

setPriority

Description

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

Note: The method should be called after attachToLoop(). See https://developer.gnome.org/glib/2.37/glib-The-Main-Event-Loop.html#g-source-set-priority for details.

Syntax

setPriority (int priority)

Parameters

Name

Required

Type

Description

priorityRequiredint

Indicates the priority level.

Returns

None

sendSignal

Description

Sends a signal specified by the URI with given payload to subscribed services.

Note:

  • Services register signals with the method registerCategory(). The signal can be fired with sendSignal(). Services can subscribe for signals with addmatch.
  • Client subscribes to a signals with the method LSCall(sh, "luna://com.webos.service.bus/signal/addmatch", ...)

Syntax

sendSignal (const char * uri, const char * payload, bool typecheck)

Parameters

Name

Required

Type

Description

uriRequiredconst char *

Indicates the fully qualified path for a method of the given service.

payloadRequiredconst char *

Indicates a string, usually following the JSON object semantics.

typecheckRequiredbool

Indicates the status of the signal point.

Possible values are:

  • true: Checks if the signal point exists
  • false: Logs a warning if it does not exist

Returns

None

callOneReply

Description

Makes a call.

Syntax

callOneReply (const char * uri, const char * payload, const char * appID, [const char * sessionID])

Parameters

Name

Required

Type

Description

uriRequiredconst char *

Indicates the fully qualified path to service's method.

payloadRequiredconst char *

Indicates some string, usually following json object semantics.

appIDRequiredconst char *

Indicates the appID.

Returns

Name

Required

Type

Description

CallRequiredCall

Indicates the Call control object.

callOneReply

Description

Makes a call with the result handler callback.

Syntax

callOneReply (const char * uri, const char * payload, LSFilterFunc func, void * context, const char * appID, [const char * sessionID])

Parameters

Name

Required

Type

Description

uriRequiredconst char *

Indicates the fully qualified path to service's method.

payloadRequiredconst char *

Indicates some string, usually following json object semantics.

funcRequiredLSFilterFunc

Indicates the callback function.

contextRequiredvoid *

Indicates the user data.

appIDRequiredconst char *

Indicates the appID.

Returns

Name

Required

Type

Description

CallRequiredCall

Indicates the Call handler object.

callMultiReply

Description

Makes a multi-call Returned object will collect arrived messages in internal queue.

Note: The messages can be obtained with callback or get(...) functions.

Syntax

callMultiReply (const char * uri, const char * payload, const char * appID, [const char * sessionID])

Parameters

Name

Required

Type

Description

uriRequiredconst char *

Indicates the fully qualified path to service's method.

payloadRequiredconst char *

Indicates some string, usually following json object semantics.

appIDRequiredconst char *

Indicates the appID.

Returns

Name

Required

Type

Description

CallRequiredCall

Indicates the Call handler object.

callMultiReply

Description

Makes a multi-call with result processing callback.

Syntax

callMultiReply (const char * uri, const char * payload, LSFilterFunc func, void * context, const char * appID, [const char * sessionID])

Parameters

Name

Required

Type

Description

uriRequiredconst char *

Indicates the fully qualified path to service's method.

payloadRequiredconst char *

Indicates some string, usually following json object semantics.

funcRequiredLSFilterFunc

Indicates the callback function.

contextRequiredvoid *

Indicates the context.

appIDRequiredconst char *

Indicates the appID.

Returns

Name

Required

Type

Description

CallRequiredCall

Indicates the Call handler object.

callSignal

Description

Call a signal to a specific category.

Syntax

callSignal (const char * category, const char * methodName, LSFilterFunc func, void * context)

Parameters

Name

Required

Type

Description

categoryRequiredconst char *

Indicates the category name to monitor.

methodNameRequiredconst char *

Indicates the methodName to monitor.

funcRequiredLSFilterFunc

Indicates the callback function.

contextRequiredvoid *

Indicates the user data.

Returns

Name

Required

Type

Description

CallRequiredCall

Inidicates the Call handler object.

registerServerStatus

Description

Registers a callback to be called when the server goes down or comes up.

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

Syntax

registerServerStatus (const char * service_name, const ServerStatusCallback & callback, [const char * sessionID])

Parameters

Name

Required

Type

Description

service_nameRequiredconst char *

Indicates the service name.

callbackRequiredconst ServerStatusCallback &

Indicates the callback function.

Returns

Name

Required

Type

Description

ServerStatusRequiredServerStatus

Indicates the status handler object, controls its lifetime to control the subscription.

LS::Call

Provides the ability to make a call to service category methods, it controls the lifetime of the call.

Note: The call is canceled on object destroy.

Methods

~Call

Description

Cancels the call if it is active.

Syntax

~Call ()

Parameters

None

Returns

None

cancel

Description

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

Syntax

cancel ()

Parameters

None

Returns

None

setTimeout

Description

Sets the timeout for a method call.

Note: The call will be canceled if no reply is received after the msTimeout (milliseconds).

Syntax

setTimeout (int msTimeout)

Parameters

Name

Required

Type

Description

msTimeoutRequiredint

Indicates the time after which the method can be canceled.

Returns

Name

Required

Type

Description

boolRequiredbool

Indicates if the timeout status for the given call.

Possible values are:

  • true: The timeout was successfully set for the call.
  • false: The timeout could not be set for the call.

continueWith

Description

Sets the callback to continue.

Note: This is the callback that is called for each message that arrives. It replaces any previous callback if it exists. If the internal queue already contains the messages then the callback is called sequentially for every message in the queue.

Syntax

continueWith (LSFilterFunc callback, void * context)

Parameters

Name

Required

Type

Description

callbackRequiredLSFilterFunc

Indicates the callback function.

contextRequiredvoid *

Indicates the user data.

Returns

None

get

Description

Note: Do not use. It will be deprecated.

Retrieve a message object from the top of its queue.

If continueWith was called then this call will wait infinitely because callback from continueWith intercepts all messages and keeps the message queue empty.

It waits for new messages if there is none. It blocks execution until a new message arrives. if msTimeout != 0 the call will be canceled if no reply is received after msTimeout milliseconds.

Syntax

get (unsigned long msTimeout)

Parameters

Name

Required

Type

Description

msTimeoutRequiredunsigned longtime after which method can be canceled. If msTimeout == 0 message wasn't canceled.

Returns

Name

Required

Type

Description

MessageRequiredMessagemessage. The message could be empty. Check for an empty message using an if (message) statement before processing the message.

isActive

Description

Returns the status of the call.

Note:

  • If the call is active, it is expected to receive the replies and will be canceled in the destructor.
  • If a call is not active, it is not expected to receive replies (for calls with one reply), and will not be cancelled in the destructor.

Syntax

isActive ()

Parameters

None

Returns

Name

Required

Type

Description

boolRequiredbool

Indicates the call status.

Possible values are:

  • true: Indicates that the call is active
  • false: Indicates that the call is not active

Contents