cmdamt/Include/IMRSDK.h

   1 // Copyright (C) Intel Corporation, 2003 - 2006.\r
   2 \r
   3 #ifndef _IMR_SDK_H_\r
   4 #define _IMR_SDK_H_\r
   5 \r
   6 #define EXPORTED_FUNC\r
   7 \r
   8 #ifdef __cplusplus\r
   9 extern "C" {\r
  10 #endif // __cplusplus\r
  11 \r
  12 #ifndef BOOL\r
  13         typedef int            BOOL;\r
  14         #define TRUE                    1\r
  15         #define FALSE                   0\r
  16 #endif\r
  17 \r
  18 #define MAX_IP_LEN                      128\r
  19 #define MAX_NAME_LEN            128\r
  20 #define MAX_COMP_NAME           128\r
  21 #define MAX_PSWD_LEN            128\r
  22 #define KEY_LEN                         20\r
  23 #define GUID_LEN                        16\r
  24 \r
  25 // SOL spec defines text length as maximum 255\r
  26 #define MAX_SOL_MESSAGE         0xFF\r
  27 \r
  28 #define INVALID_CLIENT_ID (unsigned long)-1\r
  29 typedef unsigned long ClientID;\r
  30 \r
  31 #define INVALID_SESSION_ID (unsigned long)-1\r
  32 typedef unsigned long SessionID;\r
  33 \r
  34 \r
  35 typedef enum {\r
  36         IMR_RES_OK, \r
  37         IMR_RES_ERROR, \r
  38         IMR_RES_INVALID_PARAMETER,\r
  39         IMR_RES_NOT_INITIALIZED,\r
  40         IMR_RES_ALREADY_INITIALIZED,\r
  41         IMR_RES_MEMALLOC_FAILED,\r
  42         IMR_RES_UNSUPPORTED,\r
  43         IMR_RES_CLIENT_NOT_FOUND,\r
  44         IMR_RES_DUPLICATE_CLIENT,\r
  45         IMR_RES_CLIENT_NOT_ACTIVE,\r
  46         IMR_RES_CLIENT_ACTIVE,\r
  47         IMR_RES_SESSION_ALREADY_OPEN,\r
  48         IMR_RES_SESSION_CLOSED,\r
  49         IMR_RES_SOCKET_ERROR,\r
  50         IMR_RES_UNKNOWN_PROTOCOL,\r
  51         IMR_RES_PROTOCOL_ALREADY_REGISTERED,\r
  52         IMR_RES_PENDING,\r
  53         IMR_RES_UNEXPECTED_PACKET,\r
  54         IMR_RES_TIMEOUT,\r
  55         IMR_RES_CORRUPT_PACKET,\r
  56         IMR_RES_OS_ERROR,\r
  57         IMR_RES_IDER_VERSION_NOT_SUPPORTED,\r
  58         IMR_RES_IDER_COMMAND_RUNNING,\r
  59         IMR_RES_STORAGE_FAILURE,\r
  60         IMR_RES_UNKNOWN,\r
  61         IMR_RES_AUTH_FAILED,\r
  62         IMR_RES_CLIENT_TYPE_UNKNOWN,\r
  63         IMR_RES_CLIENT_BUSY,\r
  64         IMR_RES_CLIENT_UNSUPPORTED,\r
  65         IMR_RES_CLIENT_ERROR,\r
  66         IMR_RES_NOT_ENOUGH_SPACE,\r
  67         IMR_RES_SESSION_LOOPBACK,\r
  68         IMR_RES_TLS_CONNECTION_FAILED,\r
  69 \r
  70         IMR_RES_COUNT,   // must be last entry\r
  71 } IMRResult;\r
  72 \r
  73 typedef struct {\r
  74         unsigned short major;\r
  75         unsigned short minor;\r
  76 } IMRVersion;\r
  77 \r
  78 typedef enum {CLI_TCP = 1, CLI_TLS = 2, CLI_UNKNOWN } ClientType;\r
  79 \r
  80 \r
  81 typedef char GUIDType[GUID_LEN];\r
  82 \r
  83 typedef struct {\r
  84         ClientType      type;\r
  85         char            ip[MAX_IP_LEN];\r
  86         GUIDType        guid;\r
  87 } ClientInfo;\r
  88 \r
  89 \r
  90 //IN Parameter for IDER/SOL session \r
  91 \r
  92 typedef struct {\r
  93         char user_name[MAX_NAME_LEN]; // user name - nul terminated string \r
  94         char user_pswd[MAX_PSWD_LEN]; // user password - nul terminated string \r
  95 } TCPSessionParams;\r
  96 \r
  97 //IN Parameter for SOL session \r
  98 typedef struct {\r
  99         unsigned short  tx_over_timeout;\r
 100         unsigned short  tx_buf_timeout;\r
 101         unsigned short  hb_interval;\r
 102         unsigned short  fifo_rx_flush_timeout;\r
 103         unsigned short  rx_timeout;\r
 104 } SOLTout; \r
 105 \r
 106 //IN Parameter for IDER session \r
 107 typedef struct {\r
 108         unsigned short  rx_timeout;     //client host RX timeout as defined in the IDER spec.\r
 109         unsigned short  tx_timeout; //client host TX timeout as defined in the IDER spec.\r
 110         unsigned short  hb_timeout; //client FW HB interval  as defined in the IDER spec.\r
 111 } IDERTout; \r
 112 \r
 113 //OUT parameter for querying supported IDER client features\r
 114 typedef struct {\r
 115         BOOL ider_dev_pri; //TRUE if client FW supports enable/disable of primary IDE devices\r
 116         BOOL ider_dev_sec; //TRUE if client FW supports enable/disable of secondary IDE devices\r
 117         BOOL reserved[30];\r
 118 }FeaturesSupported;\r
 119 \r
 120 typedef enum {IDER_ENABLE, IDER_DISABLE, IDER_NOP } SetOperation;\r
 121 //Timing options for the IDE device enabling/disabling:\r
 122 //ONRESET - Client should perform command at the next FW RESET.\r
 123 //GRACEFULLY - Client should perform command if there is no other host command in progress.\r
 124 //IMMEDIATELY - Client should perform command immediately.\r
 125 typedef enum {IDER_SET_ONRESET, IDER_SET_GRACEFULLY, IDER_SET_IMMEDIATELY,  } SetOption;\r
 126 \r
 127 typedef enum { IDER_DISABLED, IDER_ENABLED  } DeviceState;\r
 128 \r
 129 //Client returns REJECTED if there is a Host Command in progress\r
 130 //and the Disable/Enable command can't be performed at this time\r
 131 typedef enum { IDER_REJECTED, IDER_DONE } SetResult;\r
 132 \r
 133 //IN parameter for querying client IDE devices state\r
 134 typedef struct  {\r
 135         DeviceState     pri_default;    //Default primary devices state at the Client FW\r
 136         DeviceState     pri_current;    //Current primary devices state at the Client FW\r
 137         DeviceState     sec_default;    //Default secondary devices state at the Client FW\r
 138         DeviceState     sec_current;    //Default secondary devices state at the Client FW\r
 139 } IDERDeviceState;\r
 140 \r
 141 //IN paramter for changing client IDE devices state\r
 142 typedef struct {\r
 143         SetOperation    pri_op;         //Pimary device operation (enable or disable)\r
 144         SetOption               pri_timing; //Pimary device operation timing \r
 145         SetOperation    sec_op;         //Not supported by the SDK yet \r
 146         SetOption               sec_timing; //Not supported by the SDK yet\r
 147 } IDERDeviceCmd;\r
 148 \r
 149 //OUT parameter - IDERDeviceCmd execution result returned by the client\r
 150 typedef struct {\r
 151         SetResult       pri_res;\r
 152         SetResult       sec_res;\r
 153 } IDERDeviceResult;\r
 154 \r
 155 typedef struct {\r
 156                 BOOL                            error_state;    //TRUE if session is in ERROR state\r
 157                 BOOL                            data_transfer;  //TRUE if there is a read/write command in progress\r
 158                 unsigned short          num_reopen;             //number of session re-opens due to error recovery\r
 159                 unsigned long           num_error;              //number of ErrorOccured messages received\r
 160                 unsigned long           num_reset;              //number of ResetOccured messages received\r
 161                 unsigned long           last_cmd_length;//last data transfer (read/write) length in bytes\r
 162                 unsigned long           data_sent;              //bytes of data sent to the client\r
 163                 unsigned long           data_received;  //bytes of data received from the client\r
 164                 unsigned long           packets_sent;   //mesages sent during the session \r
 165                 unsigned long           packets_received;//messages received during the session\r
 166 } IDERStatistics;\r
 167 \r
 168 typedef enum {SEC_LEVEL_NONE, SEC_LEVEL_AUTH, SEC_LEVEL_ENCR, SEC_LEVEL_AUTH_ENCR } SecLevel;\r
 169 \r
 170 typedef enum { SOL_LOOPBACK_NONE = 0, SOL_LOOPBACK_RS232C = 1 } SOLLoopbackMode;\r
 171 \r
 172 \r
 173 //General:\r
 174 EXPORTED_FUNC IMRResult IMR_Init(IMRVersion *version, char *ini_file);\r
 175 EXPORTED_FUNC IMRResult IMR_Close();\r
 176 EXPORTED_FUNC IMRResult IMR_GetErrorStringLen(IMRResult, int * str_len);\r
 177 EXPORTED_FUNC IMRResult IMR_GetErrorString(IMRResult, char *str);\r
 178 EXPORTED_FUNC IMRResult IMR_SetCertificateInfo(const char *root_cert, const char *private_cert, const char *cert_pass);\r
 179 \r
 180 //Client List:\r
 181 EXPORTED_FUNC IMRResult IMR_AddClient( ClientType new_client_type, char *client_ip, GUIDType client_guid, ClientID *new_client_id);\r
 182 EXPORTED_FUNC IMRResult IMR_RemoveClient(ClientID client_id);\r
 183 EXPORTED_FUNC IMRResult IMR_RemoveAllClients();\r
 184 EXPORTED_FUNC IMRResult IMR_GetAllClients(ClientID *client_list, int *client_list_size);\r
 185 \r
 186 EXPORTED_FUNC IMRResult IMR_GetClientInfo(ClientID client_id, ClientInfo * );\r
 187 \r
 188 \r
 189 \r
 190 //SOL:\r
 191 EXPORTED_FUNC IMRResult IMR_SOLOpenTCPSession(ClientID  client_id, TCPSessionParams * params,\r
 192                                                         SOLTout* touts , SOLLoopbackMode *loopback);\r
 193 EXPORTED_FUNC IMRResult IMR_SOLCloseSession(ClientID  client_id);\r
 194 EXPORTED_FUNC IMRResult IMR_SOLSendText(ClientID  client_id, unsigned char *data, int data_len);\r
 195 EXPORTED_FUNC IMRResult IMR_SOLReceiveText(ClientID  client_id, unsigned char *data, int *data_len);\r
 196 \r
 197 //IDER:\r
 198 \r
 199 //\r
 200 //client_id - unique client ID, as returned by the IMR_AddClient\r
 201 //params        - pointer to the IDER over TCP/TLS session paramters structure\r
 202 //touts         - pointer to the IDER over TCP/TLS session timeouts structure\r
 203 //drive0        - floppy drive name for the IDER over TCP/TLS session. should be null terminated.\r
 204 //drive1    - CD drive name for the IDER over TCP/TLS session. should be null terminated.\r
 205 //returns   - IMR_RES_OK on success, error otherwise.\r
 206 //\r
 207 //Use this function to establish a new IDER session with the client. \r
 208 //Function will create a new connection and exchange messages needed in order\r
 209 //to open IDER session. It will return only when the session is established, or \r
 210 //error occured. After the session opening client will initiate data transfers.\r
 211 EXPORTED_FUNC IMRResult IMR_IDEROpenTCPSession(ClientID  client_id, TCPSessionParams * params,\r
 212                                                                 IDERTout* touts ,\r
 213                                                                 char *drive0, char *drive1);\r
 214 //\r
 215 //client_id - unique client ID, as returned by the IMR_AddClient\r
 216 //returns   - IMR_RES_OK on success, error otherwise.\r
 217 //\r
 218 //Use this function to close an active IDER session. After the function returns\r
 219 //no other operations can be done succesfully on the session. Closing a session during \r
 220 //write data operation can cause data corruption. \r
 221 EXPORTED_FUNC IMRResult IMR_IDERCloseSession(ClientID  client_id);\r
 222 //\r
 223 //client_id - unique client ID, as returned by the IMR_AddClient\r
 224 //supported - pointer to the FeaturesSupported structure filled by the SDK\r
 225 //returns   - IMR_RES_OK on success, error otherwise.\r
 226 //Use this function to query the Client about the special features it supports.\r
 227 //Currently the only special feature defined is an ability to disable/enable host IDE devices.\r
 228 EXPORTED_FUNC IMRResult IMR_IDERClientFeatureSupported(ClientID  client_id, FeaturesSupported *supported);\r
 229 //\r
 230 //client_id - unique client ID, as returned by the IMR_AddClient\r
 231 //state         - pointer to the IDERDeviceState structure filled by the SDK\r
 232 //returns   - IMR_RES_OK on success, error otherwise.\r
 233 //Use this function to query host IDE device(s) state. \r
 234 EXPORTED_FUNC IMRResult IMR_IDERGetDeviceState(ClientID  client_id, IDERDeviceState *state);\r
 235 //\r
 236 //client_id - unique client ID, as returned by the IMR_AddClient\r
 237 //cmd           - pointer to the IDERDeviceCmd structure that shoudl contain disable/enable command and options\r
 238 //result        - pointer to the IDERDeviceResult structure filled by the SDK\r
 239 //returns   - IMR_RES_OK on success, error otherwise.\r
 240 //Use this function to control host IDE device(s) state. Devices can be disabled/enabled through\r
 241 //this API. \r
 242 EXPORTED_FUNC IMRResult IMR_IDERSetDeviceState(ClientID  client_id, IDERDeviceCmd *cmd, IDERDeviceResult *result);\r
 243 //\r
 244 //client_id - unique client ID, as returned by the IMR_AddClient\r
 245 //stat          - pointer to the IDERStatistics filled by the SDK\r
 246 //returns   - IMR_RES_OK on success, error otherwise.\r
 247 //\r
 248 //Use this functon in order to poll active IDER session.\r
 249 //If the IDER session for the corresponding client was closed due to timeout/protocol error\r
 250 //function will fill the stat structure with the latest data, but will return IMR_RES_SESSION_CLOSED.\r
 251 EXPORTED_FUNC IMRResult IMR_IDERGetSessionStatistics(ClientID  client_id, IDERStatistics * stat );\r
 252 \r
 253 \r
 254 \r
 255 #ifdef __cplusplus\r
 256 }\r
 257 #endif // __cplusplus\r
 258 \r
 259 #endif //_IMR_SDK_H_\r
 260 \r