appd_iot_interface.h File Reference

#include "appd_iot_def.h"

Go to the source code of this file.

Macros
#define	__APPD_IOT_API

Functions
appd_iot_error_code_t	appd_iot_init_sdk (appd_iot_sdk_config_t sdkcfg, appd_iot_device_config_t devcfg) __APPD_IOT_API
	This method Initializes the SDK. This method must be called before all other SDK Apis are called. It is recommened to call this method early in your application's start up sequence. More...
appd_iot_error_code_t	appd_iot_register_network_interface (appd_iot_http_cb_t http_cb) __APPD_IOT_API
	This method registers network interface This method must be called before calling appd_iot_send_all_events(). More...
appd_iot_error_code_t	appd_iot_add_custom_event (appd_iot_custom_event_t custom_event) __APPD_IOT_API
	This method adds custom event data Each call to add event will create a new event. More...
appd_iot_error_code_t	appd_iot_add_network_request_event (appd_iot_network_request_event_t network_request_event) __APPD_IOT_API
	This method adds event data Each call to add event will create a new event. More...
appd_iot_error_code_t	appd_iot_add_error_event (appd_iot_error_event_t error_event) __APPD_IOT_API
	This method adds event data Each call to add event will create a new event. More...
appd_iot_error_code_t	appd_iot_send_all_events (void) __APPD_IOT_API
	This method sends all event data. If events are sent successfuly to collector then they will be flushed out of memory. If there is a network reject with response codes 402, 403 or 429 then events are flushed out of memory and SDK state set to DISABLED. If there is any other network error, events remain in memory for retry. Repeated calls to this API in SDK ENABLED State will retry sending the data in memory to the collector. Use the API appd_iot_clear_all_events() to clear out events in memory if retries are unsuccessful. More...
appd_iot_error_code_t	appd_iot_clear_all_events (void) __APPD_IOT_API
	This method removes all event data stored in memory This call is not needed if appd_iot_send_all_events return SUCCESS. More...
appd_iot_error_code_t	appd_iot_check_app_status (void) __APPD_IOT_API
	Use this API to check with AppDynamics Collector on the status of IoT Application on AppDynamics Controller, whether instrumentation is enabled or not. If the Collector returns Success, SDK gets ENABLED in case it has been DISABLED previously by Collector due to license expiry, kill switch or data limit exceeded. It is required that SDK initialization is already done using the API appd_iot_init_sdk() before calling this function. More...

Macro Definition Documentation

__APPD_IOT_API

#define __APPD_IOT_API

Attribute added to all the API's that need to be made public outside of appdynamics iot shared dynamic library.

Function Documentation

appd_iot_init_sdk()

appd_iot_error_code_t appd_iot_init_sdk	(	appd_iot_sdk_config_t	sdkcfg,
		appd_iot_device_config_t	devcfg
	)

This method Initializes the SDK.
This method must be called before all other SDK Apis are called.
It is recommened to call this method early in your application's start up sequence.

Parameters

sdkcfg	contains sdk configuration such as collector url, appkey etc
devcfg	contains device configuration such as device type/name and hw/fw/sw versions

Returns

appd_iot_error_code_t Error code indicating if the function call is a success or fail. Error code returned provides more details on the type of error occurred.

This method Initializes the SDK.
This method must be called before all other SDK Apis are called.
It is recommened to call this method early in your application's start up sequence.

Parameters

sdkcfg	contains sdk configuration such as collector url, appkey etc
devcfg	contains device information such as device type/name and hw/fw/sw versions

Returns

appd_iot_error_code_t Error code indicating if the function call is a success or fail. Error code returned provides more details on the type of error occurred.

