LibAwsIot

Documentation not found.

Documentation not found.

Documentation not found.

Documentation not found.

Documentation not found.

Documentation not found.

Documentation not found.

Documentation not found.

__JL_Ctag_205

Documentation not found.

User callback type invoked to retrieve an ip list custom metric

List provided will already be initialized and caller must push items into the list of type (struct aws_string *). String allocated that are placed into the list are destroyed by the defender task after it is done with the list.

returns: AWS_OP_SUCCESS if the custom metric was successfully added to the task config

User callback type invoked to retrieve a number type custom metric.

returns: AWS_OP_SUCCESS if the custom metric was successfully added to the task config

User callback type invoked to retrieve a number list custom metric

List provided will already be initialized and caller must push items into the list of type double.

returns: AWS_OP_SUCCESS if the custom metric was successfully added to the task config

User callback type invoked to retrieve a string list custom metric

List provided will already be initialized and caller must push items into the list of type (struct aws_string *). String allocated that are placed into the list are destroyed by the defender task after it is done with the list.

returns: AWS_OP_SUCCESS if the custom metric was successfully added to the task config

Callback to invoke when the defender task needs to "publish" a report. Useful to override default MQTT publish behavior, for testing report outputs

Notes: * This function should not perform blocking IO. * This function should copy the report if it needs to hold on to the memory for an IO operation

returns: AWS_OP_SUCCESS if the user callback wants to consider the publish failed.

User callback type invoked when the subscribed device defender topic for accepted reports receives a message.

aws_iotdevice_defender_report_format

Documentation not found.

User callback type invoked when a report fails to submit.

There are two possibilities for failed submission: 1. The MQTT client fails to publish the message and returns an error code. In this scenario, the client_error_code will be a value other than AWS_ERROR_SUCCESS. The rejected_message_payload parameter will be NULL. 2. After a successful publish, a reply is received on the respective MQTT rejected topic with a message. In this scenario, the client_error_code will be AWS_ERROR_SUCCESS, and rejected_message_payload will contain the payload of the rejected message received.

Arguments

• rejected_message_payload:[in] response payload recieved from rejection topic
• userdata:[in] callback userdata

Documentation not found.

User callback type invoked when DeviceDefender task has completed cancellation. After a request to stop the task, this signals the completion of the cancellation and no further user callbacks will be invoked.

Arguments

• userdata:[in] callback userdata

Documentation not found.

General callback handler for the task to report that an error occurred while running the DeviceDefender task. Error codes can only go so far in describing where/when and how the failure occur so the errors here may best communicate where/when and the how of the underlying call should be found in log output

Arguments

• is_task_stopped:[in] flag indicating whether or not the task is unable to continue running
• error_code:[in] error code describing the nature of the failure

aws_iotdevice_error

Documentation not found.

aws_iotdevice_log_subject

Documentation not found.

aws_secure_tunnel

Documentation not found.

aws_secure_tunnel_connection_view

Read-only snapshot of a Secure Tunnel Connection Completion Data

aws_secure_tunnel_connections

Documentation not found.

aws_secure_tunnel_field_number

Documentation not found.

Signature of callback to invoke on received messages

aws_secure_tunnel_message_storage

Documentation not found.

aws_secure_tunnel_message_type

Type of IoT Secure Tunnel message. Enum values match IoT Secure Tunneling Local Proxy V3 Websocket Protocol Guide values.

https://github.com/aws-samples/aws-iot-securetunneling-localproxy/blob/main/V3WebSocketProtocolGuide.md

aws_secure_tunnel_message_view

Read-only snapshot of a Secure Tunnel Message

Documentation not found.

Documentation not found.

aws_secure_tunnel_options

Basic Secure Tunnel configuration struct.

Contains connection properties for the creation of a Secure Tunnel

aws_secure_tunnel_options_storage

Documentation not found.

aws_secure_tunnel_protocol_buffer_wire_type

Documentation not found.

aws_secure_tunnel_state

The various states that the secure tunnel can be in. A secure tunnel has both a current state and a desired state. Desired state is only allowed to be one of {STOPPED, CONNECTED, TERMINATED}. The secure tunnel transitions states based on either (1) changes in desired state, or (2) external events.

