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 //--------------------------------------------------------------------------------------------------
   76 /**
   77  * Type for handler called when a server disconnects.
   78  */
   79 //--------------------------------------------------------------------------------------------------
   80 typedef void (*le_posCtrl_DisconnectHandler_t)(void *);
   81 
   82 //--------------------------------------------------------------------------------------------------
   83 /**
   84  *
   85  * Connect the current client thread to the service providing this API. Block until the service is
   86  * available.
   87  *
   88  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
   89  * called before any other functions in this API.  Normally, ConnectService is automatically called
   90  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
   91  *
   92  * This function is created automatically.
   93  */
   94 //--------------------------------------------------------------------------------------------------
   95 void le_posCtrl_ConnectService
   96 (
   97     void
   98 );
   99 
  100 //--------------------------------------------------------------------------------------------------
  101 /**
  102  *
  103  * Try to connect the current client thread to the service providing this API. Return with an error
  104  * if the service is not available.
  105  *
  106  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  107  * called before any other functions in this API.  Normally, ConnectService is automatically called
  108  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  109  *
  110  * This function is created automatically.
  111  *
  112  * @return
  113  *  - LE_OK if the client connected successfully to the service.
  114  *  - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
  115  *    bound.
  116  *  - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
  117  *  - LE_COMM_ERROR if the Service Directory cannot be reached.
  118  */
  119 //--------------------------------------------------------------------------------------------------
  120 le_result_t le_posCtrl_TryConnectService
  121 (
  122     void
  123 );
  124 
  125 //--------------------------------------------------------------------------------------------------
  126 /**
  127  * Set handler called when server disconnection is detected.
  128  *
  129  * When a server connection is lost, call this handler then exit with LE_FATAL.  If a program wants
  130  * to continue without exiting, it should call longjmp() from inside the handler.
  131  */
  132 //--------------------------------------------------------------------------------------------------
  133 LE_FULL_API void le_posCtrl_SetServerDisconnectHandler
  134 (
  135     le_posCtrl_DisconnectHandler_t disconnectHandler,
  136     void *contextPtr
  137 );
  138 
  139 //--------------------------------------------------------------------------------------------------
  140 /**
  141  *
  142  * Disconnect the current client thread from the service providing this API.
  143  *
  144  * Normally, this function doesn't need to be called. After this function is called, there's no
  145  * longer a connection to the service, and the functions in this API can't be used. For details, see
  146  * @ref apiFilesC_client.
  147  *
  148  * This function is created automatically.
  149  */
  150 //--------------------------------------------------------------------------------------------------
  151 void le_posCtrl_DisconnectService
  152 (
  153     void
  154 );
  155 
  156 
  157 //--------------------------------------------------------------------------------------------------
  158 /**
  159  * Reference type for dealing with Position Service management.
  160  */
  161 //--------------------------------------------------------------------------------------------------
  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:45
le_posCtrl_DisconnectService
void le_posCtrl_DisconnectService(void)
le_posCtrl_Release
void le_posCtrl_Release(le_posCtrl_ActivationRef_t ref)
le_posCtrl_TryConnectService
le_result_t le_posCtrl_TryConnectService(void)
le_posCtrl_Request
le_posCtrl_ActivationRef_t le_posCtrl_Request(void)
le_posCtrl_DisconnectHandler_t
void(* le_posCtrl_DisconnectHandler_t)(void *)
Definition: le_posCtrl_interface.h:80
LE_FULL_API
#define LE_FULL_API
Definition: le_apiFeatures.h:40
le_posCtrl_ConnectService
void le_posCtrl_ConnectService(void)
le_posCtrl_SetServerDisconnectHandler
LE_FULL_API void le_posCtrl_SetServerDisconnectHandler(le_posCtrl_DisconnectHandler_t disconnectHandler, void *contextPtr)