le_posCtrl_interface.h

Go to the documentation of this file.
    1 
    2 
    3 /*
    4  * ====================== WARNING ======================
    5  *
    6  * THE CONTENTS OF THIS FILE HAVE BEEN AUTO-GENERATED.
    7  * DO NOT MODIFY IN ANY WAY.
    8  *
    9  * ====================== WARNING ======================
   10  */
   11 
   12 /**
   13  * @page c_posCtrl Positioning Control API
   14  *
   15  * @ref le_posCtrl_interface.h "API Reference"
   16  *
   17  * <HR>
   18  *
   19  * This API is used to enable and disable the positioning service.
   20  *
   21  * All other positioning functionality is provided by the @ref c_pos.
   22  *
   23  * @section le_posCtrl_binding IPC interfaces binding
   24  *
   25  * All the functions of this API are provided by the @b positioningService application service.
   26  *
   27  * Here's a code sample binding to Positioning services:
   28  * @verbatim
   29    bindings:
   30    {
   31       clientExe.clientComponent.le_posCtrl -> positioningService.le_posCtrl
   32    }
   33    @endverbatim
   34  *
   35  * @section le_posCtrl_ctrl Positioning control
   36  *
   37  * To request that the positioning service be activated, call le_posCtrl_Request().
   38  *
   39  * To release the positioning service when finished with it, call le_posCtrl_Release().
   40  *
   41  * If the positioning service is already active when le_posCtrl_Request() is called, it will remain
   42  * active.  This happens if another application has already requested that the positioning service
   43  * be activated and not yet released the positioning service.
   44  *
   45  * The positioning service (and associated devices) will not necessarily be switched off when
   46  * an application calls le_posCtrl_Release(). The positioning service will be switched off only
   47  * after all applications that have requested that the positioning service be active have also
   48  * released the positioning service.
   49  *
   50  * @note    Control of the positioning service is done through a separate API than the retrieval
   51  *          of positioning information to allow access to positioning information by less-trusted
   52  *          applications, while only allowing control of the positioning system by more-trusted
   53  *          applications.
   54  *
   55  * <HR>
   56  *
   57  * Copyright (C) Sierra Wireless Inc.
   58  */
   59 /**
   60  * @file le_posCtrl_interface.h
   61  *
   62  * Legato @ref c_posCtrl include file.
   63  *
   64  * Copyright (C) Sierra Wireless Inc.
   65  */
   66 
   67 #ifndef LE_POSCTRL_INTERFACE_H_INCLUDE_GUARD
   68 #define LE_POSCTRL_INTERFACE_H_INCLUDE_GUARD
   69 
   70 
   71 #include "legato.h"
   72 
   73 
   74 //--------------------------------------------------------------------------------------------------
   75 /**
   76  * Type for handler called when a server disconnects.
   77  */
   78 //--------------------------------------------------------------------------------------------------
   79 typedef void (*le_posCtrl_DisconnectHandler_t)(void *);
   80 
   81 //--------------------------------------------------------------------------------------------------
   82 /**
   83  *
   84  * Connect the current client thread to the service providing this API. Block until the service is
   85  * available.
   86  *
   87  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
   88  * called before any other functions in this API.  Normally, ConnectService is automatically called
   89  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
   90  *
   91  * This function is created automatically.
   92  */
   93 //--------------------------------------------------------------------------------------------------
   94 void le_posCtrl_ConnectService
   95 (
   96     void
   97 );
   98 
   99 //--------------------------------------------------------------------------------------------------
  100 /**
  101  *
  102  * Try to connect the current client thread to the service providing this API. Return with an error
  103  * if the service is not available.
  104  *
  105  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  106  * called before any other functions in this API.  Normally, ConnectService is automatically called
  107  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  108  *
  109  * This function is created automatically.
  110  *
  111  * @return
  112  *  - LE_OK if the client connected successfully to the service.
  113  *  - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
  114  *    bound.
  115  *  - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
  116  *  - LE_COMM_ERROR if the Service Directory cannot be reached.
  117  */
  118 //--------------------------------------------------------------------------------------------------
  119 le_result_t le_posCtrl_TryConnectService
  120 (
  121     void
  122 );
  123 
  124 //--------------------------------------------------------------------------------------------------
  125 /**
  126  * Set handler called when server disconnection is detected.
  127  *
  128  * When a server connection is lost, call this handler then exit with LE_FATAL.  If a program wants
  129  * to continue without exiting, it should call longjmp() from inside the handler.
  130  */
  131 //--------------------------------------------------------------------------------------------------
  132 void le_posCtrl_SetServerDisconnectHandler
  133 (
  134     le_posCtrl_DisconnectHandler_t disconnectHandler,
  135     void *contextPtr
  136 );
  137 
  138 //--------------------------------------------------------------------------------------------------
  139 /**
  140  *
  141  * Disconnect the current client thread from the service providing this API.
  142  *
  143  * Normally, this function doesn't need to be called. After this function is called, there's no
  144  * longer a connection to the service, and the functions in this API can't be used. For details, see
  145  * @ref apiFilesC_client.
  146  *
  147  * This function is created automatically.
  148  */
  149 //--------------------------------------------------------------------------------------------------
  150 void le_posCtrl_DisconnectService
  151 (
  152     void
  153 );
  154 
  155 
  156 //--------------------------------------------------------------------------------------------------
  157 /**
  158  * Reference type for dealing with Position Service management.
  159  */
  160 //--------------------------------------------------------------------------------------------------
  161 typedef struct le_posCtrl_Activation* le_posCtrl_ActivationRef_t;
  162 
  163 
  164 //--------------------------------------------------------------------------------------------------
  165 /**
  166  * Request activation of the positioning service.
  167  *
  168  * @return
  169  *      - Reference to the service activation request (to be used later for releasing the request).
  170  *      - NULL if the service request could not be processed.
  171  *
  172  */
  173 //--------------------------------------------------------------------------------------------------
  174 le_posCtrl_ActivationRef_t le_posCtrl_Request
  175 (
  176     void
  177 );
  178 
  179 //--------------------------------------------------------------------------------------------------
  180 /**
  181  * Release the positioning service.
  182  *
  183  */
  184 //--------------------------------------------------------------------------------------------------
  185 void le_posCtrl_Release
  186 (
  187     le_posCtrl_ActivationRef_t ref
  188         ///< [IN] Reference to a positioning service activation request.
  189 );
  190 
  191 #endif // LE_POSCTRL_INTERFACE_H_INCLUDE_GUARD
le_result_t
le_result_t
Definition: le_basics.h:35


le_posCtrl_TryConnectService
le_result_t le_posCtrl_TryConnectService(void)


le_posCtrl_Release
void le_posCtrl_Release(le_posCtrl_ActivationRef_t ref)


le_posCtrl_DisconnectService
void le_posCtrl_DisconnectService(void)


le_posCtrl_DisconnectHandler_t
void(* le_posCtrl_DisconnectHandler_t)(void *)
Definition: le_posCtrl_interface.h:79



le_posCtrl_ConnectService
void le_posCtrl_ConnectService(void)


le_posCtrl_ActivationRef_t
struct le_posCtrl_Activation * le_posCtrl_ActivationRef_t
Definition: le_posCtrl_interface.h:161


le_posCtrl_Request
le_posCtrl_ActivationRef_t le_posCtrl_Request(void)


le_posCtrl_SetServerDisconnectHandler
void le_posCtrl_SetServerDisconnectHandler(le_posCtrl_DisconnectHandler_t disconnectHandler, void *contextPtr)