Most states are interruptible (in the sense of a change in desired state causing an immediate change in state) but CONNECTING cannot be interrupted due to waiting for an asynchronous callback (that has no cancel) to complete.

aws_secure_tunnel_vtable

Documentation not found.

aws_secure_tunneling_local_proxy_mode

Documentation not found.

Signature of callback to invoke on fully established connection to Secure Tunnel Service

Signature of callback to invoke on a connection id stream being reset

Signature of callback to invoke on shutdown of connection to Secure Tunnel Service

Signature of callback to invoke on start of a connection id stream

Signature of callback to invoke on completion of an outbound message

Signature of callback to invoke on session reset recieved from the Secure Tunnel Service

Signature of callback to invoke on Secure Tunnel reaching a STOPPED state

Signature of callback to invoke on a stream being reset

Signature of callback to invoke on the start of a stream

Signature of callback to invoke on termination completion of the Native Secure Tunnel Client

data_tunnel_pair

Documentation not found.

defender_custom_metric_type

Change name if this needs external exposure. Needed to keep track of how to interpret instantiated metrics, and cast the supplier_fn correctly.

aws_iot_st_msg_serialize_from_view(buffer, allocator, message_view)

Documentation not found.

Prototype

int aws_iot_st_msg_serialize_from_view( struct aws_byte_buf *buffer, struct aws_allocator *allocator, const struct aws_secure_tunnel_message_view *message_view);

aws_iotdevice_defender_config_clean_up(config)

Destroys a new reporting task for Device Defender metrics

Arguments

• config:[in] defender task configuration

Prototype

void aws_iotdevice_defender_config_clean_up(struct aws_iotdevice_defender_task_config *config);

aws_iotdevice_defender_config_create(config_out, allocator, thing_name, report_format)

Creates a new reporting task config for Device Defender metrics collection

Arguments

• config_out:[in] output to write a pointer to a task configuration. Will write non-NULL if successful in creating the the task configuration. Will write NULL if there is an error during creation
• allocator:[in] allocator to use for the task configuration's internal data, and the task itself when started
• thing_name:[in] thing name the task config is reporting for
• report_format:[in] report format to produce when publishing to IoT

Returns

AWS_OP_SUCCESS and config_out will be non-NULL. Returns an error code otherwise

Prototype

int aws_iotdevice_defender_config_create( struct aws_iotdevice_defender_task_config **config_out, struct aws_allocator *allocator, const struct aws_byte_cursor *thing_name, enum aws_iotdevice_defender_report_format report_format);

aws_iotdevice_defender_config_register_ip_list_metric(task_config, metric_name, supplier, userdata)

Adds IP list custom metric to the Device Defender task configuration. Has no impact on a defender task already started using the configuration.

Arguments

• task_config:[in] the defender task configuration to register the metric to
• metric_name:[in] UTF8 byte string of the metric name
• supplier:[in] callback function to produce the metric value when requested at report generation time
• userdata:[in] specific callback data for the supplier callback function

Prototype

void aws_iotdevice_defender_config_register_ip_list_metric( struct aws_iotdevice_defender_task_config *task_config, const struct aws_byte_cursor *metric_name, aws_iotdevice_defender_get_ip_list_fn *supplier, void *userdata);

aws_iotdevice_defender_config_register_number_list_metric(task_config, metric_name, supplier, userdata)

Adds number list custom metric to the Device Defender task configuration. Has no impact on a defender task already started using the configuration.

Arguments

• task_config:[in] the defender task configuration to register the metric to
• metric_name:[in] UTF8 byte string of the metric name
• supplier:[in] callback function to produce the metric value when requested at report generation time
• userdata:[in] specific callback data for the supplier callback function

Prototype

void aws_iotdevice_defender_config_register_number_list_metric( struct aws_iotdevice_defender_task_config *task_config, const struct aws_byte_cursor *metric_name, aws_iotdevice_defender_get_number_list_fn *supplier, void *userdata);

aws_iotdevice_defender_config_register_number_metric(task_config, metric_name, supplier, userdata)

Adds number custom metric to the Device Defender task configuration. Has no impact on a defender task already started using the configuration.