{
  std::string eum_collector_url;
  appd_iot_error_code_t retcode;

  /* Process Log Config */
  if (sdkcfg.log_level >= APPD_IOT_LOG_OFF && sdkcfg.log_level <= APPD_IOT_LOG_ALL)
  {
    global_sdk_config.log_level = sdkcfg.log_level;
  }
  else
  {
    global_sdk_config.log_level = APPD_IOT_LOG_ERROR;
  }

  if (global_sdk_config.log_level != APPD_IOT_LOG_OFF)
  {
    global_sdk_config.log_write_cb = sdkcfg.log_write_cb;
  }

  /* Process Device Config */
  retcode = appd_iot_init_device_config(devcfg);

  if (retcode != APPD_IOT_SUCCESS)
  {
    appd_iot_log(APPD_IOT_LOG_ERROR, "Device Config Initialization Failed");
    return retcode;
  }

  /* Process SDK Config */
  if (sdkcfg.appkey == NULL)
  {
    appd_iot_log(APPD_IOT_LOG_ERROR, "AppKey cannot be NULL");
    return APPD_IOT_ERR_INVALID_INPUT;
  }

  global_sdk_config.appkey = sdkcfg.appkey;

  if (sdkcfg.eum_collector_url == NULL)
  {
    eum_collector_url = default_eum_collector_url;
    appd_iot_log(APPD_IOT_LOG_ERROR, "EUM collector URL is NULL, setting to default:%s",
                 default_eum_collector_url.c_str());
  }
  else
  {
    eum_collector_url = sdkcfg.eum_collector_url;
  }

  if (eum_collector_url.at(eum_collector_url.length() - 1) != '/')
  {
    eum_collector_url = eum_collector_url + "/";
  }

  global_sdk_config.eum_collector_url =
    eum_collector_url + appd_iot_eum_collector_url_appkey_prefix +
    global_sdk_config.appkey + appd_iot_eum_collector_url_beacons_suffix;

  global_sdk_config.eum_appkey_enabled_url =
    eum_collector_url + appd_iot_eum_collector_url_appkey_prefix +
    global_sdk_config.appkey + appd_iot_eum_collector_url_enabled_suffix;

  appd_iot_log(APPD_IOT_LOG_INFO, "EUM Collector URL %s", global_sdk_config.eum_collector_url.c_str());


  if (sdkcfg.sdk_state_change_cb != NULL)
  {
    global_sdk_config.sdk_state_change_cb = sdkcfg.sdk_state_change_cb;
  }

  appd_iot_set_sdk_state(APPD_IOT_SDK_ENABLED);

  return APPD_IOT_SUCCESS;
}

appd_iot_register_network_interface()

appd_iot_error_code_t appd_iot_register_network_interface

(

appd_iot_http_cb_t

http_cb

)

This method registers network interface
This method must be called before calling appd_iot_send_all_events().

Parameters

http_cb

contains function pointers for http req send and http resp done callbacks . http request send callback will be called when appd_iot_send_all_events is triggered. http response done callback will be called after send http req callback returns and resp is processed.

Returns

appd_iot_error_code_t Error code indicating if the function call is a success or fail.
Error code returned provides more details on the type of error occurred.

This method registers network interface
This method must be called before calling appd_iot_send_all_events().

Parameters

http_cb

contains function pointers for http request send and http response done callbacks . http request send callback will be called when appd_iot_send_all_events is triggered. http response done callback will be called after send http request callback returns and response is processed.

Returns

appd_iot_error_code_t Error code indicating if the function call is a success or fail. Error code returned provides more details on the type of error occurred.

{
  if (http_cb.http_req_send_cb == NULL)
  {
    appd_iot_log(APPD_IOT_LOG_ERROR, "http_req_send_cb is NULL");
    return APPD_IOT_ERR_INVALID_INPUT;
  }

  if (http_cb.http_resp_done_cb == NULL)
  {
    appd_iot_log(APPD_IOT_LOG_ERROR, "http_resp_done_cb is NULL");
    return APPD_IOT_ERR_INVALID_INPUT;
  }

  global_sdk_config.http_cb.http_req_send_cb = http_cb.http_req_send_cb;
  global_sdk_config.http_cb.http_resp_done_cb = http_cb.http_resp_done_cb;

  return APPD_IOT_SUCCESS;
}

