AWSCRT

Environment variables:

• AWS_CRT_MEMORY_TRACING: Set to 0, 1, or 2 to enable memory tracing. Default is off. See aws_mem_trace_level.
• AWS_CRT_MEMORY_TRACING_FRAMES_PER_STACK: Set the number of frames per stack for memory tracing. Default is the AWS library's default.
• AWS_CRT_LOG_LEVEL: Set to 0 through 6 to enable logging. Default is off. See aws_log_level.
• AWS_CRT_LOG_PATH: Set to the log file path. Must be set if AWS_CRT_LOG_LEVEL is set.

Note: all the symbols in this package that begin with underscores are private and are not part of this package's published interface. Please don't use them.

mutable struct ClientBootstrap
    ptr::Ptr{aws_client_bootstrap}
end

Handles creation and setup of client socket connections.

Note on advanced use: the internal constructor on this struct has been left at its default so that you can bring your own native data if you need to. However, you are then responsible for the memory management of that data.

ClientBootstrap(el_group::EventLoopGroup, host_resolver::HostResolver)

Handles creation and setup of client socket connections.

Arguments:

• el_group (EventLoopGroup): EventLoopGroup to use.
• host_resolver (HostResolver): DNS host resolver to use.

mutable struct ClientTLSContext
    ptr::Ptr{aws_tls_ctx}
end

Client TLS context. A context is expensive, but can be used for the lifetime of the application by all outgoing connections that wish to use the same TLS configuration.

Note on advanced use: the internal constructor on this struct has been left at its default so that you can bring your own native data if you need to. However, you are then responsible for the memory management of that data.

ClientTLSContext(options::TLSContextOptions)

Client TLS context. A context is expensive, but can be used for the lifetime of the application by all outgoing connections that wish to use the same TLS configuration.

Arguments:

• options (TLSContextOptions): Configuration options.

EventLoopGroup(num_threads::Union{Int,Nothing} = nothing, cpu_group::Union{Int,Nothing} = nothing)

A collection of event-loops. An event-loop is a thread for doing async work, such as I/O.

Arguments:

• num_threads (Union{Int,Nothing}) (default=nothing): Maximum number of event-loops to create. If unspecified, one is created for each processor on the machine.
• cpu_group (Union{Int,Nothing}) (default=nothing): Optional processor group to which all threads will be pinned. Useful for systems with non-uniform memory access (NUMA) nodes. If specified, the number of threads will be capped at the number of processors in the group.

mutable struct EventLoopGroup
    ptr::Ptr{aws_event_loop_group}
end

A collection of event-loops. An event-loop is a thread for doing async work, such as I/O.

Note on advanced use: the internal constructor on this struct has been left at its default so that you can bring your own native data if you need to. However, you are then responsible for the memory management of that data.

HostResolver(el_group::EventLoopGroup, max_hosts::Int = 16)

Default DNS host resolver.

Arguments:

• el_group (EventLoopGroup): EventLoopGroup to use.
• max_hosts (Int) (default=16): Max host names to cache.

mutable struct HostResolver
    ptr::Ptr{aws_host_resolver}
end

Default DNS host resolver.

Note on advanced use: the internal constructor on this struct has been left at its default so that you can bring your own native data if you need to. However, you are then responsible for the memory management of that data.

MQTTClient(
    tls_ctx::Union{ClientTLSContext,Nothing},
    bootstrap::ClientBootstrap = get_or_create_default_client_bootstrap(),
)

MQTT client.

Arguments:

• tls_ctx (Union{ClientTLSContext,Nothing}): TLS context for secure socket connections. If nothing, an unencrypted connection is used.
• bootstrap (ClientBootstrap) (default=get_or_create_default_client_bootstrap()): Client bootstrap to use when initiating new socket connections. Uses the singleton by default.

MQTTConnection(client::MQTTClient)

MQTT client connection.

Arguments:

• client ([MQTTClient](@ref)): MQTT client to spawn connection from.

on_connection_interrupted(
    connection::MQTTConnection,
    error_code::Int,
)

A callback invoked whenever the MQTT connection is lost. The MQTT client will automatically attempt to reconnect.

Arguments:

• connection (MQTTConnection): The connection.
• error_code (Int): Error which caused connection loss.