Arguments

• task_config:[in] the defender task configuration to register the metric to
• metric_name:[in] UTF8 byte string of the metric name
• supplier:[in] callback function to produce the metric value when requested at report generation time
• userdata:[in] specific callback data for the supplier callback function

Prototype

void aws_iotdevice_defender_config_register_number_metric( struct aws_iotdevice_defender_task_config *task_config, const struct aws_byte_cursor *metric_name, aws_iotdevice_defender_get_number_fn *supplier, void *userdata);

aws_iotdevice_defender_config_register_string_list_metric(task_config, metric_name, supplier, userdata)

Adds string list custom metric to the Device Defender task configuration. Has no impact on a defender task already started using the configuration.

Arguments

• task_config:[in] the defender task configuration to register the metric to
• metric_name:[in] UTF8 byte string of the metric name
• supplier:[in] callback function to produce the metric value when requested at report generation time
• userdata:[in] specific callback data for the supplier callback function

Prototype

void aws_iotdevice_defender_config_register_string_list_metric( struct aws_iotdevice_defender_task_config *task_config, const struct aws_byte_cursor *metric_name, aws_iotdevice_defender_get_string_list_fn *supplier, void *userdata);

aws_iotdevice_defender_config_set_callback_userdata(config, userdata)

Sets the userdata for the device defender task's callback functions

Arguments

• config:[in] defender task configuration
• userdata:[in] how much time in nanoseconds between defender task runs

Returns

AWS_OP_SUCCESS when the property has been set properly. Returns an error code if the value was not able to be set

Prototype

int aws_iotdevice_defender_config_set_callback_userdata( struct aws_iotdevice_defender_task_config *config, void *userdata);

aws_iotdevice_defender_config_set_report_accepted_fn(config, accepted_fn)

Sets the report rejected callback function to invoke when is canceled and not going to be scheduled to run. This is a suggestion of when it is OK to close or free resources kept around while the task is running.

Arguments

• config:[in] defender task configuration
• accepted_fn:[in] accepted report callback function

Returns

AWS_OP_SUCCESS when the report accepted callback has been set. Returns an error if the callback was not set

Prototype

int aws_iotdevice_defender_config_set_report_accepted_fn( struct aws_iotdevice_defender_task_config *config, aws_iotdevice_defender_report_accepted_fn *accepted_fn);

aws_iotdevice_defender_config_set_report_rejected_fn(config, rejected_fn)

Sets the report rejected callback function to invoke when is canceled and not going to be scheduled to run. This is a suggestion of when it is OK to close or free resources kept around while the task is running.

Arguments

• config:[in] defender task configuration
• rejected_fn:[in] rejected report callback function

Returns

AWS_OP_SUCCESS when the report rejected callback has been set. Returns an error if the callback was not set

Prototype

int aws_iotdevice_defender_config_set_report_rejected_fn( struct aws_iotdevice_defender_task_config *config, aws_iotdevice_defender_report_rejected_fn *rejected_fn);

aws_iotdevice_defender_config_set_task_cancelation_fn(config, cancel_fn)

Sets the task cancelation callback function to invoke when the task is canceled and not going to be scheduled to run. This is a suggestion of when it is OK to close or free resources kept around while the task is running.

Arguments

• config:[in] defender task configuration
• cancel_fn:[in] cancelation callback function

Returns

AWS_OP_SUCCESS when the task cancelation callback has been set. Returns an error if the callback was not set

Prototype

int aws_iotdevice_defender_config_set_task_cancelation_fn( struct aws_iotdevice_defender_task_config *config, aws_iotdevice_defender_task_canceled_fn *cancel_fn);

aws_iotdevice_defender_config_set_task_failure_fn(config, failure_fn)

Sets the task failure callback function to invoke when the running of the task encounters a failure. Though this is optional to specify, it is important to register a handler to at least monitor failure that stops the task from running

The most likely scenario for task not being able to continue is failure to reschedule the task

Arguments

• config:[in] defender task configuration
• failure_fn:[in] failure callback function

Returns

AWS_OP_SUCCESS when the task failure callback has been set. Returns an error if the callback was not set

Prototype