appd_iot_add_custom_event()

appd_iot_error_code_t appd_iot_add_custom_event

(

appd_iot_custom_event_t

custom_event

)

This method adds custom event data
Each call to add event will create a new event.

Parameters

custom_event

contains details of the event

Returns

appd_iot_error_code_t Error code indicating if the function call is a success or fail. Error code returned provides more details on the type of error occurred.

This method adds custom event data
Each call to add event will create a new event.

Parameters

custom_event

contains event data

Returns

appd_iot_error_code_t indicating function execution status

{
  appd_iot_error_code_t retcode;
  appd_iot_sdk_state_t sdk_state;
  custom_event_t event;

  if ((sdk_state = appd_iot_get_sdk_state()) != APPD_IOT_SDK_ENABLED)
  {
    appd_iot_log(APPD_IOT_LOG_ERROR, "Add Custom Event Failed. SDK Not in Enabled State:%s",
                 appd_iot_sdk_state_to_str(sdk_state));

    return APPD_IOT_ERR_SDK_NOT_ENABLED;
  }

  if (custom_event.type != NULL)
  {
    event.type = appd_iot_remove_character(custom_event.type, '|');
  }
  else
  {
    appd_iot_log(APPD_IOT_LOG_WARN, "Custom Event Type cannot be NULL");
  }

  if (custom_event.summary != NULL)
  {
    event.summary = custom_event.summary;
  }
  else
  {
    appd_iot_log(APPD_IOT_LOG_WARN, "Custom Event Summary is NULL");
  }

  event.timestamp_ms = custom_event.timestamp_ms;
  event.duration_ms = custom_event.duration_ms;
  retcode = APPD_IOT_SUCCESS;

  if (custom_event.data_count > 0)
  {
    retcode = appd_iot_copy_event_data(&event.data, custom_event.data,
                                       custom_event.data_count);

    if (retcode != APPD_IOT_SUCCESS)
    {
      appd_iot_log(APPD_IOT_LOG_WARN, "Failed to parse custom event data, error:%s",
                   appd_iot_error_code_to_str(retcode));

      appd_iot_clear_event_data(&event.data);
    }
  }

  appd_iot_log(APPD_IOT_LOG_INFO, "Adding Custom Event with Type:%s", event.type.c_str());

  retcode = appd_iot_add_custom_event_to_beacon(event);

  return retcode;
}

appd_iot_add_network_request_event()

appd_iot_error_code_t appd_iot_add_network_request_event

(

appd_iot_network_request_event_t

network_request_event

)

This method adds event data
Each call to add event will create a new event.

Parameters

network_request_event

contains details of the network request

Returns

appd_iot_error_code_t Error code indicating if the function call is a success or fail. Error code returned provides more details on the type of error occurred.

This method adds event data
Each call to add event will create a new event.

Parameters

network_request_event

contains network event data

Returns

appd_iot_error_code_t indicating function execution status