on_connection_resumed(
    connection::MQTTConnection,
    return_code::aws_mqtt_connect_return_code,
    session_present::Bool,
)

A callback invoked whenever the MQTT connection is automatically resumed.

Arguments:

• connection (MQTTConnection): The connection.
• return_code (aws_mqtt_connect_return_code): Connect return code received from the server.
• session_present (Bool): true if resuming existing session. false if new session. Note that the server has forgotten all previous subscriptions if this is false. Subscriptions can be re-established via resubscribe_existing_topics.

on_message(
    topic::String,
    payload::String,
    dup::Bool,
    qos::aws_mqtt_qos,
    retain::Bool,
)

A callback invoked when a message is received.

Arguments:

• topic (String): Topic receiving message.
• payload (String): Payload of message.
• dup (Bool): DUP flag. If True, this might be re-delivery of an earlier attempt to send the message.
• qos (aws_mqtt_qos): Maximum requested QoS that the server may use when sending messages to the client. The server may grant a lower QoS in the SUBACK (see returned task).
• retain (Bool): Retain flag. If true, the message was sent as a result of a new subscription being made by the client.

Returns nothing.

on_shadow_message(
    shadow_client::ShadowClient,
    topic::String,
    payload::String,
    dup::Bool,
    qos::aws_mqtt_qos,
    retain::Bool,
)

A callback invoked when a shadow document message is received.

Arguments:

• shadow_client (ShadowClient): Shadow client that received the message.
• topic (String): Topic receiving message.
• payload (String): Payload of message.
• dup (Bool): DUP flag. If true, this might be re-delivery of an earlier attempt to send the message.
• qos (aws_mqtt_qos): Maximum requested QoS that the server may use when sending messages to the client. The server may grant a lower QoS in the SUBACK (see returned task).
• retain (Bool): Retain flag. If true, the message was sent as a result of a new subscription being made by the client.

Returns nothing.

ShadowClient(
    connection::MQTTConnection,
)

Device Shadow service client. AWS Documentation.

Arguments:

• connection (MQTTConnection): MQTT connection to publish and subscribe on.
• thing_name (String): Name of the Thing in AWS IoT under which the shadow document will exist.
• shadow_name (Union{String,Nothing}): Shadow name for a named shadow document or nothing for an unnamed shadow document.

shadow_document_post_update_callback(shadow_document::AbstractDict)

A callback invoked after the shadow document is updated. The parent ShadowFramework will not be locked when this callback is invoked. This is a good place to persist the shadow document to disk.

Arguments:

• shadow_document (AbstractDict): The updated shadow document.

shadow_document_pre_update_callback(state::Dict{String,Any})

A callback invoked before the shadow document is updated. The parent ShadowFramework will not be locked when this callback is invoked.

Arguments:

• state (Dict{String,Any}): The incoming shadow state. This could be reported state or delta state.

shadow_document_property_pre_update_function(shadow_document::AbstractDict, key::String, value)::Bool

A function invoked when updating a property in the shadow document. This allows you to replace the update behavior in this package if you want to implement custom update behavior for a given property. The parent ShadowFramework will be locked when this function is invoked. The lock is reentrant.

!!! warning "Warning"
    This function may only update the given `key`. This function cannot modify other properties in the `shadow_document`.

Arguments:

• shadow_document (AbstractDict): The shadow document being updated.
• key (String): The key in the shadow_document for the value being updated.
• value (Any): The new value for the key.

Returns a Bool indicating whether an update was done.

shadow_document_property_update_callback(value)

A callback invoked immediately after a property in the shadow document is updated. The parent ShadowFramework will be locked when this callback is invoked. The lock is reentrant.

Arguments:

• value (Any): The new value of the property in the shadow document.

ShadowFramework(
    connection::MQTTConnection,
    thing_name::String,
    shadow_name::Union{String,Nothing},
    shadow_document::T;
    shadow_document_property_callbacks::Dict{String,ShadowDocumentPropertyUpdateCallback} = Dict{
        String,
        ShadowDocumentPropertyUpdateCallback,
    }(),
    shadow_document_pre_update_callback::ShadowDocumentPreUpdateCallback = (v) -> nothing,
    shadow_document_post_update_callback::ShadowDocumentPostUpdateCallback = (v) -> nothing,
    id = 1,
) where {T}