int aws_iotdevice_defender_config_set_task_failure_fn( struct aws_iotdevice_defender_task_config *config, aws_iotdevice_defender_task_failure_fn *failure_fn);

aws_iotdevice_defender_config_set_task_period_ns(config, task_period_ns)

Sets the period of the device defender task

Arguments

• config:[in] defender task configuration
• task_period_ns:[in] how much time in nanoseconds between defender task runs

Returns

AWS_OP_SUCCESS when the property has been set properly. Returns an error code if the value was not able to be set.

Prototype

int aws_iotdevice_defender_config_set_task_period_ns( struct aws_iotdevice_defender_task_config *config, uint64_t task_period_ns);

aws_iotdevice_defender_task_clean_up(defender_task)

Cancels the running task reporting Device Defender metrics and cleans up. If the task is currently running, it will block until the task has been canceled and cleaned up successfully

Arguments

• defender_task:[in] running task to stop and clean up

Prototype

void aws_iotdevice_defender_task_clean_up(struct aws_iotdevice_defender_task *defender_task);

aws_iotdevice_defender_task_create(task_out, config, connection, event_loop)

Creates and starts a new Device Defender reporting task

Arguments

• task_out:[out] output parameter to set to point to the defender task
• config:[in] defender task configuration to use to start the task
• connection:[in] mqtt connection to use to publish reports to
• event_loop:[in] IoT device thing name used to determine the MQTT topic to publish the report to and listen for accepted or rejected responses

Returns

AWS_OP_SUCCESS if the task has been created successfully and is scheduled to run

Prototype

int aws_iotdevice_defender_task_create( struct aws_iotdevice_defender_task **task_out, const struct aws_iotdevice_defender_task_config *config, struct aws_mqtt_client_connection *connection, struct aws_event_loop *event_loop);

aws_iotdevice_defender_task_create_ex(task_out, config, publish_fn, event_loop)

Creates and starts a new Device Defender reporting task with the ability to define a function to accept/handle each report when the task needs to publish.

Arguments

• task_out:[out] output parameter to set to point to the defender task
• config:[in] defender task configuration to use to start the task
• publish_fn:[in] callback to handle reports generated by the task. The userdata comes from the task config
• event_loop:[in] IoT device thing name used to determine the MQTT topic to publish the report to and listen for accepted or rejected responses

Returns

AWS_OP_SUCCESS if the task has been created successfully and is scheduled to run

Prototype

int aws_iotdevice_defender_task_create_ex( struct aws_iotdevice_defender_task **task_out, const struct aws_iotdevice_defender_task_config *config, aws_iotdevice_defender_publish_fn *publish_fn, struct aws_event_loop *event_loop);

aws_iotdevice_library_clean_up()

Shuts down the internal datastructures used by aws-c-iot

Prototype

void aws_iotdevice_library_clean_up(void);

aws_iotdevice_library_init(allocator)

Initializes internal datastructures used by aws-c-iot. Must be called before using any functionality in aws-c-iot.

Prototype

void aws_iotdevice_library_init(struct aws_allocator *allocator);

aws_secure_tunnel_acquire(secure_tunnel)

Acquires a reference to a secure tunnel

Arguments

• secure_tunnel: secure tunnel to acquire a reference to. May be NULL

Returns

what was passed in as the secure tunnel (a client or NULL)

Prototype

struct aws_secure_tunnel *aws_secure_tunnel_acquire(struct aws_secure_tunnel *secure_tunnel);

aws_secure_tunnel_connection_reset(secure_tunnel, message_options)

Documentation not found.

Prototype

int aws_secure_tunnel_connection_reset( struct aws_secure_tunnel *secure_tunnel, const struct aws_secure_tunnel_message_view *message_options);

aws_secure_tunnel_connection_start(secure_tunnel, message_options)

Queue a CONNECTION_START message in a secure tunnel

Arguments

• secure_tunnel: secure tunnel to queue a message for
• message_options: configuration options for the message operation

Returns

success/failure in the synchronous logic that kicks off the message operation

Prototype

int aws_secure_tunnel_connection_start( struct aws_secure_tunnel *secure_tunnel, const struct aws_secure_tunnel_message_view *message_options);