{
  appd_iot_error_code_t retcode;
  appd_iot_sdk_state_t sdk_state;
  network_request_event_t event;

  if ((sdk_state = appd_iot_get_sdk_state()) != APPD_IOT_SDK_ENABLED)
  {
    appd_iot_log(APPD_IOT_LOG_ERROR, "Add Network Event Failed. SDK Not in Enabled State:%s",
                 appd_iot_sdk_state_to_str(sdk_state));

    return APPD_IOT_ERR_SDK_NOT_ENABLED;
  }

  if (network_request_event.url == NULL)
  {
    appd_iot_log(APPD_IOT_LOG_ERROR, "URL field cannot be NULL");
    return APPD_IOT_ERR_INVALID_INPUT;
  }

  if (network_request_event.error == NULL &&
      !appd_iot_is_valid_http_resp_code(network_request_event.resp_code))
  {
    appd_iot_log(APPD_IOT_LOG_WARN, "Network Error or valid Response Code needs to be populated");
  }

  if (strncmp(network_request_event.url,
              appd_iot_get_eum_collector_url(),
              strlen(network_request_event.url)) == 0)
  {
    appd_iot_log(APPD_IOT_LOG_WARN, "Skip Adding Network Event with Event URL same as APPD EUM Collector URL:%s",
                 network_request_event.url);
    return APPD_IOT_ERR_NOT_SUPPORTED;
  }

  retcode = APPD_IOT_SUCCESS;
  event.url = network_request_event.url;

  if (network_request_event.error != NULL)
  {
    event.error = network_request_event.error;
  }

  if (appd_iot_is_valid_http_resp_code(network_request_event.resp_code))
  {
    event.resp_code = network_request_event.resp_code;
  }
  else
  {
    event.resp_code = 0;
  }

  event.req_content_length = network_request_event.req_content_length;
  event.resp_content_length = network_request_event.resp_content_length;
  event.timestamp_ms = network_request_event.timestamp_ms;
  event.duration_ms = network_request_event.duration_ms;

  if (network_request_event.resp_headers_count > 0)
  {
    retcode = appd_iot_copy_response_headers_data(&event.resp_headers,
              network_request_event.resp_headers,
              network_request_event.resp_headers_count);

    if (retcode != APPD_IOT_SUCCESS)
    {
      appd_iot_log(APPD_IOT_LOG_ERROR, "Failed to parse network event response headers, error:%s",
                   appd_iot_error_code_to_str(retcode));

      appd_iot_clear_event_data(&event.resp_headers);
    }
  }

  if (network_request_event.data_count > 0)
  {
    retcode = appd_iot_copy_event_data(&event.data, network_request_event.data,
                                       network_request_event.data_count);

    if (retcode != APPD_IOT_SUCCESS)
    {
      appd_iot_log(APPD_IOT_LOG_WARN, "Failed to parse Network event data, error:%s",
                   appd_iot_error_code_to_str(retcode));

      appd_iot_clear_event_data(&event.data);
    }
  }

  appd_iot_log(APPD_IOT_LOG_INFO, "Adding Network Event with URL:%s", event.url.c_str());

  retcode = appd_iot_add_network_request_event_to_beacon(event);

  return retcode;
}

appd_iot_add_error_event()

appd_iot_error_code_t appd_iot_add_error_event

(

appd_iot_error_event_t

error_event

)

This method adds event data
Each call to add event will create a new event.

Parameters

error_event

contains details of the error event

Returns

appd_iot_error_code_t Error code indicating if the function call is a success or fail. Error code returned provides more details on the type of error occurred.

This method adds event data
Each call to add event will create a new event.

Parameters

error_event

contains event data

Returns

appd_iot_error_code_t indicating function execution status

