framework/IpcClient.h

   1 /*
   2     Copyright (c) 2014, McAfee, Inc.
   3
   4     All rights reserved.
   5
   6     Redistribution and use in source and binary forms, with or without modification,
   7     are permitted provided that the following conditions are met:
   8
   9     Redistributions of source code must retain the above copyright notice, this list
  10     of conditions and the following disclaimer.
  11
  12     Redistributions in binary form must reproduce the above copyright notice, this
  13     list of conditions and the following disclaimer in the documentation and/or other
  14     materials provided with the distribution.
  15
  16     Neither the name of McAfee, Inc. nor the names of its contributors may be used
  17     to endorse or promote products derived from this software without specific prior
  18     written permission.
  19
  20     THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
  21     ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  22     WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  23     IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
  24     INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
  25     BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  26     DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
  27     LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
  28     OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
  29     OF THE POSSIBILITY OF SUCH DAMAGE.
  30 */
  31
  32 #ifndef IPCCLIENT_H
  33 #define IPCCLIENT_H
  34
  35 #ifdef __cplusplus
  36 extern "C" {
  37 #endif
  38
  39 /**
  40  * \file IpcClient.h
  41  * \brief Ipc Client Header File
  42  *
  43  * This file provides the IPC Client API functions used by Security framework.
  44  */
  45
  46 #include "IpcTypes.h"
  47
  48 /*==================================================================================================
  49                                  CONSTANTS & ENUMS
  50 ==================================================================================================*/
  51 #define DEF_TIMEOUT -1
  52
  53
  54 /*==================================================================================================
  55                                      FUNCTION PROTOTYPES
  56 ==================================================================================================*/
  57
  58 /**
  59  * \brief Initializes client side IPC and returns its handle.
  60  *
  61  * Opens and initialises the handle to client side IPC using the security
  62  * framework defaults.
  63  *
  64  * This is a synchronous API.
  65  *
  66  * \return Return Type (TSC_IPC_HANDLE) \n
  67  * Client IPC handle - on success. \n
  68  * NULL - on failure. \n
  69  */
  70 TSC_IPC_HANDLE IpcClientOpen(void);
  71
  72 /**
  73  * \brief Requests the Security framework's IPC server and returns back the reply.
  74  *
  75  * This is a synchronous API.
  76  *
  77  * \param[in] hIpc IPC handle returned by IpcClientOpen().
  78  *
  79  * \return Return Type (void) \n
  80  */
  81 void IpcClientClose(TSC_IPC_HANDLE hIpc);
  82
  83 /**
  84  * \brief Requests the Security framework's IPC server and returns back the reply.
  85  *
  86  * This is a synchronous API.
  87  *
  88  * \param[in] hIpc Client side IPC handle.
  89  * \param[in] szMethod Name of the method called.
  90  * \param[in] argc Number of parameters passed in argv.
  91  * \param[in] argv Array of strings representing parameters for method called.
  92  * \param[out] reply_len Length of the string in reply_argv.
  93  * \param[out] reply_argv Array of strings representing result value from method called.
  94  * \param[in] timeout_milliseconds Timeout in milliseconds. -1 for default or 0 for no timeout.
  95  *
  96  * \return Return Type (int) \n
  97  * 0 - on send success. \n
  98  * -1 - on send failure. \n
  99  */
 100 int TSCSendMessageN(TSC_IPC_HANDLE hIpc, const char *service_name, const char *szMethod, int argc,
 101                     char **argv, int *argc_reply, char ***argv_reply, int timeout_milliseconds);
 102
 103 /**
 104  * \brief Requests the Security framework's IPC server asynchronously.
 105  *
 106  * This is an asynchronous API.
 107  *
 108  * \param[in] hIpc Client side IPC handle.
 109  * \param[in] szMethod Name of the method called.
 110  * \param[in] argc Number of parameters passed in argv.
 111  * \param[in] argv Array of strings representing parameters for method called.
 112  * \param[out] phCallHandle Pointer to handle of the asynchronous message sent.
 113  * \param[in] pCallback Callback function for the asynchronous reply.
 114  * \param[in] pPrivate API caller's context information, to be supplied with callback.
 115  * \param[in] timeout_milliseconds Timeout in milliseconds. -1 for default or 0 for no timeout.
 116  *
 117  * \return Return Type (int) \n
 118  * 0 - on send success. \n
 119  * Error code - on send failure. \n
 120  */
 121 int TSCSendMessageAsync(TSC_IPC_HANDLE hIpc, const char *service_name, const char *szMethod, int argc, char **argv,
 122                         TSC_CALL_HANDLE *phCallHandle, TSCCallback pCallback, void *pPrivate,
 123                         int timeout_milliseconds);
 124
 125 /**
 126  * \brief Releases the asynchronous call handle.
 127  *
 128  * \param[in] hCallHandle Handle of the asynchronous message sent earlier.
 129  */
 130 void TSCFreeSentMessageHandle(TSC_CALL_HANDLE hCallHandle);
 131
 132 /**
 133  * \brief Cancels an asynchronous request previously made to the Security framework's IPC server.
 134  * On success, releases the handle of the previously called asynchronous method.
 135  *
 136  * This is an asynchronous API.
 137  *
 138  * \param[in] hIpc Client side IPC handle.
 139  * \param[in] hCallHandle Handle of the asynchronous message sent earlier.
 140  *
 141  * \return Return Type (int) \n
 142  * 0 - on send success. \n
 143  * Error code - on failure. \n
 144  */
 145 int TSCCancelMessage(TSC_IPC_HANDLE hIpc, TSC_CALL_HANDLE hCallHandle);
 146
 147 #ifdef __cplusplus
 148 }
 149 #endif
 150
 151 #endif  /* IPCCLIENT_H */