luna-service2 Library API Reference

API Summary

luna-service2 library provides a C/C++ API that can be used to call LS2 API methods. Native apps and services can use the luna-service2 library API in order to make use of platform features.

Type Definitions

The table below shows description of the typedefs.

DefinitionDescription

LSHandle

Handle to the service.

LSMessageToken

Message token.

LSMessage

Message object.

  • Contains information about methods, connection tokens, client payload (request arguments), and whether a subscription is requested.
  • It is necessary to pass the response to the client.
  • Functions that can obtain the information are LSMessageGetMethod (), LSMessageGetPayload (), and so on.

LSMethodFunction

typedef bool(*)(LSHandle sh, LSMessage msg, void *category_context) LSMethodFunction

Table registration of callbacks.

Parameters:

  • sh - handle to the service
  • msg - message object
  • category_context - category context

Returns:

  • bool - true on success, otherwise false

LSFilterFunc

typedef bool(*)(LSHandle *sh, LSMessage *reply, void *ctx) LSFilterFunc

Callback function called on incoming message.

Parameters:

  • sh - handle to the service
  • reply - incoming message
  • ctx - context

Returns:

  • bool - true on success, otherwise false

LSError

Error object which contains information about first error since it was initialized via LSErrorInit.

Functions

LSCall

Description

Sends payload to service at the specified URI.

Syntax

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

Parameters

  • sh - [IN] handle to the service
  • uri - [IN] fully qualified path to service’s method
  • payload - [IN] some string, usually following json object semantics
  • callback - [IN] function callback to be called when responses arrive
  • ctx - [IN] user data to be passed to callback
  • ret_token - [OUT] token which identifies responses to this call
  • lserror - [OUT] set on error

Returns

  • bool - true on success, otherwise false

LSErrorInit

Description

Initializes an LSError.

Syntax

bool LSErrorInit (LSError* lserror)

Parameters

  • lserror - [IN] LSError structure to initialize

Returns

  • bool - true on success, otherwise false

LSErrorPrint

Description

Prints an LSError.

Syntax

void LSErrorPrint (LSError *lserror, FILE *out)

Parameters

  • lserror - [IN] LSError structure to print
  • out - [IN] handle to file

Returns

None

LSMessageReply

Description

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

Syntax

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

Parameters

  • sh - [IN] handle to the service
  • msg - [IN] message
  • json - [IN] json as payload
  • lserror - [OUT] set on error

Returns

  • bool - true on success, otherwise false

LSRegister

Description

Registers a service on the LS2 bus.

Syntax

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

Parameters

  • name - [IN] service name
  • sh - [IN] handle to the service
  • lserror - [OUT] set on error

Returns

  • bool - true on success, otherwise false

LSUnregister

Description

Unregisters a service.

Syntax

bool LSUnregister (LSHandle *sh, LSError *lserror)

Parameters

  • sh - [IN] handle to the service
  • lserror - [OUT] set on error

Returns

  • bool - true on success, otherwise false

LSRegisterCategory

Description

Registers tables of callbacks associated with the message category.

Syntax

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

Parameters

  • sh - [IN] handle to the service
  • category - [IN] may be NULL for default ‘/’ category.
  • methods - [IN] table of methods
  • signals - [IN] table of signals
  • properties - [IN] table of properties
  • lserror - [OUT] set on error

Returns

  • bool - true on success, otherwise false

LSGmainAttach

Description

Attaches a service to a glib mainloop.

Syntax

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

Parameters

  • sh - [IN] handle to the service
  • mainLoop - [IN] loop to attach
  • lserror - [OUT] set on error

Returns

  • bool - true on success, otherwise false

LSMessageGetMethod

Description

Gets the method name of the message.

This only applies to request messages on the service side like method call, method cancel, signal call. Doesn’t apply to response messages.

Syntax

const char * LSMessageGetMethod (LSMessage *message)

Parameters

  • message - [IN] message

Returns

  • const char * - method name

LSMessageGetPayload

Description

Gets the payload of the message.

Syntax

const char * LSMessageGetPayload (LSMessage *message)

Parameters

  • message - [IN] message

Returns

  • const char * - payload

Contents