{
  appd_iot_error_code_t retcode;
  appd_iot_sdk_state_t sdk_state;
  error_event_t event;

  if ((sdk_state = appd_iot_get_sdk_state()) != APPD_IOT_SDK_ENABLED)
  {
    appd_iot_log(APPD_IOT_LOG_ERROR, "Add Error Event Failed. SDK Not in Enabled State:%s",
                 appd_iot_sdk_state_to_str(sdk_state));

    return APPD_IOT_ERR_SDK_NOT_ENABLED;
  }

  retcode = APPD_IOT_SUCCESS;
  event.timestamp_ms = error_event.timestamp_ms;
  event.duration_ms = error_event.duration_ms;

  if (error_event.name != NULL)
  {
    event.name = error_event.name;
  }
  else
  {
    appd_iot_log(APPD_IOT_LOG_WARN, "Error Event Name cannot be NULL");
  }

  if (error_event.message != NULL)
  {
    event.message = error_event.message;
  }

  if (error_event.severity < APPD_IOT_ERR_MAX_SEVERITY_LEVELS)
  {
    event.severity = severity_str[error_event.severity];
  }
  else
  {
    event.severity = severity_str[APPD_IOT_ERR_SEVERITY_CRITICAL];
  }

  if (error_event.stack_trace_count > 0)
  {
    if (error_event.error_stack_trace_index >= error_event.stack_trace_count)
    {
      appd_iot_log(APPD_IOT_LOG_ERROR, "Invalid error stack trace index, setting to index 0");

      event.error_stack_trace_index = 0;
    }
    else
    {
      event.error_stack_trace_index = error_event.error_stack_trace_index;
    }

    retcode = appd_iot_copy_stack_trace(&event.stack_trace_list,
                                        error_event.stack_trace,
                                        error_event.stack_trace_count);

    if (retcode != APPD_IOT_SUCCESS)
    {
      appd_iot_log(APPD_IOT_LOG_ERROR, "Failed to parse stack traces, error:%s",
                   appd_iot_error_code_to_str(retcode));

      event.stack_trace_list.clear();
    }
  }
  else
  {
    appd_iot_log(APPD_IOT_LOG_INFO, "No stack traces present");
  }

  if (error_event.data_count > 0)
  {
    retcode = appd_iot_copy_event_data(&event.data, error_event.data,
                                       error_event.data_count);

    if (retcode != APPD_IOT_SUCCESS)
    {
      appd_iot_log(APPD_IOT_LOG_ERROR, "Failed to parse error event data, error:%s",
                   appd_iot_error_code_to_str(retcode));

      appd_iot_clear_event_data(&event.data);
    }
  }

  appd_iot_log(APPD_IOT_LOG_INFO, "Adding Error Event with name:%s", error_event.name);

  retcode = appd_iot_add_error_event_to_beacon(event);

  return retcode;
}

appd_iot_send_all_events()

appd_iot_error_code_t appd_iot_send_all_events

(

void

)

This method sends all event data.
If events are sent successfuly to collector then they will be flushed out of memory.
If there is a network reject with response codes 402, 403 or 429 then events are flushed out of memory and SDK state set to DISABLED. If there is any other network error, events remain in memory for retry. Repeated calls to this API in SDK ENABLED State will retry sending the data in memory to the collector.
Use the API appd_iot_clear_all_events() to clear out events in memory if retries are unsuccessful.

Returns

appd_iot_error_code_t Error code indicating if the function call is a success or fail. Error code returned provides more details on the type of error occurred.

This method sends all event data.
If events are sent successfuly to collector then they will be flushed out of memory.
If there is a network reject with response codes 402, 403 or 429 then events are flushed out of memory and SDK state set to DISABLED. If there is any other network error, events remain in memory for retry. Repeated calls to this API in SDK ENABLED State will retry sending the data in memory to the collector.
Use the API appd_iot_clear_all_events() to clear out events in memory if retries are unsuccessful.

Returns

appd_iot_error_code_t indicating function execution status

{
  appd_iot_sdk_state_t sdk_state;

  if ((sdk_state = appd_iot_get_sdk_state()) != APPD_IOT_SDK_ENABLED)
  {
    appd_iot_log(APPD_IOT_LOG_ERROR, "Send All Events Failed. SDK Not in Enabled State:%s",
                 appd_iot_sdk_state_to_str(sdk_state));

    return APPD_IOT_ERR_SDK_NOT_ENABLED;
  }

  return appd_iot_send_all_beacons();
}

appd_iot_clear_all_events()

appd_iot_error_code_t appd_iot_clear_all_events

(

void

)

This method removes all event data stored in memory
This call is not needed if appd_iot_send_all_events return SUCCESS.

Returns

appd_iot_error_code_t Error code indicating if the function call is a success or fail. Error code returned provides more details on the type of error occurred.

This method removes all event data stored in memory
This call is not needed if appd_iot_send_all_events return SUCCESS.

Returns

appd_iot_error_code_t indicating function execution status