Creates a ShadowFramework.

Arguments:

• connection (MQTTConnection): The connection.
• thing_name (String): Name of the Thing in AWS IoT under which the shadow document will exist.
• shadow_name (Union{String,Nothing}): Shadow name for a named shadow document or nothing for an unnamed shadow document.
• shadow_document (AbstractDict): The local shadow document. This must include all keys in the shadow documents published by the broker. This must also include a version (Int) key which will store the shadow document version. It is recommended that you persist this to disk. You can write the latest state to disk inside shadow_document_post_update_callback. You should also then load it from disk and pass it as this parameter during the start of your application.
• shadow_document_property_callbacks (Dict{String,ShadowDocumentPropertyUpdateCallback}): An optional set of callbacks. A given callback will be fired for each update to the shadow document property matching the given key. Note that the callback is fired only when shadow properties are changed. A shadow property change occurs when the value of the shadow property is changed to a new value which is not equal to the prior value. This is implemented using !isequal(). Please ensure a satisfactory definition (satisfactory to your application's needs) of isequal for all types used in the shadow document. You will only need to worry about this if you are using custom JSON deserialization.
• shadow_document_pre_update_callback (ShadowDocumentPreUpdateCallback): An optional callback which will be fired immediately before updating any shadow document properties. This is always fired, even if no shadow properties will be changed.
• shadow_document_post_update_callback (ShadowDocumentPostUpdateCallback): An optional callback which will be fired immediately after updating any shadow document properties. This is fired only if shadow properties were changed.
• shadow_document_property_pre_update_funcs (Dict{String,ShadowDocumentPropertyPreUpdateFunction}): An optional set of functions which customize the update behavior of certain shadow document properties. See ShadowDocumentPropertyPreUpdateFunction for more information.
• id (Int): A unique ID which disambiguates log messages from multiple shadow frameworks.

See also ShadowDocumentPropertyUpdateCallback, ShadowDocumentPreUpdateCallback, ShadowDocumentPostUpdateCallback, MQTTConnection.

!!! note "Limitations"
    Removing properties by setting their desired value to `null` is not currently supported. AWS IoT will remove
    that `null` property from the desired state, but the property will remain in the reported state.

mutable struct TLSConnectionOptions
    ptr::Ref{aws_tls_connection_options}
end

Connection-specific TLS options. Note that while a TLS context is an expensive object, this object is cheap.

Note on advanced use: the internal constructor on this struct has been left at its default so that you can bring your own native data if you need to. However, you are then responsible for the memory management of that data.

TLSConnectionOptions(
    client_tls_context::ClientTLSContext,
    alpn_list::Union{Vector{String},Nothing} = nothing,
    server_name::Union{String,Nothing} = nothing,
)

Connection-specific TLS options. Note that while a TLS context is an expensive object, this object is cheap.

Arguments:

• client_tls_context (ClientTLSContext): TLS context. A context can be shared by many connections.
• alpn_list (Union{Vector{String},Nothing}) (default=nothing): Connection-specific Application Layer Protocol Negotiation (ALPN) list. This overrides any ALPN list on the TLS context in the client this connection was made with. ALPN is not supported on all systems, see aws_tls_is_alpn_available.
• server_name (Union{String,Nothing}) (default=nothing): Name for TLS Server Name Indication (SNI). Also used for x.509 validation.

TLSContextOptions(;
    min_tls_version::aws_tls_versions = AWS_IO_TLS_VER_SYS_DEFAULTS,
    ca_dirpath::Union{String,Nothing} = nothing,
    ca_filepath::Union{String,Nothing} = nothing,
    ca_data::Union{String,Nothing} = nothing,
    alpn_list::Union{Vector{String},Nothing} = nothing,
    cert_data::Union{String,Nothing} = nothing,
    pk_data::Union{String,Nothing} = nothing,
    verify_peer::Bool = true,
)

Options to create a TLS context.

Arguments:

• min_tls_version (aws_tls_versions) (default=AWS_IO_TLS_VER_SYS_DEFAULTS): Minimum TLS version to use. System defaults are used by default.

• ca_dirpath (Union{String,Nothing}) (default=nothing): Path to directory containing trusted certificates, which will overrides the default trust store. Only supported on Unix.

• ca_filepath (Union{String,Nothing}) (default=nothing): Path to file containing PEM armored chain of trusted CA certificates.

• ca_data (Union{String,Nothing}) (default=nothing): PEM armored chain of trusted CA certificates.

• alpn_list (Union{Vector{String},Nothing}) (default=nothing): If set, names to use in Application Layer Protocol Negotiation (ALPN). ALPN is not supported on all systems, see aws_tls_is_alpn_available. This can be customized per connection; see TLSConnectionOptions.

• cert_data (Union{String,Nothing}) (default=nothing): Certificate contents. Treated as PKCS #7 PEM armored.

• pk_data (Union{String,Nothing}) (default=nothing): Private key contents. Treated as PKCS #7 PEM armored.

• verify_peer (Bool) (default=true): Whether to validate the peer's x.509 certificate.

Will(
    topic::String,
    qos::aws_mqtt_qos,
    payload::String,
    retain::Bool,
)

A Will message is published by the server if a client is lost unexpectedly.

The Will message is stored on the server when a client connects. It is published if the client connection is lost without the server receiving a DISCONNECT packet.

[MQTT-3.1.2-8]

Arguments:

• topic (String): Topic to publish Will message on.
• qos (aws_mqtt_qos): QoS used when publishing the Will message.
• payload (String): Content of Will message.
• retain (Bool): Whether the Will message is to be retained when it is published.

_do_local_shadow_update!(sf::ShadowFramework, state::Dict{String,<:Any})

1. Fires the pre-update callback
2. Updates each shadow property from state and fires its callback if an update occured
3. Fires the post-update callback
4. Returns true if any updated occured.

_sync_version!(doc::AbstractDict, payload_str::String)

Updates the local shadow's version number using the version in the payload.

_update_local_shadow_from_delta!(sf::ShadowFramework, payload_str::String)

Performs a local shadow update using the delta state from an /update/delta document. Returns true if the local shadow was updated.

_update_local_shadow_from_get!(sf::ShadowFramework, payload_str::String)

Performs a local shadow update using the delta state from a /get/accepted document. Returns true if the local shadow was updated.

_update_shadow_property!(sf::ShadowFramework, doc::AbstractDict, key::String, value)

Updates the shadow property if the new value is not equal to the current value at the key. If the value is an AbstractDict, it is merged into the doc instead of overwriting the key. Returns true if an update occured.

connect(
    connection::MQTTConnection,
    server_name::String,
    port::Integer,
    client_id::String;
    clean_session::Bool = true,
    on_connection_interrupted::Union{OnConnectionInterrupted,Nothing} = nothing,
    on_connection_resumed::Union{OnConnectionResumed,Nothing} = nothing,
    reconnect_min_timeout_secs::Integer = 5,
    reconnect_max_timeout_secs::Integer = 60,
    keep_alive_secs::Integer = 1200,
    ping_timeout_ms::Integer = 3000,
    protocol_operation_timeout_ms::Integer = 0,
    will::Union{Will,Nothing} = nothing,
    username::Union{String,Nothing} = nothing,
    password::Union{String,Nothing} = nothing,
    socket_options = Ref(aws_socket_options(AWS_SOCKET_STREAM, AWS_SOCKET_IPV6, 5000, 0, 0, 0, false)),
    alpn_list::Union{Vector{String},Nothing} = nothing,
    use_websockets::Bool = false,
    websocket_handshake_transform = nothing, # TODO union type
    proxy_options = nothing, # TODO union type
)

Open the actual connection to the server (async).

Arguments:

• connection (MQTTConnection): Connection to use.
• server_name (String): Server name to connect to.
• port (Integer): Server port to connect to.
• client_id (String): ID to place in CONNECT packet. Must be unique across all devices/clients. If an ID is already in use, the other client will be disconnected.
• clean_session (Bool) (default=true): Whether or not to start a clean session with each reconnect. If true, the server will forget all subscriptions with each reconnect. Set false to request that the server resume an existing session or start a new session that may be resumed after a connection loss. The session_present bool in the connection callback informs whether an existing session was successfully resumed. If an existing session is resumed, the server remembers previous subscriptions and sends mesages (with QoS level 1 or higher) that were published while the client was offline.
• on_connection_interrupted (Union{OnConnectionInterrupted,Nothing}) (default=nothing): Optional callback invoked whenever the MQTT connection is lost. The MQTT client will automatically attempt to reconnect. See OnConnectionInterrupted.
• on_connection_resumed (Union{OnConnectionResumed,Nothing}) (default=nothing): Optional callback invoked whenever the MQTT connection is automatically resumed. See OnConnectionResumed.
• reconnect_min_timeout_secs (Integer) (default=5): Minimum time to wait between reconnect attempts. Must be <= reconnect_max_timeout_secs. Wait starts at min and doubles with each attempt until max is reached.
• reconnect_max_timeout_secs (Integer) (default=60): Maximum time to wait between reconnect attempts. Must be >= reconnect_min_timeout_secs. Wait starts at min and doubles with each attempt until max is reached.
• keep_alive_secs (Integer) (default=1200): The keep alive value (seconds) to send in CONNECT packet. A PING will automatically be sent at this interval. The server will assume the connection is lost if no PING is received after 1.5X this value. This duration must be longer than ping_timeout_ms.
• ping_timeout_ms (Integer) (default=3000): Milliseconds to wait for ping response before client assumes the connection is invalid and attempts to reconnect. This duration must be shorter than keep_alive_secs.
• protocol_operation_timeout_ms (Integer) (default=0): Milliseconds to wait for a response to an operation that requires a response by the server. Set to zero to disable timeout. Otherwise, the operation will fail if no response is received within this amount of time after the packet is written to the socket. This works with PUBLISH (if QoS level > 0) and UNSUBSCRIBE.
• will (Union{Will,Nothing}) (default=nothing): Will to send with CONNECT packet. The will is published by the server when its connection to the client is unexpectedly lost.
• username (Union{String,Nothing}) (default=nothing): Username to connect with.
• password (Union{String,Nothing}) (default=nothing): Password to connect with.
• socket_options (Ref(aws_socket_options}) (default=Ref(aws_socket_options(AWS_SOCKET_STREAM, AWS_SOCKET_IPV6, 5000, 0, 0, 0, false))): Optional socket options.
• alpn_list (Union{Vector{String},Nothing}) (default=nothing): Connection-specific Application Layer Protocol Negotiation (ALPN) list. This overrides any ALPN list on the TLS context in the client this connection was made with. ALPN is not supported on all systems, see aws_tls_is_alpn_available.
• use_websockets (Bool) (default=false): # TODO not implemented
• websocket_handshake_transform (nothing) (default=nothing): # TODO not implemented
• proxy_options (nothing) (default=nothing): # TODO not implemented

Returns a task which completes when the connection succeeds or fails.

If the connection succeeds, the task will contain a dict containing the following keys:

• :session_present: true if resuming an existing session, false if new session

If the connection fails, the task will throw an exception.

create_client_with_mtls(cert_data, pk_data; kwargs...)

Create options configured for use with mutual TLS in client mode. Both buffers are treated as PKCS #7 PEM armored.

Arguments:

• cert_data (String): Certificate contents
• pk_data (String): Private key contents.
• ca_dirpath (Union{String,Nothing}) (default=nothing): Path to directory containing trusted certificates, which will overrides the default trust store. Only supported on Unix.
• ca_filepath (Union{String,Nothing}) (default=nothing): Path to file containing PEM armored chain of trusted CA certificates.
• ca_data (Union{String,Nothing}) (default=nothing): PEM armored chain of trusted CA certificates.
• alpn_list (Union{Vector{String},Nothing}) (default=nothing): If set, names to use in Application Layer Protocol Negotiation (ALPN). ALPN is not supported on all systems, see aws_tls_is_alpn_available. This can be customized per connection; see TLSConnectionOptions.

create_client_with_mtls_from_path(cert_filepath, pk_filepath; kwargs...)

Create options configured for use with mutual TLS in client mode. Both files are treated as PKCS #7 PEM armored. They are loaded from disk and stored in buffers internally.

Arguments:

• cert_filepath (String): Path to certificate file.
• pk_filepath (String): Path to private key file.
• ca_dirpath (Union{String,Nothing}) (default=nothing): Path to directory containing trusted certificates, which will overrides the default trust store. Only supported on Unix.
• ca_filepath (Union{String,Nothing}) (default=nothing): Path to file containing PEM armored chain of trusted CA certificates.
• ca_data (Union{String,Nothing}) (default=nothing): PEM armored chain of trusted CA certificates.
• alpn_list (Union{Vector{String},Nothing}) (default=nothing): If set, names to use in Application Layer Protocol Negotiation (ALPN). ALPN is not supported on all systems, see aws_tls_is_alpn_available. This can be customized per connection; see TLSConnectionOptions.

create_server(cert_data, pk_data; kwargs...)

Create options configured for use in server mode. Both buffers are treated as PKCS #7 PEM armored.

Arguments:

• cert_data (String): Certificate contents
• pk_data (String): Private key contents.
• ca_dirpath (Union{String,Nothing}) (default=nothing): Path to directory containing trusted certificates, which will overrides the default trust store. Only supported on Unix.
• ca_filepath (Union{String,Nothing}) (default=nothing): Path to file containing PEM armored chain of trusted CA certificates.
• ca_data (Union{String,Nothing}) (default=nothing): PEM armored chain of trusted CA certificates.
• alpn_list (Union{Vector{String},Nothing}) (default=nothing): If set, names to use in Application Layer Protocol Negotiation (ALPN). ALPN is not supported on all systems, see aws_tls_is_alpn_available. This can be customized per connection; see TLSConnectionOptions.

create_server_from_path(cert_filepath, pk_filepath; kwargs...)

Create options configured for use in server mode. Both files are treated as PKCS #7 PEM armored. They are loaded from disk and stored in buffers internally.

Arguments:

• cert_filepath (String): Path to certificate file.
• pk_filepath (String): Path to private key file.
• ca_dirpath (Union{String,Nothing}) (default=nothing): Path to directory containing trusted certificates, which will overrides the default trust store. Only supported on Unix.
• ca_filepath (Union{String,Nothing}) (default=nothing): Path to file containing PEM armored chain of trusted CA certificates.
• ca_data (Union{String,Nothing}) (default=nothing): PEM armored chain of trusted CA certificates.
• alpn_list (Union{Vector{String},Nothing}) (default=nothing): If set, names to use in Application Layer Protocol Negotiation (ALPN). ALPN is not supported on all systems, see aws_tls_is_alpn_available. This can be customized per connection; see TLSConnectionOptions.

disconnect(connection::MQTTConnection)

Close the connection to the server (async). Returns a task which completes when the connection is closed. If there is no MQTT connection or network connection, the task completes. The task will contain nothing.

new_jl_allocator()

Returns an aws_allocator which integrates with Julia's GC to track memory allocated by native code.

on_message(connection::MQTTConnection, callback::Union{OnMessage,Nothing})

Set callback to be invoked when ANY message is received.

Arguments:

• connection (MQTTConnection): Connection to use.
• callback (Union{OnMessage,Nothing}): Optional callback invoked when message received. See OnMessage for the required signature. Set to nothing to clear this callback.

Returns nothing.

publish(connection::MQTTConnection, topic::String, payload::String, qos::aws_mqtt_qos, retain::Bool = false)

Publish message (async). If the device is offline, the PUBLISH packet will be sent once the connection resumes.

Arguments:

• connection (MQTTConnection): Connection to use.
• topic (String): Topic name.
• payload (String): Contents of message.
• qos (aws_mqtt_qos): Maximum requested QoS that the server may use when sending messages to the client. The server may grant a lower QoS in the SUBACK (see returned task).
• retain (Bool): If true, the server will store the message and its QoS so that it can be delivered to future subscribers whose subscriptions match its topic name.

Returns a task and the ID of the PUBLISH packet. The QoS determines when the task completes:

• For QoS 0, completes as soon as the packet is sent.
• For QoS 1, completes when PUBACK is received.
• For QoS 2, completes when PUBCOMP is received.

If successful, the task will contain a dict with the following members:

• :packet_id (Int): ID of the PUBLISH packet that is complete.

If unsuccessful, the task will throw an exception.

If there is no MQTT connection or network connection, the task may wait forever.

Throws if the PUBLISH packet could not be sent.

publish(client::ShadowClient, topic::String, payload::String, qos::aws_mqtt_qos)

Publishes the payload to the topic under the configured shadow topic.

Arguments:

• client (ShadowClient): Shadow client to use.
• topic (String): Topic name, not including the shadow topic prefix. E.g. /get.
• payload (String): Message contents.
• qos (aws_mqtt_qos): Maximum requested QoS that the server may use when sending messages to the client. The server may grant a lower QoS in the SUBACK (see returned task).

Returns a task and the ID of the PUBLISH packet. The QoS determines when the task completes:

• For QoS 0, completes as soon as the packet is sent.
• For QoS 1, completes when PUBACK is received.
• For QoS 2, completes when PUBCOMP is received.

If successful, the task will contain a dict with the following members:

• :packet_id (Int): ID of the PUBLISH packet that is complete.

If unsuccessful, the task will throw an exception.

If there is no MQTT connection or network connection, the task may wait forever.

Throws if the PUBLISH packet could not be sent.

publish_current_state(sf::ShadowFramework; include_version::Bool = true)

Publishes the current state of the shadow document.

Arguments:

• include_version (Bool): Includes the version of the shadow document if this is true. You may want to exclude the version if you don't know what the broker's version is.

Returns a task and the ID of the PUBLISH packet. The QoS determines when the task completes:

• For QoS 0, completes as soon as the packet is sent.
• For QoS 1, completes when PUBACK is received.
• For QoS 2, completes when PUBCOMP is received.

If successful, the task will contain a dict with the following members:

• :packet_id (Int): ID of the PUBLISH packet that is complete.

If unsuccessful, the task will throw an exception.

If there is no MQTT connection or network connection, the task may wait forever.

Throws if the PUBLISH packet could not be sent.

resubscribe_existing_topics(connection::MQTTConnection)

Subscribe again to all current topics. This is to help when resuming a connection with a clean session.

Returns a task and the ID of the SUBSCRIBE packet. The task completes when a SUBACK is received from the server.

If successful, the task will contain a dict with the following members:

• :packet_id (Int): ID of the SUBSCRIBE packet being acknowledged.
• :topics (Vector{Tuple{Union{String,Nothing},aws_mqtt_qos}}): Topic filter of the SUBSCRIBE packet being acknowledged and its QoS level. The topic will be nothing if the topic failed to resubscribe. The vector will be empty if there were no topics to resubscribe.

If unsuccessful, the task contains an exception.

Throws if the SUBSCRIBE packet could not be sent.

shadow_client(sf::ShadowFramework)

Returns the ShadowClient for sf.

subscribe(connection::MQTTConnection, topic::String, qos::aws_mqtt_qos, callback::OnMessage)

Subsribe to a topic filter (async). The client sends a SUBSCRIBE packet and the server responds with a SUBACK. This function may be called while the device is offline, though the async operation cannot complete successfully until the connection resumes. Once subscribed, callback is invoked each time a message matching the topic is received. It is possible for such messages to arrive before the SUBACK is received.

Arguments:

• connection (MQTTConnection): Connection to use.
• topic (String): Subscribe to this topic filter, which may include wildcards.
• qos (aws_mqtt_qos): Maximum requested QoS that the server may use when sending messages to the client. The server may grant a lower QoS in the SUBACK (see returned task).
• callback (OnMessage): Callback invoked when a message is received. See OnMessage for the required signature.

Returns a task and the ID of the SUBSCRIBE packet. The task completes when a SUBACK is received from the server.

If successful, the task will contain a dict with the following members:

• :packet_id (Int): ID of the SUBSCRIBE packet being acknowledged.
• :topic (String): Topic filter of the SUBSCRIBE packet being acknowledged.
• :qos (aws_mqtt_qos): Maximum QoS that was granted by the server. This may be lower than the requested QoS.

If unsuccessful, the task contains an exception.

If there is no MQTT connection or network connection, the task may wait forever.

Throws if the SUBSCRIBE packet could not be sent.

subscribe(client::ShadowClient, qos::aws_mqtt_qos, callback::OnShadowMessage)

Subscribes to all topics under the given shadow document using a wildcard, including but not limited to:

• /get/accepted
• /get/rejected
• /update/delta
• /update/accepted
• /update/documents
• /update/rejected
• /delete/accepted
• /delete/rejected

Arguments:

• client (ShadowClient): Shadow client to use.
• qos (aws_mqtt_qos): Maximum requested QoS that the server may use when sending messages to the client. The server may grant a lower QoS in the SUBACK (see returned task).
• callback (OnShadowMessage): Callback invoked when message received. See OnShadowMessage for the required signature.

Returns a task which completes when the tasks from each subscribe call complete. Also returns a collection containing the packet ID from each subscribe call.

subscribe(client::ShadowClient, topic::String, qos::aws_mqtt_qos, callback::OnMessage)

Subscribes to the given topic (must contain a leading forward slash (/)) under the given shadow document.

Arguments:

• client (ShadowClient): Shadow client to use.
• topic (String): Subscribe to this topic filter, which may include wildcards, under the given shadow document.
• qos (aws_mqtt_qos): Maximum requested QoS that the server may use when sending messages to the client. The server may grant a lower QoS in the SUBACK (see returned task).
• callback (OnMessage): Callback invoked when a message is received. See OnMessage for the required signature.

Returns a task and the ID of the SUBSCRIBE packet. The task completes when a SUBACK is received from the server.

If successful, the task will contain a dict with the following members:

• :packet_id (Int): ID of the SUBSCRIBE packet being acknowledged.
• :topic (String): Topic filter of the SUBSCRIBE packet being acknowledged.
• :qos (aws_mqtt_qos): Maximum QoS that was granted by the server. This may be lower than the requested QoS.

If unsuccessful, the task contains an exception.

If there is no MQTT connection or network connection, the task may wait forever.

Throws if the SUBSCRIBE packet could not be sent.

subscribe(sf::ShadowFramework)

Subscribes to the shadow document's topics and begins processing updates. The sf is always locked before reading/writing from/to the shadow document. If the remote shadow document does not exist, the local shadow document will be used to create it.

Publishes an initial message to the /get topic to synchronize the shadow document with the broker's state. You can call wait_until_synced(sf) if you need to wait until this synchronization is done.

Returns a task and the ID of the PUBLISH packet. The QoS determines when the task completes:

• For QoS 0, completes as soon as the packet is sent.
• For QoS 1, completes when PUBACK is received.
• For QoS 2, completes when PUBCOMP is received.

If successful, the task will contain a dict with the following members:

• :packet_id (Int): ID of the PUBLISH packet that is complete.

If unsuccessful, the task will throw an exception.

If there is no MQTT connection or network connection, the task may wait forever.

Throws if the PUBLISH packet could not be sent.

unsubscribe(connection::MQTTConnection, topic::String)

Unsubscribe from a topic filter (async). The client sends an UNSUBSCRIBE packet, and the server responds with an UNSUBACK.

Arguments:

• connection (MQTTConnection): Connection to use.
• topic (String): Unsubscribe from this topic filter.

Returns a task and the ID of the UNSUBSCRIBE packet. The task completes when an UNSUBACK is received from the server.

If successful, the task will contain a dict with the following members:

• :packet_id (Int): ID of the UNSUBSCRIBE packet being acknowledged.

If unsuccessful, the task will throw an exception.

If there is no MQTT connection or network connection, the task may wait forever.

Throws if the UNSUBSCRIBE packet could not be sent.

unsubscribe(client::ShadowClient)

Unsubscribes from all shadow document topics.

Arguments:

• client (ShadowClient): Shadow client to use.

Returns a task which completes when the tasks from each unsubscribe call complete. Also returns a collection containing the packet ID from each unsubscribe call.

unsubscribe(sf::ShadowFramework)

Unsubscribes from the shadow document's topics and stops processing updates. After calling this, wait_until_synced(sf) will again block until the first publish in response to calling subscribe(sf).

Returns a task which completes when the tasks from each unsubscribe call complete. Also returns a collection containing the packet ID from each unsubscribe call.

wait_until_synced(f::Function, sf::ShadowFramework)

Blocks until the next time the shadow document is synchronized with the broker. If you want to wait for a synchronization after a publication that you make, then you must make that publication inside the lambda f.

wait_until_synced(sf::ShadowFramework)

Blocks until the next time the shadow document is synchronized with the broker.

lock(f::Function, sf::ShadowFramework)

Locks the sf to ensure atomic access to the shadow document.

lock(sf::ShadowFramework)

Locks the sf to ensure atomic access to the shadow document.

unlock(sf::ShadowFramework)

Unlocks the sf.