AWSCRT
Documentation for AWSCRT.
AWSCRT.AWSCRT
AWSCRT.ClientBootstrap
AWSCRT.ClientBootstrap
AWSCRT.ClientTLSContext
AWSCRT.ClientTLSContext
AWSCRT.EventLoopGroup
AWSCRT.EventLoopGroup
AWSCRT.HostResolver
AWSCRT.HostResolver
AWSCRT.MQTTClient
AWSCRT.MQTTConnection
AWSCRT.OnConnectionInterrupted
AWSCRT.OnConnectionResumed
AWSCRT.OnMessage
AWSCRT.OnShadowMessage
AWSCRT.ShadowClient
AWSCRT.ShadowDocumentPostUpdateCallback
AWSCRT.ShadowDocumentPreUpdateCallback
AWSCRT.ShadowDocumentPropertyUpdateCallback
AWSCRT.ShadowFramework
AWSCRT.TLSConnectionOptions
AWSCRT.TLSConnectionOptions
AWSCRT.TLSContextOptions
AWSCRT.Will
AWSCRT._do_local_shadow_update!
AWSCRT._sync_version!
AWSCRT._update_local_shadow_from_delta!
AWSCRT._update_local_shadow_from_get!
AWSCRT._update_shadow_property!
AWSCRT._update_shadow_property!
AWSCRT.connect
AWSCRT.create_client_with_mtls
AWSCRT.create_client_with_mtls_from_path
AWSCRT.create_server
AWSCRT.create_server_from_path
AWSCRT.disconnect
AWSCRT.on_message
AWSCRT.publish
AWSCRT.publish
AWSCRT.publish_current_state
AWSCRT.resubscribe_existing_topics
AWSCRT.shadow_client
AWSCRT.subscribe
AWSCRT.subscribe
AWSCRT.subscribe
AWSCRT.subscribe
AWSCRT.unsubscribe
AWSCRT.unsubscribe
AWSCRT.unsubscribe
AWSCRT.wait_until_synced
Base.lock
Base.lock
Base.unlock
AWSCRT.AWSCRT
— ModuleEnvironment variables:
AWS_CRT_MEMORY_TRACING
: Set to0
,1
, or2
to enable memory tracing. Default is off. Seeaws_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 to0
through6
to enable logging. Default is off. Seeaws_log_level
.AWS_CRT_LOG_PATH
: Set to the log file path. Must be set ifAWS_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.
AWSCRT.ClientBootstrap
— Typemutable 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.
AWSCRT.ClientBootstrap
— MethodClientBootstrap(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.
AWSCRT.ClientTLSContext
— Typemutable 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.
AWSCRT.ClientTLSContext
— MethodClientTLSContext(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.
AWSCRT.EventLoopGroup
— TypeEventLoopGroup(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.
AWSCRT.EventLoopGroup
— Typemutable 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.
AWSCRT.HostResolver
— TypeHostResolver(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.
AWSCRT.HostResolver
— Typemutable 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.
AWSCRT.MQTTClient
— TypeMQTTClient(
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. Ifnothing
, 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.
AWSCRT.MQTTConnection
— TypeMQTTConnection(client::MQTTClient)
MQTT client connection.
Arguments:
client ([MQTTClient](@ref))
: MQTT client to spawn connection from.
AWSCRT.OnConnectionInterrupted
— Typeon_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.
All callbacks are run concurrently. Your callback implementations must be thread-safe. There is no concurrency limit.
AWSCRT.OnConnectionResumed
— Typeon_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 isfalse
. Subscriptions can be re-established viaresubscribe_existing_topics
.
All callbacks are run concurrently. Your callback implementations must be thread-safe. There is no concurrency limit.
AWSCRT.OnMessage
— Typeon_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. Iftrue
, the message was sent as a result of a new subscription being made by the client.
Returns nothing
.
All callbacks are run concurrently. Your callback implementations must be thread-safe. There is no concurrency limit.
AWSCRT.OnShadowMessage
— Typeon_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. Iftrue
, 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. Iftrue
, the message was sent as a result of a new subscription being made by the client.
Returns nothing
.
AWSCRT.ShadowClient
— TypeShadowClient(
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 ornothing
for an unnamed shadow document.
AWSCRT.ShadowDocumentPostUpdateCallback
— Typeshadow_document_post_update_callback(shadow_document::T)
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 (T)
: The updated shadow document.
AWSCRT.ShadowDocumentPreUpdateCallback
— Typeshadow_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.
AWSCRT.ShadowDocumentPropertyUpdateCallback
— Typeshadow_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 value of the shadow property that was just set in the shadow document.
AWSCRT.ShadowFramework
— MethodShadowFramework(
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 ornothing
for an unnamed shadow document.shadow_document (T)
: The local shadow document. This can be anAbstractDict
or a mutable struct. This must include keys/properties for all keys in the shadow documents published by the broker. If this type is not an AbstractDict and is missing a property of the desired shadow document state, an error will be logged and there will be a permanent difference between the reported and desired state. This must also include aversion (Int)
key/property which will store the shadow document version. It is recommended that you persist this to disk. You can write the latest state to disk insideshadow_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 (satifactory to your application's needs) ofisequal
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.id (Int)
: A unique ID which disambiguates log messages from multiple shadow frameworks.
See also ShadowDocumentPropertyUpdateCallback
, ShadowDocumentPreUpdateCallback
, ShadowDocumentPostUpdateCallback
, MQTTConnection
.
AWSCRT.TLSConnectionOptions
— TypeTLSConnectionOptions(
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, seeaws_tls_is_alpn_available
.server_name (Union{String,Nothing}) (default=nothing)
: Name for TLS Server Name Indication (SNI). Also used for x.509 validation.
AWSCRT.TLSConnectionOptions
— Typemutable 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.
AWSCRT.TLSContextOptions
— TypeTLSContextOptions(;
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, seeaws_tls_is_alpn_available
. This can be customized per connection; seeTLSConnectionOptions
.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.
AWSCRT.Will
— TypeWill(
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.
AWSCRT._do_local_shadow_update!
— Method_do_local_shadow_update!(sf::ShadowFramework{T}, state::Dict{String,<:Any}) where {T}
- Fires the pre-update callback
- Updates each shadow property from
state
and fires its callback if an update occured - Fires the post-update callback
- Returns
true
if any updated occured.
AWSCRT._sync_version!
— Method_sync_version!(doc::T, payload_str::String) where {T}
Updates the local shadow's version number using the version in the payload
.
AWSCRT._update_local_shadow_from_delta!
— Method_update_local_shadow_from_delta!(sf::ShadowFramework{T}, payload_str::String) where {T}
Performs a local shadow update using the delta state from an /update/delta document. Returns true
if the local shadow was updated.
AWSCRT._update_local_shadow_from_get!
— Method_update_local_shadow_from_get!(sf::ShadowFramework{T}, payload_str::String) where {T}
Performs a local shadow update using the delta state from a /get/accepted document. Returns true
if the local shadow was updated.
AWSCRT._update_shadow_property!
— Method_update_shadow_property!(sf::ShadowFramework{<:Any}, key::String, value)
Updates the shadow property if the new value
is not equal to the current value at the key
. Returns true
if an update occured.
AWSCRT._update_shadow_property!
— Method_update_shadow_property!(sf::ShadowFramework{<:AbstractDict}, key::String, value)
Updates the shadow property if the new value
is not equal to the current value at the key
. Returns true
if an update occured.
AWSCRT.connect
— Methodconnect(
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. Iftrue
, the server will forget all subscriptions with each reconnect. Setfalse
to request that the server resume an existing session or start a new session that may be resumed after a connection loss. Thesession_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. SeeOnConnectionInterrupted
.on_connection_resumed (Union{OnConnectionResumed,Nothing}) (default=nothing)
: Optional callback invoked whenever the MQTT connection is automatically resumed. SeeOnConnectionResumed
.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 thanping_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 thankeep_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, seeaws_tls_is_alpn_available
.use_websockets (Bool) (default=false)
: # TODO not implementedwebsocket_handshake_transform (nothing) (default=nothing)
: # TODO not implementedproxy_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.
All callbacks are run concurrently. Your callback implementations must be thread-safe. There is no concurrency limit.
AWSCRT.create_client_with_mtls
— Methodcreate_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 contentspk_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, seeaws_tls_is_alpn_available
. This can be customized per connection; seeTLSConnectionOptions
.
AWSCRT.create_client_with_mtls_from_path
— Methodcreate_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, seeaws_tls_is_alpn_available
. This can be customized per connection; seeTLSConnectionOptions
.
AWSCRT.create_server
— Methodcreate_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 contentspk_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, seeaws_tls_is_alpn_available
. This can be customized per connection; seeTLSConnectionOptions
.
AWSCRT.create_server_from_path
— Methodcreate_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, seeaws_tls_is_alpn_available
. This can be customized per connection; seeTLSConnectionOptions
.
AWSCRT.disconnect
— Methoddisconnect(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.
AWSCRT.on_message
— Methodon_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. SeeOnMessage
for the required signature. Set tonothing
to clear this callback.
Returns nothing.
All callbacks are run concurrently. Your callback implementations must be thread-safe. There is no concurrency limit.
AWSCRT.publish
— Functionpublish(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)
: Iftrue
, 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.
AWSCRT.publish
— Methodpublish(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.
AWSCRT.publish_current_state
— MethodPublishes the current state of the shadow document.
Arguments:
include_version (Bool)
: Includes the version of the shadow document if this istrue
. 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.
AWSCRT.resubscribe_existing_topics
— Methodresubscribe_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 benothing
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.
AWSCRT.shadow_client
— Methodshadow_client(sf::ShadowFramework)
Returns the ShadowClient
for sf
.
AWSCRT.subscribe
— Methodsubscribe(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. SeeOnMessage
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.
All callbacks are run concurrently. Your callback implementations must be thread-safe. There is no concurrency limit.
AWSCRT.subscribe
— Methodsubscribe(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. SeeOnShadowMessage
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.
AWSCRT.subscribe
— Methodsubscribe(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. SeeOnMessage
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.
AWSCRT.subscribe
— Methodsubscribe(sf::ShadowFramework{T}) where {T}
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.
AWSCRT.unsubscribe
— Methodunsubscribe(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.
AWSCRT.unsubscribe
— Methodunsubscribe(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.
AWSCRT.unsubscribe
— Methodunsubscribe(sf::ShadowFramework{T}) where {T}
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.
AWSCRT.wait_until_synced
— Methodwait_until_synced(sf::ShadowFramework)
Blocks until the next time the shadow document is synchronized with the broker.
Base.lock
— Methodlock(f::Function, sf::ShadowFramework)
Locks the sf
to ensure atomic access to the shadow document.
Base.lock
— Methodlock(sf::ShadowFramework)
Locks the sf
to ensure atomic access to the shadow document.
Base.unlock
— Methodunlock(sf::ShadowFramework)
Unlocks the sf
.