{
  appd_iot_sdk_state_t sdk_state;

  if ((sdk_state = appd_iot_get_sdk_state()) != APPD_IOT_SDK_ENABLED)
  {
    appd_iot_log(APPD_IOT_LOG_ERROR, "Clear All Events Failed. SDK Not in Enabled State:%s",
                 appd_iot_sdk_state_to_str(sdk_state));

    return APPD_IOT_ERR_SDK_NOT_ENABLED;
  }

  return appd_iot_clear_all_beacons();
}

appd_iot_check_app_status()

appd_iot_error_code_t appd_iot_check_app_status

(

void

)

Use this API to check with AppDynamics Collector on the status of IoT Application on AppDynamics Controller, whether instrumentation is enabled or not. If the Collector returns Success, SDK gets ENABLED in case it has been DISABLED previously by Collector due to license expiry, kill switch or data limit exceeded.
It is required that SDK initialization is already done using the API appd_iot_init_sdk() before calling this function.

Returns

appd_iot_error_code_t will indicate success if app is enabled

{
  appd_iot_sdk_state_t curr_sdk_state = appd_iot_get_sdk_state();

  if (curr_sdk_state == APPD_IOT_SDK_UNINITIALIZED)
  {
    appd_iot_log(APPD_IOT_LOG_ERROR, "SDK is Uninitalized. Call Init SDK before calling this API");
    return APPD_IOT_ERR_SDK_NOT_ENABLED;
  }

  /* Init all the data structures - REQ and RESP */
  appd_iot_http_req_t http_req;
  appd_iot_http_resp_t* http_resp = NULL;
  appd_iot_error_code_t retcode = APPD_IOT_SUCCESS;
  appd_iot_http_req_send_cb_t http_req_send_cb = appd_iot_get_http_req_send_cb();
  appd_iot_http_resp_done_cb_t http_resp_done_cb = appd_iot_get_http_resp_done_cb();

  if (http_req_send_cb == NULL)
  {
    appd_iot_log(APPD_IOT_LOG_ERROR, "Network Interface Not Available");
    return APPD_IOT_ERR_NETWORK_NOT_AVAILABLE;
  }

  appd_iot_init_to_zero(&http_req, sizeof(http_req));

  http_req.type = "GET";
  http_req.url = global_sdk_config.eum_appkey_enabled_url.c_str();

  http_resp = http_req_send_cb(&http_req);

  /* check if any error present in http response */
  if (http_resp != NULL)
  {
    retcode = http_resp->error;
  }
  else
  {
    appd_iot_log(APPD_IOT_LOG_ERROR, "NULL HTTP Response Returned");
    retcode = APPD_IOT_ERR_NULL_PTR;
  }

  /* Return if there is an error executing http req */
  if (retcode != APPD_IOT_SUCCESS)
  {
    appd_iot_log(APPD_IOT_LOG_ERROR, "Error Executing HTTP Request, ErrorCode:%d", retcode);

    if (http_resp_done_cb != NULL)
    {
      http_resp_done_cb(http_resp);
    }

    return retcode;
  }

  if (http_resp->resp_code >= 200 && http_resp->resp_code < 300)
  {
    appd_iot_set_sdk_state(APPD_IOT_SDK_ENABLED);
    appd_iot_log(APPD_IOT_LOG_INFO, "RespCode:%d Application is Enabled on Controller", http_resp->resp_code);
    retcode = APPD_IOT_SUCCESS;
  }
  else if ((http_resp->resp_code == 402) ||
           (http_resp->resp_code == 403) ||
           (http_resp->resp_code == 429))
  {
    appd_iot_disable_sdk(http_resp->resp_code);
    retcode = APPD_IOT_ERR_NETWORK_REJECT;
  }
  else
  {
    appd_iot_log(APPD_IOT_LOG_ERROR, "Resp Code:%d Network Request to Check App Status Failed",
                 http_resp->resp_code);
    retcode = APPD_IOT_ERR_NETWORK_ERROR;
  }

  if (http_resp_done_cb != NULL)
  {
    http_resp_done_cb(http_resp);
  }

  return retcode;
}