le_posCtrl_interface.h

    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 // Internal includes for this interface
   74 #include "le_posCtrl_common.h"
   75 /** @addtogroup le_posCtrl le_posCtrl API Reference
   76  * @{
   77  * @file le_posCtrl_common.h
   78  * @file le_posCtrl_interface.h **/
   79 //--------------------------------------------------------------------------------------------------
   80 /**
   81  * Type for handler called when a server disconnects.
   82  */
   83 //--------------------------------------------------------------------------------------------------
   84 typedef void (*le_posCtrl_DisconnectHandler_t)(void *);
   85 
   86 //--------------------------------------------------------------------------------------------------
   87 /**
   88  *
   89  * Connect the current client thread to the service providing this API. Block until the service is
   90  * available.
   91  *
   92  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
   93  * called before any other functions in this API.  Normally, ConnectService is automatically called
   94  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
   95  *
   96  * This function is created automatically.
   97  */
   98 //--------------------------------------------------------------------------------------------------
   99 void le_posCtrl_ConnectService
  100 (
  101     void
  102 );
  103 
  104 //--------------------------------------------------------------------------------------------------
  105 /**
  106  *
  107  * Try to connect the current client thread to the service providing this API. Return with an error
  108  * if the service is not available.
  109  *
  110  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  111  * called before any other functions in this API.  Normally, ConnectService is automatically called
  112  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  113  *
  114  * This function is created automatically.
  115  *
  116  * @return
  117  *  - LE_OK if the client connected successfully to the service.
  118  *  - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
  119  *    bound.
  120  *  - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
  121  *  - LE_COMM_ERROR if the Service Directory cannot be reached.
  122  */
  123 //--------------------------------------------------------------------------------------------------
  124 le_result_t le_posCtrl_TryConnectService
  125 (
  126     void
  127 );
  128 
  129 //--------------------------------------------------------------------------------------------------
  130 /**
  131  * Set handler called when server disconnection is detected.
  132  *
  133  * When a server connection is lost, call this handler then exit with LE_FATAL.  If a program wants
  134  * to continue without exiting, it should call longjmp() from inside the handler.
  135  */
  136 //--------------------------------------------------------------------------------------------------
  137 LE_FULL_API void le_posCtrl_SetServerDisconnectHandler
  138 (
  139     le_posCtrl_DisconnectHandler_t disconnectHandler,
  140     void *contextPtr
  141 );
  142 
  143 //--------------------------------------------------------------------------------------------------
  144 /**
  145  *
  146  * Disconnect the current client thread from the service providing this API.
  147  *
  148  * Normally, this function doesn't need to be called. After this function is called, there's no
  149  * longer a connection to the service, and the functions in this API can't be used. For details, see
  150  * @ref apiFilesC_client.
  151  *
  152  * This function is created automatically.
  153  */
  154 //--------------------------------------------------------------------------------------------------
  155 void le_posCtrl_DisconnectService
  156 (
  157     void
  158 );
  159 
  160 
  161 //--------------------------------------------------------------------------------------------------
  162 /**
  163  * Reference type for dealing with Position Service management.
  164  */
  165 //--------------------------------------------------------------------------------------------------
  166 
  167 
  168 //--------------------------------------------------------------------------------------------------
  169 /**
  170  * Request activation of the positioning service.
  171  *
  172  * @return
  173  *      - Reference to the service activation request (to be used later for releasing the request).
  174  *      - NULL if the service request could not be processed.
  175  *
  176  */
  177 //--------------------------------------------------------------------------------------------------
  178 le_posCtrl_ActivationRef_t le_posCtrl_Request
  179 (
  180     void
  181 );
  182 
  183 //--------------------------------------------------------------------------------------------------
  184 /**
  185  * Release the positioning service.
  186  *
  187  */
  188 //--------------------------------------------------------------------------------------------------
  189 void le_posCtrl_Release
  190 (
  191     le_posCtrl_ActivationRef_t ref
  192         ///< [IN] Reference to a positioning service activation request.
  193 );
  194 
  195 /** @} **/
  196 
  197 #endif // LE_POSCTRL_INTERFACE_H_INCLUDE_GUARD
le_result_t
le_result_t
Definition: le_basics.h:46
le_posCtrl_ActivationRef_t
struct le_posCtrl_Activation * le_posCtrl_ActivationRef_t
Definition: le_posCtrl_common.h:33
le_posCtrl_SetServerDisconnectHandler
LE_FULL_API void le_posCtrl_SetServerDisconnectHandler(le_posCtrl_DisconnectHandler_t disconnectHandler, void *contextPtr)
le_posCtrl_ConnectService
void le_posCtrl_ConnectService(void)
le_posCtrl_Release
void le_posCtrl_Release(le_posCtrl_ActivationRef_t ref)
le_posCtrl_DisconnectHandler_t
void(* le_posCtrl_DisconnectHandler_t)(void *)
Definition: le_posCtrl_interface.h:84
LE_FULL_API
#define LE_FULL_API
Definition: le_apiFeatures.h:40
legato.h
le_posCtrl_TryConnectService
le_result_t le_posCtrl_TryConnectService(void)
le_posCtrl_common.h
le_posCtrl_DisconnectService
void le_posCtrl_DisconnectService(void)
le_posCtrl_Request
le_posCtrl_ActivationRef_t le_posCtrl_Request(void)