aws_secure_tunnel_deserialize_message_from_cursor(secure_tunnel, cursor, on_message_received)

Documentation not found.

Prototype

int aws_secure_tunnel_deserialize_message_from_cursor( struct aws_secure_tunnel *secure_tunnel, struct aws_byte_cursor *cursor, aws_secure_tunnel_on_message_received_fn *on_message_received);

aws_secure_tunnel_get_default_vtable()

Documentation not found.

Prototype

const struct aws_secure_tunnel_vtable *aws_secure_tunnel_get_default_vtable(void);

aws_secure_tunnel_message_type_to_c_string(message_type)

Get the const char description of a message type

Arguments

• message_type: message type used by a secure tunnel message

Returns

const char translation of the message type

Prototype

const char *aws_secure_tunnel_message_type_to_c_string(enum aws_secure_tunnel_message_type message_type);

aws_secure_tunnel_new(allocator, options)

Creates a new secure tunnel

Arguments

• options: secure tunnel configuration

Returns

a new secure tunnel or NULL

Prototype

struct aws_secure_tunnel *aws_secure_tunnel_new( struct aws_allocator *allocator, const struct aws_secure_tunnel_options *options);

aws_secure_tunnel_release(secure_tunnel)

Release a reference to a secure tunnel. When the secure tunnel ref count drops to zero, the secure tunnel will automatically trigger a stop and once the stop completes, the secure tunnel will delete itself.

Arguments

• secure_tunnel: secure tunnel to release a reference to. May be NULL

Returns

NULL

Prototype

struct aws_secure_tunnel *aws_secure_tunnel_release(struct aws_secure_tunnel *secure_tunnel);

aws_secure_tunnel_send_message(secure_tunnel, message_options)

Queues a message operation in a secure tunnel

Arguments

• secure_tunnel: secure tunnel to queue a message for
• message_options: configuration options for the message operation

Returns

success/failure in the synchronous logic that kicks off the message operation

Prototype

int aws_secure_tunnel_send_message( struct aws_secure_tunnel *secure_tunnel, const struct aws_secure_tunnel_message_view *message_options);

aws_secure_tunnel_set_vtable(secure_tunnel, vtable)

Documentation not found.

Prototype

void aws_secure_tunnel_set_vtable( struct aws_secure_tunnel *secure_tunnel, const struct aws_secure_tunnel_vtable *vtable);

aws_secure_tunnel_start(secure_tunnel)

Asynchronous notify to the secure tunnel that you want it to attempt to connect. The secure tunnel will attempt to stay connected.

Arguments

• secure_tunnel: secure tunnel to start

Returns

success/failure in the synchronous logic that kicks off the start process

Prototype

int aws_secure_tunnel_start(struct aws_secure_tunnel *secure_tunnel);

aws_secure_tunnel_stop(secure_tunnel)

Asynchronous notify to the secure tunnel that you want it to transition to the stopped state. When the secure tunnel reaches the stopped state, all session state is erased.

Arguments

• secure_tunnel: secure tunnel to stop

Returns

success/failure in the synchronous logic that kicks off the start process

Prototype

int aws_secure_tunnel_stop(struct aws_secure_tunnel *secure_tunnel);

aws_secure_tunnel_stream_reset(secure_tunnel, message_options)

Queue a STREAM_RESET message in a secure tunnel

Arguments

• secure_tunnel: secure tunnel to queue a message for
• message_options: configuration options for the message operation

Returns

success/failure in the synchronous logic that kicks off the message operation

Prototype

int aws_secure_tunnel_stream_reset( struct aws_secure_tunnel *secure_tunnel, const struct aws_secure_tunnel_message_view *message_options);

aws_secure_tunnel_stream_start(secure_tunnel, message_options)

Queue a STREAM_START message in a secure tunnel

Arguments

• secure_tunnel: secure tunnel to queue a message for
• message_options: configuration options for the message operation

Returns

success/failure in the synchronous logic that kicks off the message operation

Prototype

int aws_secure_tunnel_stream_start( struct aws_secure_tunnel *secure_tunnel, const struct aws_secure_tunnel_message_view *message_options);