Struct ipworksmq::AzureRelayReceiver

Properties   Methods   Events   Config Settings   Errors  

An Azure Relay Service listener to accept and communicate with clients.

Syntax

ipworksmq::AzureRelayReceiver

Remarks

The AzureRelayReceiver struct implements the listener role in the Azure Relay service. The struct will connect to the server and listen for incoming connections. Once a connection is established data can be exchange freely in both directions allowing a flexible messaging environment.

Authenticating and Listening

Authentication to Azure Relay is performed using the Shared Access Key Name and Shared Access Key created from the Azure portal for the Relay. To begin listening for incoming connections set listening to True.

When set to True the struct will immediately attempt to make a connection to the Azure Relay Service and begin listening. The following properties are applicable when setting listening:

• access_key (required)
• access_key_name (required)
• hybrid_connection (required)
• namespace_address (required)
• default_timeout
• forwarding_host
• forwarding_port

To stop listening set listening to False. To shutdown the server including existing connections call shutdown.

Handling Connections

When a connection is made the on_connection_request event fires with information about the connecting client. From within this event the client connection may be accepted (default) or rejected.

If the client connection is accepted the on_connection_connected and on_connection_ready_to_send events fire when the connection completes and is ready to send and receive data.

When data is received from the client the on_connection_data_in event fires with the received data.

To send data to the client set send_bytesor call send, send_file, or send_text.

When the client disconnects the on_connection_disconnected event fires. To initiate the client disconnection call disconnect.

Handling HTTP Connections

Azure Relay also supports HTTP connections which follow a request/response model. When an HTTP request is received the on_http_request event fires with information about the request including the request body. Save the ConnectionId value obtained within on_http_request for use with send_http_response.

To send a HTTP response call send_http_response with the ConnectionId, status code and description, and any response day to be sent back to the client.

Forwarding Connections

The struct supports forwarding incoming connection to a separate destination. This functionality allows AzureRelayReceiver to act as a proxy for incoming requests. When forwarding_host and forwarding_port are set anytime a connection is made the struct will establish a separate connection to the forwarding_host and forward all incoming traffic. Responses from the forwarding_host are then automatically sent back over the connection.

When connection forwarding is used no special steps are needed to send or receive data. Data flows freely between the connected client and the forwarding_host.

Note: Forwarding is not supported for HTTP requests.

Code Example (WebSockets)

Azurerelayreceiver listener = new Azurerelayreceiver(); listener.AccessKey = "9oKRDwjl0s440MlLUi4qHxDL34j1FS6K3t5TRoJ216c="; listener.AccessKeyName = "RootManageSharedAccessKey"; listener.NamespaceAddress = "myrelay.servicebus.windows.net"; listener.HybridConnection = "hc1"; listener.OnConnectionRequest += (s, e) => { Console.WriteLine("Connection Request From: " + e.RemoteAddress + ":" + e.RemotePort); e.Accept = true; }; listener.OnConnectionReadyToSend += (s, e) => { Console.WriteLine("Connection [" + e.ConnectionId + "] connected and ready to send and receive."); }; listener.OnConnectionDataIn += (s, e) => { Console.WriteLine("Received data from " + e.ConnectionId + ": " + e.Text); //echo the data back listener.SendText(e.ConnectionId, e.Text); Console.WriteLine("Echoed received data back"); }; listener.Listening = true; while (true) listener.DoEvents();

Code Example (HTTP)

Azurerelaylistener listener = new Azurerelaylistener(); listener.AccessKey = "9oKRDwjl0s440MlLUi4qHxDL34j1FS6K3t5TRoJ216c="; listener.AccessKeyName = "RootManageSharedAccessKey"; listener.NamespaceAddress = "myrelay.servicebus.windows.net"; listener.HybridConnection = "hc1"; listener.OnHTTPRequest += (s, e) => { Console.WriteLine("HTTP Request from " + e.RemoteAddress + ":" + e.RemotePort); Console.WriteLine("HTTP Method: " + e.RequestMethod); Console.WriteLine("HTTP Request: " + e.RequestData); myConnectionId = e.ConnectionId; }; //Send a response using the ConnectionId value from the HTTPRequest event listener.SendHTTPResponse(myConnectionId, 200, "OK", myResponseBody);

Object Lifetime

The new() method returns a mutable reference to a struct instance. The object itself is kept in the global list maintained by IPWorksMQ. Due to this, the AzureRelayReceiver struct cannot be disposed of automatically. Please, call the dispose(&mut self) method of AzureRelayReceiver when you have finished using the instance.

Property List

The following is the full list of the properties of the struct with short descriptions. Click on the links for further details.

Method List

The following is the full list of the methods of the struct with short descriptions. Click on the links for further details.

Event List

The following is the full list of the events fired by the struct with short descriptions. Click on the links for further details.

Config Settings

The following is a list of config settings for the struct with short descriptions. Click on the links for further details.

access_key property (AzureRelayReceiver Struct)

The Shared Access Key.

Syntax

fn access_key(&self ) -> Result<String, IPWorksMQError> 
fn set_access_key(&self, value : &str) ->  Option<IPWorksMQError> 
fn set_access_key_ref(&self, value : &String) ->  Option<IPWorksMQError> 

Default Value

""

Remarks

This property specifies the Shared Access Key to use when authenticating. This is the primary or secondary key of the shared access policy created in the Azure portal. For instance 8oKRDwkl0s440MlLUi4qHxDL34j1FS6K3t5TRoJ216c=.

Data Type

String

access_key_name property (AzureRelayReceiver Struct)

The Shared Access Key Name.

Syntax

fn access_key_name(&self ) -> Result<String, IPWorksMQError> 
fn set_access_key_name(&self, value : &str) ->  Option<IPWorksMQError> 
fn set_access_key_name_ref(&self, value : &String) ->  Option<IPWorksMQError> 

Default Value

""

Remarks

This property specifies the Shared Access Key name to use when authenticating. This is the name of the shared access policy created in the Azure portal. For instance RootManageSharedAccessKey.

Data Type

String

connected property (AzureRelayReceiver Struct)

Whether the struct is connected.

Syntax

fn connected(&self ) -> Result<bool, IPWorksMQError> 

Default Value

false

Remarks

This property is used to determine whether or not the struct is connected to the remote host. Use the connect and disconnect methods to manage the connection.

This property is read-only.

Data Type

bool

azure_relay_connection_count property (AzureRelayReceiver Struct)

The number of records in the AzureRelayConnection arrays.

Syntax

fn azure_relay_connection_count(&self ) -> Result<i32, IPWorksMQError> 

Default Value

0

Remarks

This property controls the size of the following arrays:

• azure_relay_connection_accept_data
• azure_relay_connection_address
• azure_relay_connection_bytes_sent
• azure_relay_connection_connected
• azure_relay_connection_connect_headers
• azure_relay_connection_connection_id
• azure_relay_connection_data_format
• azure_relay_connection_extensions
• azure_relay_connection_host
• azure_relay_connection_id
• azure_relay_connection_ready_to_send
• azure_relay_connection_remote_address
• azure_relay_connection_remote_port
• azure_relay_connection_sub_protocols
• azure_relay_connection_timeout

The array indices start at 0 and end at azure_relay_connection_count - 1.

This property is read-only.

Data Type

i32

azure_relay_connection_accept_data property (AzureRelayReceiver Struct)

Setting this property to False, temporarily disables data reception (and the ConnectionDataIn event) on the connection.

Syntax

fn azure_relay_connection_accept_data(&self , ConnectionId : i32) -> Result<bool, IPWorksMQError> 

Default Value

true

Remarks

Setting this property to False, temporarily disables data reception (and the on_connection_data_in event) on the connection. Setting this to True, re-enables data reception.

The ConnectionId parameter specifies the index of the item in the array. The size of the array is controlled by the AzureRelayConnectionCount property.

This property is read-only.

Data Type

bool

azure_relay_connection_address property (AzureRelayReceiver Struct)

This property holds the rendezvous URL to which the connection specific websocket connection will be made.

Syntax

fn azure_relay_connection_address(&self , ConnectionId : i32) -> Result<String, IPWorksMQError> 

Default Value

""

Remarks

This property holds the rendezvous URL to which the connection specific websocket connection will be made. This is for information only, no action needs to be taken based on this value. For instance: wss://g21-prod-by3-003-sb.servicebus.windows.net/$hc/hc1?sb-hc-action=accept&sb-hc-id=2d4acb89-7d15-4aeb-bcd5-66e031580a90_G21_G1

The ConnectionId parameter specifies the index of the item in the array. The size of the array is controlled by the AzureRelayConnectionCount property.

This property is read-only.

Data Type

String

azure_relay_connection_bytes_sent property (AzureRelayReceiver Struct)

This property shows how many bytes were sent after calling Send or SendBytes .

Syntax

fn azure_relay_connection_bytes_sent(&self , ConnectionId : i32) -> Result<i32, IPWorksMQError> 

Default Value

0

Remarks

This property shows how many bytes were sent after calling send or send_bytes. Please see send or send_bytes for more information.

NOTE: This property will always return 0 when the struct is operating in the synchronous mode (i.e., the azure_relay_connection_timeout property is set to a positive value).

The ConnectionId parameter specifies the index of the item in the array. The size of the array is controlled by the AzureRelayConnectionCount property.

This property is read-only.

Data Type

i32

azure_relay_connection_connected property (AzureRelayReceiver Struct)

This property indicates the status of individual connections.

Syntax

fn azure_relay_connection_connected(&self , ConnectionId : i32) -> Result<bool, IPWorksMQError> 

Default Value

false

Remarks

This property indicates the status of individual connections.

When true, the connection is established. Use the disconnect method to disconnect an existing connection.

The ConnectionId parameter specifies the index of the item in the array. The size of the array is controlled by the AzureRelayConnectionCount property.

This property is read-only.

Data Type

bool

azure_relay_connection_connect_headers property (AzureRelayReceiver Struct)

A JSON object containing the HTTP headers that have been supplied by the sender to the Azure Relay service.

Syntax

fn azure_relay_connection_connect_headers(&self , ConnectionId : i32) -> Result<String, IPWorksMQError> 

Default Value

""

Remarks

A JSON object containing the HTTP headers that have been supplied by the sender to the Azure Relay service. For instance:

"connectHeaders": {
	"Sec-WebSocket-Key": "QocLBwK5J40Qp35L2duoBg==",
	"Sec-WebSocket-Version": "13",
	"Origin": "null",
	"Connection": "Upgrade",
	"Upgrade": "websocket",
	"Accept-Encoding": "gzip, deflate",
	"Host": "nstest.servicebus.windows.net",
	"User-Agent": "IPWorks HTTP Component - www.nsoftware.com"
}

The ConnectionId parameter specifies the index of the item in the array. The size of the array is controlled by the AzureRelayConnectionCount property.

This property is read-only.

Data Type

String

azure_relay_connection_connection_id property (AzureRelayReceiver Struct)

This property contains an identifier generated by the struct to identify each connection.

Syntax

fn azure_relay_connection_connection_id(&self , ConnectionId : i32) -> Result<i32, IPWorksMQError> 

Default Value

0

Remarks

This property contains an identifier generated by the struct to identify each connection. This identifier is unique to this connection.

The ConnectionId parameter specifies the index of the item in the array. The size of the array is controlled by the AzureRelayConnectionCount property.

This property is read-only.

Data Type

i32

azure_relay_connection_data_format property (AzureRelayReceiver Struct)

This property includes the format of the data being sent.

Syntax

fn azure_relay_connection_data_format(&self , ConnectionId : i32) -> Result<i32, IPWorksMQError> 
fn set_azure_relay_connection_data_format(&self, ConnectionId : i32, value : i32) ->  Option<IPWorksMQError> 

Possible Values

0   // Automatic
1   // Text
2   // Binary
9   // Ping
10   // Pong

Default Value

0

Remarks

This property includes the format of the data being sent. When data are sent over an established connection, it is either considered as text or binary data. Text data are UTF-8 encoded. Binary data have no encoding associated with it.

Possible values are as follows:

The ConnectionId parameter specifies the index of the item in the array. The size of the array is controlled by the AzureRelayConnectionCount property.

Data Type

i32

azure_relay_connection_extensions property (AzureRelayReceiver Struct)

The WebSocket extensions sent by the client in the initial WebSocket connection request.

Syntax

fn azure_relay_connection_extensions(&self , ConnectionId : i32) -> Result<String, IPWorksMQError> 

Default Value

""

Remarks

The WebSocket extensions sent by the client in the initial WebSocket connection request.

The ConnectionId parameter specifies the index of the item in the array. The size of the array is controlled by the AzureRelayConnectionCount property.

This property is read-only.

Data Type

String

azure_relay_connection_host property (AzureRelayReceiver Struct)

This property includes the Host header value of the connected client.

Syntax

fn azure_relay_connection_host(&self , ConnectionId : i32) -> Result<String, IPWorksMQError> 

Default Value

""

Remarks

This property includes the Host header value of the connected client.

The ConnectionId parameter specifies the index of the item in the array. The size of the array is controlled by the AzureRelayConnectionCount property.

This property is read-only.

Data Type

String

azure_relay_connection_id property (AzureRelayReceiver Struct)

This property holds the Id of the connection.

Syntax

fn azure_relay_connection_id(&self , ConnectionId : i32) -> Result<String, IPWorksMQError> 

Default Value

""

Remarks

This property holds the Id of the connection. If an Id was specified by the client it is present here, otherwise the Azure Relay service generates a value. For instance: 2d4acb89-7d15-4aeb-bcd5-66e031580a90_G21_G1.

The ConnectionId parameter specifies the index of the item in the array. The size of the array is controlled by the AzureRelayConnectionCount property.

This property is read-only.

Data Type

String

azure_relay_connection_ready_to_send property (AzureRelayReceiver Struct)

This property indicates whether the struct is ready to send data.

Syntax

fn azure_relay_connection_ready_to_send(&self , ConnectionId : i32) -> Result<bool, IPWorksMQError> 

Default Value

false

Remarks

This property indicates whether the struct is ready to send data.

This is true after a client connects but will become false after a failed call to send or send_bytes. After a failed call to send or send_bytes, the on_ready_to_send event will fire and this property will be true when data can be sent again.

The ConnectionId parameter specifies the index of the item in the array. The size of the array is controlled by the AzureRelayConnectionCount property.

This property is read-only.

Data Type

bool

azure_relay_connection_remote_address property (AzureRelayReceiver Struct)

This property holds the IP address of the connecting client.

Syntax

fn azure_relay_connection_remote_address(&self , ConnectionId : i32) -> Result<String, IPWorksMQError> 

Default Value

""

Remarks

This property holds the IP address of the connecting client.

The ConnectionId parameter specifies the index of the item in the array. The size of the array is controlled by the AzureRelayConnectionCount property.

This property is read-only.

Data Type

String

azure_relay_connection_remote_port property (AzureRelayReceiver Struct)

This property holds the port of the connecting client.

Syntax

fn azure_relay_connection_remote_port(&self , ConnectionId : i32) -> Result<i32, IPWorksMQError> 

Default Value

0

Remarks

This property holds the port of the connecting client.

The ConnectionId parameter specifies the index of the item in the array. The size of the array is controlled by the AzureRelayConnectionCount property.

This property is read-only.

Data Type

i32

azure_relay_connection_sub_protocols property (AzureRelayReceiver Struct)

This property includes the subprotocols (application-level protocols layered over the WebSocket Protocol) sent by the client in the initial WebSocket connection request.

Syntax

fn azure_relay_connection_sub_protocols(&self , ConnectionId : i32) -> Result<String, IPWorksMQError> 

Default Value

""

Remarks

This property includes the subprotocols (application-level protocols layered over the WebSocket Protocol) sent by the client in the initial WebSocket connection request.

The ConnectionId parameter specifies the index of the item in the array. The size of the array is controlled by the AzureRelayConnectionCount property.

This property is read-only.

Data Type

String

azure_relay_connection_timeout property (AzureRelayReceiver Struct)

This property specifies a timeout for the struct.

Syntax

fn azure_relay_connection_timeout(&self , ConnectionId : i32) -> Result<i32, IPWorksMQError> 
fn set_azure_relay_connection_timeout(&self, ConnectionId : i32, value : i32) ->  Option<IPWorksMQError> 

Default Value

0

Remarks

This property specifies a timeout for the struct.

If the azure_relay_connection_timeout property is set to 0, all operations return immediately, potentially failing with a WOULDBLOCK error if data cannot be sent immediately.

If azure_relay_connection_timeout is set to a positive value, data is sent in a blocking manner and the struct will wait for the operation to complete before returning control. The struct will handle any potential WOULDBLOCK errors internally and automatically retry the operation for a maximum of azure_relay_connection_timeout seconds.

The struct will use do_events to enter an efficient wait loop during any potential waiting period, making sure that all system events are processed immediately as they arrive. This ensures that the host application does not freeze and remains responsive.

If timeout expires, and the operation is not yet complete, the struct fails with an error.

NOTE: By default, all timeouts are inactivity timeouts, that is, the timeout period is extended by timeout seconds when any amount of data is successfully sent or received.

The default value for the azure_relay_connection_timeout property is 0(asynchronous operation).

The ConnectionId parameter specifies the index of the item in the array. The size of the array is controlled by the AzureRelayConnectionCount property.

Data Type

i32

default_timeout property (AzureRelayReceiver Struct)

An initial timeout value to be used by incoming connections.

Syntax

fn default_timeout(&self ) -> Result<i32, IPWorksMQError> 
fn set_default_timeout(&self, value : i32) ->  Option<IPWorksMQError> 

Default Value

0

Remarks

This property is used by the struct to set the operational timeout value of all inbound connections once they are established.

By default, the timeout is 0, meaning that all inbound connections will behave asynchronously.

Data Type

i32

firewall_auto_detect property (AzureRelayReceiver Struct)

Whether to automatically detect and use firewall system settings, if available.

Syntax

fn firewall_auto_detect(&self ) -> Result<bool, IPWorksMQError> 
fn set_firewall_auto_detect(&self, value : bool) ->  Option<IPWorksMQError> 

Default Value

false

Remarks

Whether to automatically detect and use firewall system settings, if available.

Data Type

bool

firewall_type property (AzureRelayReceiver Struct)

The type of firewall to connect through.

Syntax

fn firewall_type(&self ) -> Result<i32, IPWorksMQError> 
fn set_firewall_type(&self, value : i32) ->  Option<IPWorksMQError> 

Possible Values

0   // None
1   // Tunnel
2   // SOCKS4
3   // SOCKS5
10   // SOCKS4A

Default Value

0

Remarks

The type of firewall to connect through. The applicable values are as follows:

Data Type

i32

firewall_host property (AzureRelayReceiver Struct)

The name or IP address of the firewall (optional).

Syntax

fn firewall_host(&self ) -> Result<String, IPWorksMQError> 
fn set_firewall_host(&self, value : &str) ->  Option<IPWorksMQError> 
fn set_firewall_host_ref(&self, value : &String) ->  Option<IPWorksMQError> 

Default Value

""

Remarks

The name or IP address of the firewall (optional). If a firewall_host is given, the requested connections will be authenticated through the specified firewall when connecting.

If this property is set to a Domain Name, a DNS request is initiated. Upon successful termination of the request, this property is set to the corresponding address. If the search is not successful, the struct fails with an error.

Data Type

String

firewall_password property (AzureRelayReceiver Struct)

A password if authentication is to be used when connecting through the firewall.

Syntax

fn firewall_password(&self ) -> Result<String, IPWorksMQError> 
fn set_firewall_password(&self, value : &str) ->  Option<IPWorksMQError> 
fn set_firewall_password_ref(&self, value : &String) ->  Option<IPWorksMQError> 

Default Value

""

Remarks

A password if authentication is to be used when connecting through the firewall. If firewall_host is specified, the firewall_user and firewall_password properties are used to connect and authenticate to the given firewall. If the authentication fails, the struct fails with an error.

Data Type

String

firewall_port property (AzureRelayReceiver Struct)

The Transmission Control Protocol (TCP) port for the firewall Host .

Syntax

fn firewall_port(&self ) -> Result<i32, IPWorksMQError> 
fn set_firewall_port(&self, value : i32) ->  Option<IPWorksMQError> 

Default Value

0

Remarks

The Transmission Control Protocol (TCP) port for the firewall firewall_host. See the description of the firewall_host property for details.

NOTE: This property is set automatically when firewall_firewall_type is set to a valid value. See the description of the firewall_firewall_type property for details.

Data Type

i32

firewall_user property (AzureRelayReceiver Struct)

A username if authentication is to be used when connecting through a firewall.

Syntax

fn firewall_user(&self ) -> Result<String, IPWorksMQError> 
fn set_firewall_user(&self, value : &str) ->  Option<IPWorksMQError> 
fn set_firewall_user_ref(&self, value : &String) ->  Option<IPWorksMQError> 

Default Value

""

Remarks

A username if authentication is to be used when connecting through a firewall. If firewall_host is specified, this property and the firewall_password property are used to connect and authenticate to the given Firewall. If the authentication fails, the struct fails with an error.

Data Type

String

forwarding_host property (AzureRelayReceiver Struct)

The address to which traffic will automatically be forwarded.

Syntax

fn forwarding_host(&self ) -> Result<String, IPWorksMQError> 
fn set_forwarding_host(&self, value : &str) ->  Option<IPWorksMQError> 
fn set_forwarding_host_ref(&self, value : &String) ->  Option<IPWorksMQError> 

Default Value

""

Remarks

forwarding_host optionally specifies an address to which traffic will be automatically forwarded. Traffic will only be forwarded if both forwarding_host and forwarding_port are specified.

When a connection is made the struct will automatically establish a connection to forwarding_host on the port specified by forwarding_port. Data will then flow freely between the connected client and the forwarding_host.

Note: This functionality is not applicable to HTTP requests.

Data Type

String

forwarding_port property (AzureRelayReceiver Struct)

The port to which traffic will automatically be forwarded.

Syntax

fn forwarding_port(&self ) -> Result<i32, IPWorksMQError> 
fn set_forwarding_port(&self, value : i32) ->  Option<IPWorksMQError> 

Default Value

0

Remarks

forwarding_port is used together with forwarding_host to define a location where traffic is automatically forwarded.

forwarding_host optionally specifies an address to which traffic will be automatically forwarded. Traffic will only be forwarded if both forwarding_host and forwarding_port are specified.

When a connection is made the struct will automatically establish a connection to forwarding_host on the port specified by forwarding_port. Data will then flow freely between the connected client and the forwarding_host.

Note: This functionality is not applicable to HTTP requests.

Data Type

i32

hybrid_connection property (AzureRelayReceiver Struct)

The hybrid connection name.

Syntax

fn hybrid_connection(&self ) -> Result<String, IPWorksMQError> 
fn set_hybrid_connection(&self, value : &str) ->  Option<IPWorksMQError> 
fn set_hybrid_connection_ref(&self, value : &String) ->  Option<IPWorksMQError> 

Default Value

""

Remarks

This setting specifies the name of the hybrid connection that was created in the Azure portal. For instance hc1.

Data Type

String

listening property (AzureRelayReceiver Struct)

If True , the struct is listening for incoming connections.

Syntax

fn listening(&self ) -> Result<bool, IPWorksMQError> 

Default Value

false

Remarks

This setting indicates whether the struct accepts incoming connections. When true the struct has connected to the Azure Service and started listening for incoming connections. The initiate the connection and begin listening call the start_listening method.

Use the start_listening and stop_listening methods to control whether the struct is listening.

This property is read-only.

Data Type

bool

local_host property (AzureRelayReceiver Struct)

The name of the local host or user-assigned IP interface through which connections are initiated or accepted.

Syntax

fn local_host(&self ) -> Result<String, IPWorksMQError> 
fn set_local_host(&self, value : &str) ->  Option<IPWorksMQError> 
fn set_local_host_ref(&self, value : &String) ->  Option<IPWorksMQError> 

Default Value

""

Remarks

This property contains the name of the local host as obtained by the gethostname() system call, or if the user has assigned an IP address, the value of that address.

In multihomed hosts (machines with more than one IP interface) setting LocalHost to the IP address of an interface will make the struct initiate connections (or accept in the case of server structs) only through that interface. It is recommended to provide an IP address rather than a hostname when setting this property to ensure the desired interface is used.

If the struct is connected, the local_host property shows the IP address of the interface through which the connection is made in internet dotted format (aaa.bbb.ccc.ddd). In most cases, this is the address of the local host, except for multihomed hosts (machines with more than one IP interface).

NOTE: local_host is not persistent. You must always set it in code, and never in the property window.

Data Type

String

namespace_address property (AzureRelayReceiver Struct)

The namespace address of the relay.

Syntax

fn namespace_address(&self ) -> Result<String, IPWorksMQError> 
fn set_namespace_address(&self, value : &str) ->  Option<IPWorksMQError> 
fn set_namespace_address_ref(&self, value : &String) ->  Option<IPWorksMQError> 

Default Value

""

Remarks

This property specifies the full fully qualified domain name of the relay namespace. For instance myrelay.servicebus.windows.net.

Data Type

String

proxy_auth_scheme property (AzureRelayReceiver Struct)

The type of authorization to perform when connecting to the proxy.

Syntax

fn proxy_auth_scheme(&self ) -> Result<i32, IPWorksMQError> 
fn set_proxy_auth_scheme(&self, value : i32) ->  Option<IPWorksMQError> 

Possible Values

0   // Basic
1   // Digest
2   // Proprietary
3   // None
4   // Ntlm
5   // Negotiate

Default Value

0

Remarks

The type of authorization to perform when connecting to the proxy. This is used only when the proxy_user and proxy_password properties are set.

proxy_auth_scheme should be set to authNone (3) when no authentication is expected.

By default, proxy_auth_scheme is authBasic (0), and if the proxy_user and proxy_password properties are set, the struct will attempt basic authentication.

If proxy_auth_scheme is set to authDigest (1), digest authentication will be attempted instead.

If proxy_auth_scheme is set to authProprietary (2), then the authorization token will not be generated by the struct. Look at the configuration file for the struct being used to find more information about manually setting this token.

If proxy_auth_scheme is set to authNtlm (4), NTLM authentication will be used.

For security reasons, setting this property will clear the values of proxy_user and proxy_password.

Data Type

i32

proxy_auto_detect property (AzureRelayReceiver Struct)

Whether to automatically detect and use proxy system settings, if available.

Syntax

fn proxy_auto_detect(&self ) -> Result<bool, IPWorksMQError> 
fn set_proxy_auto_detect(&self, value : bool) ->  Option<IPWorksMQError> 

Default Value

false

Remarks

Whether to automatically detect and use proxy system settings, if available. The default value is false.

Data Type

bool

proxy_password property (AzureRelayReceiver Struct)

A password if authentication is to be used for the proxy.

Syntax

fn proxy_password(&self ) -> Result<String, IPWorksMQError> 
fn set_proxy_password(&self, value : &str) ->  Option<IPWorksMQError> 
fn set_proxy_password_ref(&self, value : &String) ->  Option<IPWorksMQError> 

Default Value

""

Remarks

A password if authentication is to be used for the proxy.

If proxy_auth_scheme is set to Basic Authentication, the proxy_user and proxy_password properties are Base64 encoded and the proxy authentication token will be generated in the form Basic [encoded-user-password].

If proxy_auth_scheme is set to Digest Authentication, the proxy_user and proxy_password properties are used to respond to the Digest Authentication challenge from the server.

If proxy_auth_scheme is set to NTLM Authentication, the proxy_user and proxy_password properties are used to authenticate through NTLM negotiation.

Data Type

String

proxy_port property (AzureRelayReceiver Struct)

The Transmission Control Protocol (TCP) port for the proxy Server (default 80).

Syntax

fn proxy_port(&self ) -> Result<i32, IPWorksMQError> 
fn set_proxy_port(&self, value : i32) ->  Option<IPWorksMQError> 

Default Value

80

Remarks

The Transmission Control Protocol (TCP) port for the proxy proxy_server (default 80). See the description of the proxy_server property for details.

Data Type

i32

proxy_server property (AzureRelayReceiver Struct)

If a proxy Server is given, then the HTTP request is sent to the proxy instead of the server otherwise specified.

Syntax

fn proxy_server(&self ) -> Result<String, IPWorksMQError> 
fn set_proxy_server(&self, value : &str) ->  Option<IPWorksMQError> 
fn set_proxy_server_ref(&self, value : &String) ->  Option<IPWorksMQError> 

Default Value

""

Remarks

If a proxy proxy_server is given, then the HTTP request is sent to the proxy instead of the server otherwise specified.

If the proxy_server property is set to a domain name, a DNS request is initiated. Upon successful termination of the request, the proxy_server property is set to the corresponding address. If the search is not successful, an error is returned.

Data Type

String

proxy_ssl property (AzureRelayReceiver Struct)

When to use a Secure Sockets Layer (SSL) for the connection to the proxy.

Syntax

fn proxy_ssl(&self ) -> Result<i32, IPWorksMQError> 
fn set_proxy_ssl(&self, value : i32) ->  Option<IPWorksMQError> 

Possible Values

0   // Automatic
1   // Always
2   // Never
3   // Tunnel

Default Value

0

Remarks

When to use a Secure Sockets Layer (SSL) for the connection to the proxy. The applicable values are as follows:

Data Type

i32

proxy_user property (AzureRelayReceiver Struct)

A username if authentication is to be used for the proxy.

Syntax

fn proxy_user(&self ) -> Result<String, IPWorksMQError> 
fn set_proxy_user(&self, value : &str) ->  Option<IPWorksMQError> 
fn set_proxy_user_ref(&self, value : &String) ->  Option<IPWorksMQError> 

Default Value

""

Remarks

A username if authentication is to be used for the proxy.

If proxy_auth_scheme is set to Basic Authentication, the proxy_user and proxy_password properties are Base64 encoded and the proxy authentication token will be generated in the form Basic [encoded-user-password].

If proxy_auth_scheme is set to Digest Authentication, the proxy_user and proxy_password properties are used to respond to the Digest Authentication challenge from the server.

If proxy_auth_scheme is set to NTLM Authentication, the proxy_user and proxy_password properties are used to authenticate through NTLM negotiation.

Data Type

String

ssl_accept_server_cert_effective_date property (AzureRelayReceiver Struct)

The date on which this certificate becomes valid.

Syntax

fn ssl_accept_server_cert_effective_date(&self ) -> Result<String, IPWorksMQError> 

Default Value

""

Remarks

The date on which this certificate becomes valid. Before this date, it is not valid. The date is localized to the system's time zone. The following example illustrates the format of an encoded date:

23-Jan-2000 15:00:00.

This property is read-only.

Data Type

String

ssl_accept_server_cert_expiration_date property (AzureRelayReceiver Struct)

The date on which the certificate expires.

Syntax

fn ssl_accept_server_cert_expiration_date(&self ) -> Result<String, IPWorksMQError> 

Default Value

""

Remarks

The date on which the certificate expires. After this date, the certificate will no longer be valid. The date is localized to the system's time zone. The following example illustrates the format of an encoded date:

23-Jan-2001 15:00:00.

This property is read-only.

Data Type

String

ssl_accept_server_cert_extended_key_usage property (AzureRelayReceiver Struct)

A comma-delimited list of extended key usage identifiers.

Syntax

fn ssl_accept_server_cert_extended_key_usage(&self ) -> Result<String, IPWorksMQError> 

Default Value

""

Remarks

A comma-delimited list of extended key usage identifiers. These are the same as ASN.1 object identifiers (OIDs).

This property is read-only.

Data Type

String

ssl_accept_server_cert_fingerprint property (AzureRelayReceiver Struct)

The hex-encoded, 16-byte MD5 fingerprint of the certificate.

Syntax

fn ssl_accept_server_cert_fingerprint(&self ) -> Result<String, IPWorksMQError> 

Default Value

""

Remarks

The hex-encoded, 16-byte MD5 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: bc:2a:72:af:fe:58:17:43:7a:5f:ba:5a:7c:90:f7:02

This property is read-only.

Data Type

String

ssl_accept_server_cert_fingerprint_sha1 property (AzureRelayReceiver Struct)

The hex-encoded, 20-byte SHA-1 fingerprint of the certificate.

Syntax

fn ssl_accept_server_cert_fingerprint_sha1(&self ) -> Result<String, IPWorksMQError> 

Default Value

""

Remarks

The hex-encoded, 20-byte SHA-1 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: 30:7b:fa:38:65:83:ff:da:b4:4e:07:3f:17:b8:a4:ed:80:be:ff:84

This property is read-only.

Data Type

String

ssl_accept_server_cert_fingerprint_sha256 property (AzureRelayReceiver Struct)

The hex-encoded, 32-byte SHA-256 fingerprint of the certificate.

Syntax

fn ssl_accept_server_cert_fingerprint_sha256(&self ) -> Result<String, IPWorksMQError> 

Default Value

""

Remarks

The hex-encoded, 32-byte SHA-256 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: 6a:80:5c:33:a9:43:ea:b0:96:12:8a:64:96:30:ef:4a:8a:96:86:ce:f4:c7:be:10:24:8e:2b:60:9e:f3:59:53

This property is read-only.

Data Type

String

ssl_accept_server_cert_issuer property (AzureRelayReceiver Struct)

The issuer of the certificate.

Syntax

fn ssl_accept_server_cert_issuer(&self ) -> Result<String, IPWorksMQError> 

Default Value

""

Remarks

The issuer of the certificate. This property contains a string representation of the name of the issuing authority for the certificate.

This property is read-only.

Data Type

String

ssl_accept_server_cert_private_key property (AzureRelayReceiver Struct)

The private key of the certificate (if available).

Syntax

fn ssl_accept_server_cert_private_key(&self ) -> Result<String, IPWorksMQError> 

Default Value

""

Remarks

The private key of the certificate (if available). The key is provided as PEM/Base64-encoded data.

NOTE: The ssl_accept_server_cert_private_key may be available but not exportable. In this case, ssl_accept_server_cert_private_key returns an empty string.

This property is read-only.

Data Type

String

ssl_accept_server_cert_private_key_available property (AzureRelayReceiver Struct)

Whether a PrivateKey is available for the selected certificate.

Syntax

fn ssl_accept_server_cert_private_key_available(&self ) -> Result<bool, IPWorksMQError> 

Default Value

false

Remarks

Whether a ssl_accept_server_cert_private_key is available for the selected certificate. If ssl_accept_server_cert_private_key_available is True, the certificate may be used for authentication purposes (e.g., server authentication).

This property is read-only.

Data Type

bool

ssl_accept_server_cert_private_key_container property (AzureRelayReceiver Struct)

The name of the PrivateKey container for the certificate (if available).

Syntax

fn ssl_accept_server_cert_private_key_container(&self ) -> Result<String, IPWorksMQError> 

Default Value

""

Remarks

The name of the ssl_accept_server_cert_private_key container for the certificate (if available). This functionality is available only on Windows platforms.

This property is read-only.

Data Type

String

ssl_accept_server_cert_public_key property (AzureRelayReceiver Struct)

The public key of the certificate.

Syntax

fn ssl_accept_server_cert_public_key(&self ) -> Result<String, IPWorksMQError> 

Default Value

""

Remarks

The public key of the certificate. The key is provided as PEM/Base64-encoded data.

This property is read-only.

Data Type

String

ssl_accept_server_cert_public_key_algorithm property (AzureRelayReceiver Struct)

The textual description of the certificate's public key algorithm.

Syntax

fn ssl_accept_server_cert_public_key_algorithm(&self ) -> Result<String, IPWorksMQError> 

Default Value

""

Remarks

The textual description of the certificate's public key algorithm. The property contains either the name of the algorithm (e.g., "RSA" or "RSA_DH") or an object identifier (OID) string representing the algorithm.

This property is read-only.

Data Type

String

ssl_accept_server_cert_public_key_length property (AzureRelayReceiver Struct)

The length of the certificate's public key (in bits).

Syntax

fn ssl_accept_server_cert_public_key_length(&self ) -> Result<i32, IPWorksMQError> 

Default Value

0

Remarks

The length of the certificate's public key (in bits). Common values are 512, 1024, and 2048.

This property is read-only.

Data Type

i32

ssl_accept_server_cert_serial_number property (AzureRelayReceiver Struct)

The serial number of the certificate encoded as a string.

Syntax

fn ssl_accept_server_cert_serial_number(&self ) -> Result<String, IPWorksMQError> 

Default Value

""

Remarks

The serial number of the certificate encoded as a string. The number is encoded as a series of hexadecimal digits, with each pair representing a byte of the serial number.

This property is read-only.

Data Type

String

ssl_accept_server_cert_signature_algorithm property (AzureRelayReceiver Struct)

The text description of the certificate's signature algorithm.

Syntax

fn ssl_accept_server_cert_signature_algorithm(&self ) -> Result<String, IPWorksMQError> 

Default Value

""

Remarks

The text description of the certificate's signature algorithm. The property contains either the name of the algorithm (e.g., "RSA" or "RSA_MD5RSA") or an object identifier (OID) string representing the algorithm.

This property is read-only.

Data Type

String

ssl_accept_server_cert_store property (AzureRelayReceiver Struct)

The name of the certificate store for the client certificate.

Syntax

fn ssl_accept_server_cert_store(&self ) -> Result<Vec<u8>, IPWorksMQError> 
fn set_ssl_accept_server_cert_store(&self, value : Vec<u8>) ->  Option<IPWorksMQError> 
fn set_ssl_accept_server_cert_store_ref(&self, value : &[u8]) ->  Option<IPWorksMQError> 

Default Value

"MY"

Remarks

The name of the certificate store for the client certificate.

The ssl_accept_server_cert_store_type property denotes the type of the certificate store specified by ssl_accept_server_cert_store. If the store is password-protected, specify the password in ssl_accept_server_cert_store_password.

ssl_accept_server_cert_store is used in conjunction with the ssl_accept_server_cert_subject property to specify client certificates. If ssl_accept_server_cert_store has a value, and ssl_accept_server_cert_subject or ssl_accept_server_cert_encoded is set, a search for a certificate is initiated. Please see the ssl_accept_server_cert_subject property for details.

Designations of certificate stores are platform dependent.

The following designations are the most common User and Machine certificate stores in Windows:

When the certificate store type is cstPFXFile, this property must be set to the name of the file. When the type is cstPFXBlob, the property must be set to the binary contents of a PFX file (i.e., PKCS#12 certificate store).

Data Type

Vec

ssl_accept_server_cert_store_password property (AzureRelayReceiver Struct)

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

Syntax

fn ssl_accept_server_cert_store_password(&self ) -> Result<String, IPWorksMQError> 
fn set_ssl_accept_server_cert_store_password(&self, value : &str) ->  Option<IPWorksMQError> 
fn set_ssl_accept_server_cert_store_password_ref(&self, value : &String) ->  Option<IPWorksMQError> 

Default Value

""

Remarks

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

Data Type

String

ssl_accept_server_cert_store_type property (AzureRelayReceiver Struct)

The type of certificate store for this certificate.

Syntax

fn ssl_accept_server_cert_store_type(&self ) -> Result<i32, IPWorksMQError> 
fn set_ssl_accept_server_cert_store_type(&self, value : i32) ->  Option<IPWorksMQError> 

Possible Values

0   // User
1   // Machine
2   // PFXFile
3   // PFXBlob
4   // JKSFile
5   // JKSBlob
6   // PEMKeyFile
7   // PEMKeyBlob
8   // PublicKeyFile
9   // PublicKeyBlob
10   // SSHPublicKeyBlob
11   // P7BFile
12   // P7BBlob
13   // SSHPublicKeyFile
14   // PPKFile
15   // PPKBlob
16   // XMLFile
17   // XMLBlob
18   // JWKFile
19   // JWKBlob
20   // SecurityKey
21   // BCFKSFile
22   // BCFKSBlob
23   // PKCS11
99   // Auto

Default Value

0

Remarks

The type of certificate store for this certificate.

The struct supports both public and private keys in a variety of formats. When the cstAuto value is used, the struct will automatically determine the type. This property can take one of the following values:

Data Type

i32

ssl_accept_server_cert_subject_alt_names property (AzureRelayReceiver Struct)

Comma-separated lists of alternative subject names for the certificate.

Syntax

fn ssl_accept_server_cert_subject_alt_names(&self ) -> Result<String, IPWorksMQError> 

Default Value

""

Remarks

Comma-separated lists of alternative subject names for the certificate.

This property is read-only.

Data Type

String

ssl_accept_server_cert_thumbprint_md5 property (AzureRelayReceiver Struct)

The MD5 hash of the certificate.

Syntax

fn ssl_accept_server_cert_thumbprint_md5(&self ) -> Result<String, IPWorksMQError> 

Default Value

""

Remarks

The MD5 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

This property is read-only.

Data Type

String

ssl_accept_server_cert_thumbprint_sha1 property (AzureRelayReceiver Struct)

The SHA-1 hash of the certificate.

Syntax

fn ssl_accept_server_cert_thumbprint_sha1(&self ) -> Result<String, IPWorksMQError> 

Default Value

""

Remarks

The SHA-1 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

This property is read-only.

Data Type

String

ssl_accept_server_cert_thumbprint_sha256 property (AzureRelayReceiver Struct)

The SHA-256 hash of the certificate.

Syntax

fn ssl_accept_server_cert_thumbprint_sha256(&self ) -> Result<String, IPWorksMQError> 

Default Value

""

Remarks

The SHA-256 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

This property is read-only.

Data Type

String

ssl_accept_server_cert_usage property (AzureRelayReceiver Struct)

The text description of UsageFlags .

Syntax

fn ssl_accept_server_cert_usage(&self ) -> Result<String, IPWorksMQError> 

Default Value

""

Remarks

The text description of ssl_accept_server_cert_usage_flags.

This value will be one or more of the following strings and will be separated by commas:

• Digital Signature
• Non-Repudiation
• Key Encipherment
• Data Encipherment
• Key Agreement
• Certificate Signing
• CRL Signing
• Encipher Only

If the provider is OpenSSL, the value is a comma-separated list of X.509 certificate extension names.

This property is read-only.

Data Type

String

ssl_accept_server_cert_usage_flags property (AzureRelayReceiver Struct)

The flags that show intended use for the certificate.

Syntax

fn ssl_accept_server_cert_usage_flags(&self ) -> Result<i32, IPWorksMQError> 

Default Value

0

Remarks

The flags that show intended use for the certificate. The value of ssl_accept_server_cert_usage_flags is a combination of the following flags:

Please see the ssl_accept_server_cert_usage property for a text representation of ssl_accept_server_cert_usage_flags.

This functionality currently is not available when the provider is OpenSSL.

This property is read-only.

Data Type

i32

ssl_accept_server_cert_version property (AzureRelayReceiver Struct)

The certificate's version number.

Syntax

fn ssl_accept_server_cert_version(&self ) -> Result<String, IPWorksMQError> 

Default Value

""

Remarks

The certificate's version number. The possible values are the strings "V1", "V2", and "V3".

This property is read-only.

Data Type

String

ssl_accept_server_cert_subject property (AzureRelayReceiver Struct)

The subject of the certificate used for client authentication.

Syntax

fn ssl_accept_server_cert_subject(&self ) -> Result<String, IPWorksMQError> 
fn set_ssl_accept_server_cert_subject(&self, value : &str) ->  Option<IPWorksMQError> 
fn set_ssl_accept_server_cert_subject_ref(&self, value : &String) ->  Option<IPWorksMQError> 

Default Value

""

Remarks

The subject of the certificate used for client authentication.

This property must be set after all other certificate properties are set. When this property is set, a search is performed in the current certificate store to locate a certificate with a matching subject.

If a matching certificate is found, the property is set to the full subject of the matching certificate.

If an exact match is not found, the store is searched for subjects containing the value of the property.

If a match is still not found, the property is set to an empty string, and no certificate is selected.

The special value "*" picks a random certificate in the certificate store.

The certificate subject is a comma-separated list of distinguished name fields and values. For instance, "CN=www.server.com, OU=test, C=US, E=example@email.com". Common fields and their meanings are as follows:

If a field value contains a comma, it must be quoted.

Data Type

String

ssl_accept_server_cert_encoded property (AzureRelayReceiver Struct)

The certificate (PEM/Base64 encoded).

Syntax

fn ssl_accept_server_cert_encoded(&self ) -> Result<Vec<u8>, IPWorksMQError> 
fn set_ssl_accept_server_cert_encoded(&self, value : Vec<u8>) ->  Option<IPWorksMQError> 
fn set_ssl_accept_server_cert_encoded_ref(&self, value : &[u8]) ->  Option<IPWorksMQError> 

Default Value

""

Remarks

The certificate (PEM/Base64 encoded). This property is used to assign a specific certificate. The ssl_accept_server_cert_store and ssl_accept_server_cert_subject properties also may be used to specify a certificate.

When ssl_accept_server_cert_encoded is set, a search is initiated in the current ssl_accept_server_cert_store for the private key of the certificate. If the key is found, ssl_accept_server_cert_subject is updated to reflect the full subject of the selected certificate; otherwise, ssl_accept_server_cert_subject is set to an empty string.

Data Type

Vec

ssl_cert_effective_date property (AzureRelayReceiver Struct)

The date on which this certificate becomes valid.

Syntax

fn ssl_cert_effective_date(&self ) -> Result<String, IPWorksMQError> 

Default Value

""

Remarks

The date on which this certificate becomes valid. Before this date, it is not valid. The date is localized to the system's time zone. The following example illustrates the format of an encoded date:

23-Jan-2000 15:00:00.

This property is read-only.

Data Type

String

ssl_cert_expiration_date property (AzureRelayReceiver Struct)

The date on which the certificate expires.

Syntax

fn ssl_cert_expiration_date(&self ) -> Result<String, IPWorksMQError> 

Default Value

""

Remarks

The date on which the certificate expires. After this date, the certificate will no longer be valid. The date is localized to the system's time zone. The following example illustrates the format of an encoded date:

23-Jan-2001 15:00:00.

This property is read-only.

Data Type

String

ssl_cert_extended_key_usage property (AzureRelayReceiver Struct)

A comma-delimited list of extended key usage identifiers.

Syntax

fn ssl_cert_extended_key_usage(&self ) -> Result<String, IPWorksMQError> 

Default Value

""

Remarks

A comma-delimited list of extended key usage identifiers. These are the same as ASN.1 object identifiers (OIDs).

This property is read-only.

Data Type

String

ssl_cert_fingerprint property (AzureRelayReceiver Struct)

The hex-encoded, 16-byte MD5 fingerprint of the certificate.

Syntax

fn ssl_cert_fingerprint(&self ) -> Result<String, IPWorksMQError> 

Default Value

""

Remarks

The hex-encoded, 16-byte MD5 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: bc:2a:72:af:fe:58:17:43:7a:5f:ba:5a:7c:90:f7:02

This property is read-only.

Data Type

String

ssl_cert_fingerprint_sha1 property (AzureRelayReceiver Struct)

The hex-encoded, 20-byte SHA-1 fingerprint of the certificate.

Syntax

fn ssl_cert_fingerprint_sha1(&self ) -> Result<String, IPWorksMQError> 

Default Value

""

Remarks

The hex-encoded, 20-byte SHA-1 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: 30:7b:fa:38:65:83:ff:da:b4:4e:07:3f:17:b8:a4:ed:80:be:ff:84

This property is read-only.

Data Type

String

ssl_cert_fingerprint_sha256 property (AzureRelayReceiver Struct)

The hex-encoded, 32-byte SHA-256 fingerprint of the certificate.

Syntax

fn ssl_cert_fingerprint_sha256(&self ) -> Result<String, IPWorksMQError> 

Default Value

""

Remarks

The hex-encoded, 32-byte SHA-256 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: 6a:80:5c:33:a9:43:ea:b0:96:12:8a:64:96:30:ef:4a:8a:96:86:ce:f4:c7:be:10:24:8e:2b:60:9e:f3:59:53

This property is read-only.

Data Type

String

ssl_cert_issuer property (AzureRelayReceiver Struct)

The issuer of the certificate.

Syntax

fn ssl_cert_issuer(&self ) -> Result<String, IPWorksMQError> 

Default Value

""

Remarks

The issuer of the certificate. This property contains a string representation of the name of the issuing authority for the certificate.

This property is read-only.

Data Type

String

ssl_cert_private_key property (AzureRelayReceiver Struct)

The private key of the certificate (if available).

Syntax

fn ssl_cert_private_key(&self ) -> Result<String, IPWorksMQError> 

Default Value

""

Remarks

The private key of the certificate (if available). The key is provided as PEM/Base64-encoded data.

NOTE: The ssl_cert_private_key may be available but not exportable. In this case, ssl_cert_private_key returns an empty string.

This property is read-only.

Data Type

String

ssl_cert_private_key_available property (AzureRelayReceiver Struct)

Whether a PrivateKey is available for the selected certificate.

Syntax

fn ssl_cert_private_key_available(&self ) -> Result<bool, IPWorksMQError> 

Default Value

false

Remarks

Whether a ssl_cert_private_key is available for the selected certificate. If ssl_cert_private_key_available is True, the certificate may be used for authentication purposes (e.g., server authentication).

This property is read-only.

Data Type

bool

ssl_cert_private_key_container property (AzureRelayReceiver Struct)

The name of the PrivateKey container for the certificate (if available).

Syntax

fn ssl_cert_private_key_container(&self ) -> Result<String, IPWorksMQError> 

Default Value

""

Remarks

The name of the ssl_cert_private_key container for the certificate (if available). This functionality is available only on Windows platforms.

This property is read-only.

Data Type

String

ssl_cert_public_key property (AzureRelayReceiver Struct)

The public key of the certificate.

Syntax

fn ssl_cert_public_key(&self ) -> Result<String, IPWorksMQError> 

Default Value

""

Remarks

The public key of the certificate. The key is provided as PEM/Base64-encoded data.

This property is read-only.

Data Type

String

ssl_cert_public_key_algorithm property (AzureRelayReceiver Struct)

The textual description of the certificate's public key algorithm.

Syntax

fn ssl_cert_public_key_algorithm(&self ) -> Result<String, IPWorksMQError> 

Default Value

""

Remarks

The textual description of the certificate's public key algorithm. The property contains either the name of the algorithm (e.g., "RSA" or "RSA_DH") or an object identifier (OID) string representing the algorithm.

This property is read-only.

Data Type

String

ssl_cert_public_key_length property (AzureRelayReceiver Struct)

The length of the certificate's public key (in bits).

Syntax

fn ssl_cert_public_key_length(&self ) -> Result<i32, IPWorksMQError> 

Default Value

0

Remarks

The length of the certificate's public key (in bits). Common values are 512, 1024, and 2048.

This property is read-only.

Data Type

i32

ssl_cert_serial_number property (AzureRelayReceiver Struct)

The serial number of the certificate encoded as a string.

Syntax

fn ssl_cert_serial_number(&self ) -> Result<String, IPWorksMQError> 

Default Value

""

Remarks

The serial number of the certificate encoded as a string. The number is encoded as a series of hexadecimal digits, with each pair representing a byte of the serial number.

This property is read-only.

Data Type

String

ssl_cert_signature_algorithm property (AzureRelayReceiver Struct)

The text description of the certificate's signature algorithm.

Syntax

fn ssl_cert_signature_algorithm(&self ) -> Result<String, IPWorksMQError> 

Default Value

""

Remarks

The text description of the certificate's signature algorithm. The property contains either the name of the algorithm (e.g., "RSA" or "RSA_MD5RSA") or an object identifier (OID) string representing the algorithm.

This property is read-only.

Data Type

String

ssl_cert_store property (AzureRelayReceiver Struct)

The name of the certificate store for the client certificate.

Syntax

fn ssl_cert_store(&self ) -> Result<Vec<u8>, IPWorksMQError> 
fn set_ssl_cert_store(&self, value : Vec<u8>) ->  Option<IPWorksMQError> 
fn set_ssl_cert_store_ref(&self, value : &[u8]) ->  Option<IPWorksMQError> 

Default Value

"MY"

Remarks

The name of the certificate store for the client certificate.

The ssl_cert_store_type property denotes the type of the certificate store specified by ssl_cert_store. If the store is password-protected, specify the password in ssl_cert_store_password.

ssl_cert_store is used in conjunction with the ssl_cert_subject property to specify client certificates. If ssl_cert_store has a value, and ssl_cert_subject or ssl_cert_encoded is set, a search for a certificate is initiated. Please see the ssl_cert_subject property for details.

Designations of certificate stores are platform dependent.

The following designations are the most common User and Machine certificate stores in Windows:

When the certificate store type is cstPFXFile, this property must be set to the name of the file. When the type is cstPFXBlob, the property must be set to the binary contents of a PFX file (i.e., PKCS#12 certificate store).

Data Type

Vec

ssl_cert_store_password property (AzureRelayReceiver Struct)

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

Syntax

fn ssl_cert_store_password(&self ) -> Result<String, IPWorksMQError> 
fn set_ssl_cert_store_password(&self, value : &str) ->  Option<IPWorksMQError> 
fn set_ssl_cert_store_password_ref(&self, value : &String) ->  Option<IPWorksMQError> 

Default Value

""

Remarks

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

Data Type

String

ssl_cert_store_type property (AzureRelayReceiver Struct)

The type of certificate store for this certificate.

Syntax

fn ssl_cert_store_type(&self ) -> Result<i32, IPWorksMQError> 
fn set_ssl_cert_store_type(&self, value : i32) ->  Option<IPWorksMQError> 

Possible Values

0   // User
1   // Machine
2   // PFXFile
3   // PFXBlob
4   // JKSFile
5   // JKSBlob
6   // PEMKeyFile
7   // PEMKeyBlob
8   // PublicKeyFile
9   // PublicKeyBlob
10   // SSHPublicKeyBlob
11   // P7BFile
12   // P7BBlob
13   // SSHPublicKeyFile
14   // PPKFile
15   // PPKBlob
16   // XMLFile
17   // XMLBlob
18   // JWKFile
19   // JWKBlob
20   // SecurityKey
21   // BCFKSFile
22   // BCFKSBlob
23   // PKCS11
99   // Auto

Default Value

0

Remarks

The type of certificate store for this certificate.

The struct supports both public and private keys in a variety of formats. When the cstAuto value is used, the struct will automatically determine the type. This property can take one of the following values:

Data Type

i32

ssl_cert_subject_alt_names property (AzureRelayReceiver Struct)

Comma-separated lists of alternative subject names for the certificate.

Syntax

fn ssl_cert_subject_alt_names(&self ) -> Result<String, IPWorksMQError> 

Default Value

""

Remarks

Comma-separated lists of alternative subject names for the certificate.

This property is read-only.

Data Type

String

ssl_cert_thumbprint_md5 property (AzureRelayReceiver Struct)

The MD5 hash of the certificate.

Syntax

fn ssl_cert_thumbprint_md5(&self ) -> Result<String, IPWorksMQError> 

Default Value

""

Remarks

The MD5 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

This property is read-only.

Data Type

String

ssl_cert_thumbprint_sha1 property (AzureRelayReceiver Struct)

The SHA-1 hash of the certificate.

Syntax

fn ssl_cert_thumbprint_sha1(&self ) -> Result<String, IPWorksMQError> 

Default Value

""

Remarks

The SHA-1 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

This property is read-only.

Data Type

String

ssl_cert_thumbprint_sha256 property (AzureRelayReceiver Struct)

The SHA-256 hash of the certificate.

Syntax

fn ssl_cert_thumbprint_sha256(&self ) -> Result<String, IPWorksMQError> 

Default Value

""

Remarks

The SHA-256 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

This property is read-only.

Data Type

String

ssl_cert_usage property (AzureRelayReceiver Struct)

The text description of UsageFlags .

Syntax

fn ssl_cert_usage(&self ) -> Result<String, IPWorksMQError> 

Default Value

""

Remarks

The text description of ssl_cert_usage_flags.

This value will be one or more of the following strings and will be separated by commas:

• Digital Signature
• Non-Repudiation
• Key Encipherment
• Data Encipherment
• Key Agreement
• Certificate Signing
• CRL Signing
• Encipher Only

If the provider is OpenSSL, the value is a comma-separated list of X.509 certificate extension names.

This property is read-only.

Data Type

String

ssl_cert_usage_flags property (AzureRelayReceiver Struct)

The flags that show intended use for the certificate.

Syntax

fn ssl_cert_usage_flags(&self ) -> Result<i32, IPWorksMQError> 

Default Value

0

Remarks

The flags that show intended use for the certificate. The value of ssl_cert_usage_flags is a combination of the following flags:

Please see the ssl_cert_usage property for a text representation of ssl_cert_usage_flags.

This functionality currently is not available when the provider is OpenSSL.

This property is read-only.

Data Type

i32

ssl_cert_version property (AzureRelayReceiver Struct)

The certificate's version number.

Syntax

fn ssl_cert_version(&self ) -> Result<String, IPWorksMQError> 

Default Value

""

Remarks

The certificate's version number. The possible values are the strings "V1", "V2", and "V3".

This property is read-only.

Data Type

String

ssl_cert_subject property (AzureRelayReceiver Struct)

The subject of the certificate used for client authentication.

Syntax

fn ssl_cert_subject(&self ) -> Result<String, IPWorksMQError> 
fn set_ssl_cert_subject(&self, value : &str) ->  Option<IPWorksMQError> 
fn set_ssl_cert_subject_ref(&self, value : &String) ->  Option<IPWorksMQError> 

Default Value

""

Remarks

The subject of the certificate used for client authentication.

This property must be set after all other certificate properties are set. When this property is set, a search is performed in the current certificate store to locate a certificate with a matching subject.

If a matching certificate is found, the property is set to the full subject of the matching certificate.

If an exact match is not found, the store is searched for subjects containing the value of the property.

If a match is still not found, the property is set to an empty string, and no certificate is selected.

The special value "*" picks a random certificate in the certificate store.

The certificate subject is a comma-separated list of distinguished name fields and values. For instance, "CN=www.server.com, OU=test, C=US, E=example@email.com". Common fields and their meanings are as follows:

If a field value contains a comma, it must be quoted.

Data Type

String

ssl_cert_encoded property (AzureRelayReceiver Struct)

The certificate (PEM/Base64 encoded).

Syntax

fn ssl_cert_encoded(&self ) -> Result<Vec<u8>, IPWorksMQError> 
fn set_ssl_cert_encoded(&self, value : Vec<u8>) ->  Option<IPWorksMQError> 
fn set_ssl_cert_encoded_ref(&self, value : &[u8]) ->  Option<IPWorksMQError> 

Default Value

""

Remarks

The certificate (PEM/Base64 encoded). This property is used to assign a specific certificate. The ssl_cert_store and ssl_cert_subject properties also may be used to specify a certificate.

When ssl_cert_encoded is set, a search is initiated in the current ssl_cert_store for the private key of the certificate. If the key is found, ssl_cert_subject is updated to reflect the full subject of the selected certificate; otherwise, ssl_cert_subject is set to an empty string.

Data Type

Vec

ssl_provider property (AzureRelayReceiver Struct)

The Secure Sockets Layer/Transport Layer Security (SSL/TLS) implementation to use.

Syntax

fn ssl_provider(&self ) -> Result<i32, IPWorksMQError> 
fn set_ssl_provider(&self, value : i32) ->  Option<IPWorksMQError> 

Possible Values

0   // Automatic
1   // Platform
2   // Internal

Default Value

0

Remarks

This property specifies the SSL/TLS implementation to use. In most cases the default value of 0 (Automatic) is recommended and should not be changed. When set to 0 (Automatic), the struct will select whether to use the platform implementation or the internal implementation depending on the operating system as well as the TLS version being used.

Possible values are as follows:

In most cases using the default value (Automatic) is recommended. The struct will select a provider depending on the current platform.

When Automatic is selected, on Windows, the struct will use the platform implementation. On Linux/macOS, the struct will use the internal implementation. When TLS 1.3 is enabled via SSLEnabledProtocols, the struct will always try and use the platform implementation. If the platform TLS 1.3 implementation is not available, the internal implementation will be used.

Data Type

i32

ssl_server_cert_effective_date property (AzureRelayReceiver Struct)

The date on which this certificate becomes valid.

Syntax

fn ssl_server_cert_effective_date(&self ) -> Result<String, IPWorksMQError> 

Default Value

""

Remarks

The date on which this certificate becomes valid. Before this date, it is not valid. The date is localized to the system's time zone. The following example illustrates the format of an encoded date:

23-Jan-2000 15:00:00.

This property is read-only.

Data Type

String

ssl_server_cert_expiration_date property (AzureRelayReceiver Struct)

The date on which the certificate expires.

Syntax

fn ssl_server_cert_expiration_date(&self ) -> Result<String, IPWorksMQError> 

Default Value

""

Remarks

The date on which the certificate expires. After this date, the certificate will no longer be valid. The date is localized to the system's time zone. The following example illustrates the format of an encoded date:

23-Jan-2001 15:00:00.

This property is read-only.

Data Type

String

ssl_server_cert_extended_key_usage property (AzureRelayReceiver Struct)

A comma-delimited list of extended key usage identifiers.

Syntax

fn ssl_server_cert_extended_key_usage(&self ) -> Result<String, IPWorksMQError> 

Default Value

""

Remarks

A comma-delimited list of extended key usage identifiers. These are the same as ASN.1 object identifiers (OIDs).

This property is read-only.

Data Type

String

ssl_server_cert_fingerprint property (AzureRelayReceiver Struct)

The hex-encoded, 16-byte MD5 fingerprint of the certificate.

Syntax

fn ssl_server_cert_fingerprint(&self ) -> Result<String, IPWorksMQError> 

Default Value

""

Remarks

The hex-encoded, 16-byte MD5 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: bc:2a:72:af:fe:58:17:43:7a:5f:ba:5a:7c:90:f7:02

This property is read-only.

Data Type

String

ssl_server_cert_fingerprint_sha1 property (AzureRelayReceiver Struct)

The hex-encoded, 20-byte SHA-1 fingerprint of the certificate.

Syntax

fn ssl_server_cert_fingerprint_sha1(&self ) -> Result<String, IPWorksMQError> 

Default Value

""

Remarks

The hex-encoded, 20-byte SHA-1 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: 30:7b:fa:38:65:83:ff:da:b4:4e:07:3f:17:b8:a4:ed:80:be:ff:84

This property is read-only.

Data Type

String

ssl_server_cert_fingerprint_sha256 property (AzureRelayReceiver Struct)

The hex-encoded, 32-byte SHA-256 fingerprint of the certificate.

Syntax

fn ssl_server_cert_fingerprint_sha256(&self ) -> Result<String, IPWorksMQError> 

Default Value

""

Remarks

The hex-encoded, 32-byte SHA-256 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: 6a:80:5c:33:a9:43:ea:b0:96:12:8a:64:96:30:ef:4a:8a:96:86:ce:f4:c7:be:10:24:8e:2b:60:9e:f3:59:53

This property is read-only.

Data Type

String

ssl_server_cert_issuer property (AzureRelayReceiver Struct)

The issuer of the certificate.

Syntax

fn ssl_server_cert_issuer(&self ) -> Result<String, IPWorksMQError> 

Default Value

""

Remarks

The issuer of the certificate. This property contains a string representation of the name of the issuing authority for the certificate.

This property is read-only.

Data Type

String

ssl_server_cert_private_key property (AzureRelayReceiver Struct)

The private key of the certificate (if available).

Syntax

fn ssl_server_cert_private_key(&self ) -> Result<String, IPWorksMQError> 

Default Value

""

Remarks

The private key of the certificate (if available). The key is provided as PEM/Base64-encoded data.

NOTE: The ssl_server_cert_private_key may be available but not exportable. In this case, ssl_server_cert_private_key returns an empty string.

This property is read-only.

Data Type

String

ssl_server_cert_private_key_available property (AzureRelayReceiver Struct)

Whether a PrivateKey is available for the selected certificate.

Syntax

fn ssl_server_cert_private_key_available(&self ) -> Result<bool, IPWorksMQError> 

Default Value

false

Remarks

Whether a ssl_server_cert_private_key is available for the selected certificate. If ssl_server_cert_private_key_available is True, the certificate may be used for authentication purposes (e.g., server authentication).

This property is read-only.

Data Type

bool

ssl_server_cert_private_key_container property (AzureRelayReceiver Struct)

The name of the PrivateKey container for the certificate (if available).

Syntax

fn ssl_server_cert_private_key_container(&self ) -> Result<String, IPWorksMQError> 

Default Value

""

Remarks

The name of the ssl_server_cert_private_key container for the certificate (if available). This functionality is available only on Windows platforms.

This property is read-only.

Data Type

String

ssl_server_cert_public_key property (AzureRelayReceiver Struct)

The public key of the certificate.

Syntax

fn ssl_server_cert_public_key(&self ) -> Result<String, IPWorksMQError> 

Default Value

""

Remarks

The public key of the certificate. The key is provided as PEM/Base64-encoded data.

This property is read-only.

Data Type

String

ssl_server_cert_public_key_algorithm property (AzureRelayReceiver Struct)

The textual description of the certificate's public key algorithm.

Syntax

fn ssl_server_cert_public_key_algorithm(&self ) -> Result<String, IPWorksMQError> 

Default Value

""

Remarks

The textual description of the certificate's public key algorithm. The property contains either the name of the algorithm (e.g., "RSA" or "RSA_DH") or an object identifier (OID) string representing the algorithm.

This property is read-only.

Data Type

String

ssl_server_cert_public_key_length property (AzureRelayReceiver Struct)

The length of the certificate's public key (in bits).

Syntax

fn ssl_server_cert_public_key_length(&self ) -> Result<i32, IPWorksMQError> 

Default Value

0

Remarks

The length of the certificate's public key (in bits). Common values are 512, 1024, and 2048.

This property is read-only.

Data Type

i32

ssl_server_cert_serial_number property (AzureRelayReceiver Struct)

The serial number of the certificate encoded as a string.

Syntax

fn ssl_server_cert_serial_number(&self ) -> Result<String, IPWorksMQError> 

Default Value

""

Remarks

The serial number of the certificate encoded as a string. The number is encoded as a series of hexadecimal digits, with each pair representing a byte of the serial number.

This property is read-only.

Data Type

String

ssl_server_cert_signature_algorithm property (AzureRelayReceiver Struct)

The text description of the certificate's signature algorithm.

Syntax

fn ssl_server_cert_signature_algorithm(&self ) -> Result<String, IPWorksMQError> 

Default Value

""

Remarks

The text description of the certificate's signature algorithm. The property contains either the name of the algorithm (e.g., "RSA" or "RSA_MD5RSA") or an object identifier (OID) string representing the algorithm.

This property is read-only.

Data Type

String

ssl_server_cert_store property (AzureRelayReceiver Struct)

The name of the certificate store for the client certificate.

Syntax

fn ssl_server_cert_store(&self ) -> Result<Vec<u8>, IPWorksMQError> 

Default Value

"MY"

Remarks

The name of the certificate store for the client certificate.

The ssl_server_cert_store_type property denotes the type of the certificate store specified by ssl_server_cert_store. If the store is password-protected, specify the password in ssl_server_cert_store_password.

ssl_server_cert_store is used in conjunction with the ssl_server_cert_subject property to specify client certificates. If ssl_server_cert_store has a value, and ssl_server_cert_subject or ssl_server_cert_encoded is set, a search for a certificate is initiated. Please see the ssl_server_cert_subject property for details.

Designations of certificate stores are platform dependent.

The following designations are the most common User and Machine certificate stores in Windows:

When the certificate store type is cstPFXFile, this property must be set to the name of the file. When the type is cstPFXBlob, the property must be set to the binary contents of a PFX file (i.e., PKCS#12 certificate store).

This property is read-only.

Data Type

Vec

ssl_server_cert_store_password property (AzureRelayReceiver Struct)

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

Syntax

fn ssl_server_cert_store_password(&self ) -> Result<String, IPWorksMQError> 

Default Value

""

Remarks

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

This property is read-only.

Data Type

String

ssl_server_cert_store_type property (AzureRelayReceiver Struct)

The type of certificate store for this certificate.

Syntax

fn ssl_server_cert_store_type(&self ) -> Result<i32, IPWorksMQError> 

Possible Values

0   // User
1   // Machine
2   // PFXFile
3   // PFXBlob
4   // JKSFile
5   // JKSBlob
6   // PEMKeyFile
7   // PEMKeyBlob
8   // PublicKeyFile
9   // PublicKeyBlob
10   // SSHPublicKeyBlob
11   // P7BFile
12   // P7BBlob
13   // SSHPublicKeyFile
14   // PPKFile
15   // PPKBlob
16   // XMLFile
17   // XMLBlob
18   // JWKFile
19   // JWKBlob
20   // SecurityKey
21   // BCFKSFile
22   // BCFKSBlob
23   // PKCS11
99   // Auto

Default Value

0

Remarks

The type of certificate store for this certificate.

The struct supports both public and private keys in a variety of formats. When the cstAuto value is used, the struct will automatically determine the type. This property can take one of the following values:

This property is read-only.

Data Type

i32

ssl_server_cert_subject_alt_names property (AzureRelayReceiver Struct)

Comma-separated lists of alternative subject names for the certificate.

Syntax

fn ssl_server_cert_subject_alt_names(&self ) -> Result<String, IPWorksMQError> 

Default Value

""

Remarks

Comma-separated lists of alternative subject names for the certificate.

This property is read-only.

Data Type

String

ssl_server_cert_thumbprint_md5 property (AzureRelayReceiver Struct)

The MD5 hash of the certificate.

Syntax

fn ssl_server_cert_thumbprint_md5(&self ) -> Result<String, IPWorksMQError> 

Default Value

""

Remarks

The MD5 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

This property is read-only.

Data Type

String

ssl_server_cert_thumbprint_sha1 property (AzureRelayReceiver Struct)

The SHA-1 hash of the certificate.

Syntax

fn ssl_server_cert_thumbprint_sha1(&self ) -> Result<String, IPWorksMQError> 

Default Value

""

Remarks

The SHA-1 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

This property is read-only.

Data Type

String

ssl_server_cert_thumbprint_sha256 property (AzureRelayReceiver Struct)

The SHA-256 hash of the certificate.

Syntax

fn ssl_server_cert_thumbprint_sha256(&self ) -> Result<String, IPWorksMQError> 

Default Value

""

Remarks

The SHA-256 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

This property is read-only.

Data Type

String

ssl_server_cert_usage property (AzureRelayReceiver Struct)

The text description of UsageFlags .

Syntax

fn ssl_server_cert_usage(&self ) -> Result<String, IPWorksMQError> 

Default Value

""

Remarks

The text description of ssl_server_cert_usage_flags.

This value will be one or more of the following strings and will be separated by commas:

• Digital Signature
• Non-Repudiation
• Key Encipherment
• Data Encipherment
• Key Agreement
• Certificate Signing
• CRL Signing
• Encipher Only

If the provider is OpenSSL, the value is a comma-separated list of X.509 certificate extension names.

This property is read-only.

Data Type

String

ssl_server_cert_usage_flags property (AzureRelayReceiver Struct)

The flags that show intended use for the certificate.

Syntax

fn ssl_server_cert_usage_flags(&self ) -> Result<i32, IPWorksMQError> 

Default Value

0

Remarks

The flags that show intended use for the certificate. The value of ssl_server_cert_usage_flags is a combination of the following flags:

Please see the ssl_server_cert_usage property for a text representation of ssl_server_cert_usage_flags.

This functionality currently is not available when the provider is OpenSSL.

This property is read-only.

Data Type

i32

ssl_server_cert_version property (AzureRelayReceiver Struct)

The certificate's version number.

Syntax

fn ssl_server_cert_version(&self ) -> Result<String, IPWorksMQError> 

Default Value

""

Remarks

The certificate's version number. The possible values are the strings "V1", "V2", and "V3".

This property is read-only.

Data Type

String

ssl_server_cert_subject property (AzureRelayReceiver Struct)

The subject of the certificate used for client authentication.

Syntax

fn ssl_server_cert_subject(&self ) -> Result<String, IPWorksMQError> 

Default Value

""

Remarks

The subject of the certificate used for client authentication.

This property must be set after all other certificate properties are set. When this property is set, a search is performed in the current certificate store to locate a certificate with a matching subject.

If a matching certificate is found, the property is set to the full subject of the matching certificate.

If an exact match is not found, the store is searched for subjects containing the value of the property.

If a match is still not found, the property is set to an empty string, and no certificate is selected.

The special value "*" picks a random certificate in the certificate store.

The certificate subject is a comma-separated list of distinguished name fields and values. For instance, "CN=www.server.com, OU=test, C=US, E=example@email.com". Common fields and their meanings are as follows:

If a field value contains a comma, it must be quoted.

This property is read-only.

Data Type

String

ssl_server_cert_encoded property (AzureRelayReceiver Struct)

The certificate (PEM/Base64 encoded).

Syntax

fn ssl_server_cert_encoded(&self ) -> Result<Vec<u8>, IPWorksMQError> 

Default Value

""

Remarks

The certificate (PEM/Base64 encoded). This property is used to assign a specific certificate. The ssl_server_cert_store and ssl_server_cert_subject properties also may be used to specify a certificate.

When ssl_server_cert_encoded is set, a search is initiated in the current ssl_server_cert_store for the private key of the certificate. If the key is found, ssl_server_cert_subject is updated to reflect the full subject of the selected certificate; otherwise, ssl_server_cert_subject is set to an empty string.

This property is read-only.

Data Type

Vec

config method (AzureRelayReceiver Struct)

Sets or retrieves a configuration setting.

Syntax

fn config(&self, configuration_string : &str) ->  Result<String, IPWorksMQError>

Remarks

config is a generic method available in every struct. It is used to set and retrieve configuration settings for the struct.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the struct, access to these internal properties is provided through the config method.

To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.

disconnect method (AzureRelayReceiver Struct)

This method disconnects the specified client.

Syntax

fn disconnect(&self, connection_id : i32) -> Result<(), IPWorksMQError>

Remarks

Calling this method will disconnect the client specified by the connection_id parameter.

do_events method (AzureRelayReceiver Struct)

This method processes events from the internal message queue.

Syntax

fn do_events(&self) -> Result<(), IPWorksMQError>

Remarks

When do_events is called, the struct processes any available events. If no events are available, it waits for a preset period of time, and then returns.

interrupt method (AzureRelayReceiver Struct)

Interrupts a synchronous send to the remote host.

Syntax

fn interrupt(&self, connection_id : i32) -> Result<(), IPWorksMQError>

Remarks

This property is called using the Connection ID if you wish to interrupt a connection and stop a file from uploading without disconnecting the client connected to the struct. If you use send_file to upload a file, the struct will run synchronously on that Connection ID until it is completed.

pause_data method (AzureRelayReceiver Struct)

This method pauses data reception.

Syntax

fn pause_data(&self, connection_id : i32) -> Result<(), IPWorksMQError>

Remarks

This method pauses data reception for the connection identified by connection_id when called. While data reception is paused, the on_data_in event will not fire for the specified connection. Call process_data to reenable data reception.

process_data method (AzureRelayReceiver Struct)

This method reenables data reception after a call to PauseData .

Syntax

fn process_data(&self, connection_id : i32) -> Result<(), IPWorksMQError>

Remarks

This method reenables data reception for the connection identified by connection_id after a previous call to pause_data. When pause_data is called, the on_data_in event will not fire for the specified connection. To reenable data reception and allow on_data_in to fire, call this method.

NOTE: This method is used only after previously calling pause_data. It does not need to be called to process incoming data by default.

send method (AzureRelayReceiver Struct)

This method sends binary data to the client.

Syntax

fn send(&self, connection_id : i32, data : &[u8]) -> Result<(), IPWorksMQError>

Remarks

This method sends the binary data specified by Data to the client specified by ConnectionId.

send_bytes method (AzureRelayReceiver Struct)

This method sends binary data to the specified client.

Syntax

fn send_bytes(&self, connection_id : i32, data : &[u8]) -> Result<(), IPWorksMQError>

Remarks

This method sends binary data to the client identified by connection_id. To send text, use the send_text method instead.

When azure_relay_connection_timeout is set to 0, the struct will behave asynchronously. If you are sending data to the remote host faster than it can process it, or faster than the network's bandwidth allows, the outgoing queue might fill up. When this happens, the operation fails with error 10035: "[10035] Operation would block" (WSAEWOULDBLOCK). You can check this error, and then try to send the data again. . The bytes_sent property shows how many bytes were sent (if any). If 0 bytes were sent, then you can wait for the on_ready_to_send event before attempting to send data again.

NOTE: The on_ready_to_send event is not fired when part of the data is sent successfully.

This method sends binary data to the client identified by ConnectionId. To send text, use the send_text method instead.

When azure_relay_connection_timeout is set to 0, the struct will behave asynchronously. If you are sending data to the remote host faster than it can process it, or faster than the network's bandwidth allows, the outgoing queue might fill up. When this happens, the operation fails with error 10035: "[10035] Operation would block" (WSAEWOULDBLOCK). You can check this error, and then try to send the data again. . The bytes_sent property shows how many bytes were sent (if any). If 0 bytes were sent, then you can wait for the on_ready_to_send event before attempting to send data again.

NOTE: The on_ready_to_send event is not fired when part of the data is sent successfully.

send_file method (AzureRelayReceiver Struct)

This method sends the file to the remote host.

Syntax

fn send_file(&self, connection_id : i32, file_name : &str) -> Result<(), IPWorksMQError>

Remarks

This method sends the file to the client specified by the connection_id.

send_http_response method (AzureRelayReceiver Struct)

Send the HTTP response.

Syntax

fn send_http_response(&self, connection_id : i32, status_code : i32, status_description : &str, response_data : &[u8]) -> Result<(), IPWorksMQError>

Remarks

This method sends an HTTP response to the HTTP request identified by ConnectionId.

The response status code and description, as well as the response body, are sent to the client using this method. The ConnectionId value should be obtained from the on_http_request event.

StatusCode is the three digit HTTP status code to return, for instance 200.

StatusDescription is the text corresponding to the StatusCode. For instance OK.

ResponseBody specifies the body to be sent back to the client (if any).

Code Example (HTTP)

Azurerelaylistener listener = new Azurerelaylistener(); listener.AccessKey = "9oKRDwjl0s440MlLUi4qHxDL34j1FS6K3t5TRoJ216c="; listener.AccessKeyName = "RootManageSharedAccessKey"; listener.NamespaceAddress = "myrelay.servicebus.windows.net"; listener.HybridConnection = "hc1"; listener.OnHTTPRequest += (s, e) => { Console.WriteLine("HTTP Request from " + e.RemoteAddress + ":" + e.RemotePort); Console.WriteLine("HTTP Method: " + e.RequestMethod); Console.WriteLine("HTTP Request: " + e.RequestData); myConnectionId = e.ConnectionId; }; //Send a response using the ConnectionId value from the HTTPRequest event listener.SendHTTPResponse(myConnectionId, 200, "OK", myResponseBody);

send_text method (AzureRelayReceiver Struct)

This method sends text to the specified client.

Syntax

fn send_text(&self, connection_id : i32, text : &str) -> Result<(), IPWorksMQError>

Remarks

This method sends text to the client identified by connection_id. To send binary data, use the send_bytes method instead.

When azure_relay_connection_timeout is set to 0, the struct will behave asynchronously. If you are sending data to the remote host faster than it can process it, or faster than the network's bandwidth allows, the outgoing queue might fill up. When this happens, the operation fails with error 10035: "[10035] Operation would block" (WSAEWOULDBLOCK). You can check this error, and then try to send the data again. . The bytes_sent property shows how many bytes were sent (if any). If 0 bytes were sent, then you can wait for the on_ready_to_send event before attempting to send data again.

NOTE: The on_ready_to_send event is not fired when part of the data is sent successfully.

This method sends text to the client identified by ConnectionId. Data sent with this method will always be treated as text data regardless of the value of azure_relay_connection_data_format. The struct will UTF-8 encode the supplied text.

This method sends text to the client identified by ConnectionId. To send binary data, use the send_bytes method instead.

When azure_relay_connection_timeout is set to 0, the struct will behave asynchronously. If you are sending data to the remote host faster than it can process it, or faster than the network's bandwidth allows, the outgoing queue might fill up. When this happens, the operation fails with error 10035: "[10035] Operation would block" (WSAEWOULDBLOCK). You can check this error, and then try to send the data again. . The bytes_sent property shows how many bytes were sent (if any). If 0 bytes were sent, then you can wait for the on_ready_to_send event before attempting to send data again.

NOTE: The on_ready_to_send event is not fired when part of the data is sent successfully.

shutdown method (AzureRelayReceiver Struct)

This method shuts down the server.

Syntax

fn shutdown(&self) -> Result<(), IPWorksMQError>

Remarks

This method shuts down the server. Calling this method is equivalent to calling stop_listening and then breaking every client connection by calling disconnect.

start_listening method (AzureRelayReceiver Struct)

Starts listening for incoming connections.

Syntax

fn start_listening(&self) -> Result<(), IPWorksMQError>

Remarks

This method begins listening for incoming connections on the port specified by local_port. Once listening events will fire as new clients connect and data is transferred.

To stop listening for new connections call stop_listening. To stop listening for new connections and disconnect all existing clients call shutdown.

The following properties are applicable when calling this method:

• access_key (required)
• access_key_name (required)
• hybrid_connection (required)
• namespace_address (required)
• default_timeout
• forwarding_host
• forwarding_port

stop_listening method (AzureRelayReceiver Struct)

This method stops listening for new connections.

Syntax

fn stop_listening(&self) -> Result<(), IPWorksMQError>

Remarks

This method stops listening for new connections. After being called, any new connection attempts will be rejected. Calling this method does not disconnect existing connections.

To stop listening and to disconnect all existing clients, call shutdown instead.

This method stops listening for new connections. After being called, any new connection attempts will be rejected. Calling this method does not disconnect existing connections.

To stop listening and to disconnect all existing clients, call shutdown instead.

on_connected event (AzureRelayReceiver Struct)

This event is fired immediately after the WebSocket handshake completes (or fails).

Syntax

// AzureRelayReceiverConnectedEventArgs carries the AzureRelayReceiver Connected event's parameters.
pub struct AzureRelayReceiverConnectedEventArgs {
  fn status_code(&self) -> i32
  fn description(&self) -> &String
}

// AzureRelayReceiverConnectedEvent defines the signature of the AzureRelayReceiver Connected event's handler function.
pub trait AzureRelayReceiverConnectedEvent {
  fn on_connected(&self, sender : AzureRelayReceiver, e : &mut AzureRelayReceiverConnectedEventArgs);
}

impl <'a> AzureRelayReceiver<'a> {
  pub fn on_connected(&self) -> &'a dyn AzureRelayReceiverConnectedEvent;
  pub fn set_on_connected(&mut self, value : &'a dyn AzureRelayReceiverConnectedEvent);
  ...
}

Remarks

The on_connected event will fire after the entire WebSocket connection and handshake process finishes (or fails). This consists of three steps: (1) the initial TCP connection (along with SSL negotiation, if used), (2) the HTTP "Upgrade" request, and (3) the 101 HTTP response.

If the connection is made normally, status_code is 0 and description is "OK".

If the connection fails, status_code has the error code returned by the TCP/IP stack. description contains a description of this code. The value of status_code is equal to the value of the error.

NOTE: Please refer to the Error Codes section for more information.

on_connection_connected event (AzureRelayReceiver Struct)

Fired when a client has connected.

Syntax

// AzureRelayReceiverConnectionConnectedEventArgs carries the AzureRelayReceiver ConnectionConnected event's parameters.
pub struct AzureRelayReceiverConnectionConnectedEventArgs {
  fn connection_id(&self) -> i32
}

// AzureRelayReceiverConnectionConnectedEvent defines the signature of the AzureRelayReceiver ConnectionConnected event's handler function.
pub trait AzureRelayReceiverConnectionConnectedEvent {
  fn on_connection_connected(&self, sender : AzureRelayReceiver, e : &mut AzureRelayReceiverConnectionConnectedEventArgs);
}

impl <'a> AzureRelayReceiver<'a> {
  pub fn on_connection_connected(&self) -> &'a dyn AzureRelayReceiverConnectionConnectedEvent;
  pub fn set_on_connection_connected(&mut self, value : &'a dyn AzureRelayReceiverConnectionConnectedEvent);
  ...
}

Remarks

This event fires when a client has successfully established a WebSocket connection.

ConnectionId identifies the connection.

on_connection_data_in event (AzureRelayReceiver Struct)

Fired when data is received.

Syntax

// AzureRelayReceiverConnectionDataInEventArgs carries the AzureRelayReceiver ConnectionDataIn event's parameters.
pub struct AzureRelayReceiverConnectionDataInEventArgs {
  fn connection_id(&self) -> i32
  fn data_format(&self) -> i32
  fn text(&self) -> &[u8]
  fn eom(&self) -> bool
}

// AzureRelayReceiverConnectionDataInEvent defines the signature of the AzureRelayReceiver ConnectionDataIn event's handler function.
pub trait AzureRelayReceiverConnectionDataInEvent {
  fn on_connection_data_in(&self, sender : AzureRelayReceiver, e : &mut AzureRelayReceiverConnectionDataInEventArgs);
}

impl <'a> AzureRelayReceiver<'a> {
  pub fn on_connection_data_in(&self) -> &'a dyn AzureRelayReceiverConnectionDataInEvent;
  pub fn set_on_connection_data_in(&mut self, value : &'a dyn AzureRelayReceiverConnectionDataInEvent);
  ...
}

Remarks

The on_data_in event provides the data received from the client identified by the ConnectionId parameter.

The incoming data are provided through the Text parameter.

The DataFormat parameter identifies the encoding (if any) of the data. Possible value are as follows:

The EOM parameter stands for End of Message. By default, the struct will fire the on_data_in event as data are received. Larger messages will be fragmented and will cause the event to fire multiple times. When EOM is True within the event, this indicates the current fragment is also the final fragment of the message. The struct may also be configured to buffer the message internally until the complete message is received. To enable this, set BufferMessage to True.

The EOL parameter stands for End of Line. When line_mode is False, EOL will always be False. When line_mode is True, EOL will be True if the on_data_in event fired because an EOL was received and will be False if the on_data_in event fired because MaxLineLength was reached.

on_connection_disconnected event (AzureRelayReceiver Struct)

Fired when a WebSocket connection is disconnected.

Syntax

// AzureRelayReceiverConnectionDisconnectedEventArgs carries the AzureRelayReceiver ConnectionDisconnected event's parameters.
pub struct AzureRelayReceiverConnectionDisconnectedEventArgs {
  fn connection_id(&self) -> i32
  fn status_code(&self) -> i32
  fn description(&self) -> &String
}

// AzureRelayReceiverConnectionDisconnectedEvent defines the signature of the AzureRelayReceiver ConnectionDisconnected event's handler function.
pub trait AzureRelayReceiverConnectionDisconnectedEvent {
  fn on_connection_disconnected(&self, sender : AzureRelayReceiver, e : &mut AzureRelayReceiverConnectionDisconnectedEventArgs);
}

impl <'a> AzureRelayReceiver<'a> {
  pub fn on_connection_disconnected(&self) -> &'a dyn AzureRelayReceiverConnectionDisconnectedEvent;
  pub fn set_on_connection_disconnected(&mut self, value : &'a dyn AzureRelayReceiverConnectionDisconnectedEvent);
  ...
}

Remarks

When the connection is closed the StatusCode parameter may be used to determine if the disconnect occurred normally or if there was an error condition. If the connection is closed normally the StatusCode will be 1000. The Description parameter will contain a textual description returned by the server. Common StatusCode values are:

on_connection_error event (AzureRelayReceiver Struct)

Information about errors during data delivery.

Syntax

// AzureRelayReceiverConnectionErrorEventArgs carries the AzureRelayReceiver ConnectionError event's parameters.
pub struct AzureRelayReceiverConnectionErrorEventArgs {
  fn connection_id(&self) -> i32
  fn error_code(&self) -> i32
  fn description(&self) -> &String
}

// AzureRelayReceiverConnectionErrorEvent defines the signature of the AzureRelayReceiver ConnectionError event's handler function.
pub trait AzureRelayReceiverConnectionErrorEvent {
  fn on_connection_error(&self, sender : AzureRelayReceiver, e : &mut AzureRelayReceiverConnectionErrorEventArgs);
}

impl <'a> AzureRelayReceiver<'a> {
  pub fn on_connection_error(&self) -> &'a dyn AzureRelayReceiverConnectionErrorEvent;
  pub fn set_on_connection_error(&mut self, value : &'a dyn AzureRelayReceiverConnectionErrorEvent);
  ...
}

Remarks

The on_error event is fired in case of exceptional conditions during message processing. Normally the struct fails with an error.

ConnectionId contains an error code and Description contains a textual description of the error. For a list of valid error codes and their descriptions, please refer to the Error Codes section.

ErrorCode contains an error code and Description contains a textual description of the error. For a list of valid error codes and their descriptions, please refer to the Error Codes section.

on_connection_ready_to_send event (AzureRelayReceiver Struct)

Fired when the struct is ready to send data.

Syntax

// AzureRelayReceiverConnectionReadyToSendEventArgs carries the AzureRelayReceiver ConnectionReadyToSend event's parameters.
pub struct AzureRelayReceiverConnectionReadyToSendEventArgs {
  fn connection_id(&self) -> i32
}

// AzureRelayReceiverConnectionReadyToSendEvent defines the signature of the AzureRelayReceiver ConnectionReadyToSend event's handler function.
pub trait AzureRelayReceiverConnectionReadyToSendEvent {
  fn on_connection_ready_to_send(&self, sender : AzureRelayReceiver, e : &mut AzureRelayReceiverConnectionReadyToSendEventArgs);
}

impl <'a> AzureRelayReceiver<'a> {
  pub fn on_connection_ready_to_send(&self) -> &'a dyn AzureRelayReceiverConnectionReadyToSendEvent;
  pub fn set_on_connection_ready_to_send(&mut self, value : &'a dyn AzureRelayReceiverConnectionReadyToSendEvent);
  ...
}

Remarks

The on_ready_to_send event indicates that the underlying TCP/IP subsystem is ready to accept data after a failed send. The event is also fired immediately after a connection is established.

on_connection_request event (AzureRelayReceiver Struct)

Fires when a WebSocket connection is requested.

Syntax

// AzureRelayReceiverConnectionRequestEventArgs carries the AzureRelayReceiver ConnectionRequest event's parameters.
pub struct AzureRelayReceiverConnectionRequestEventArgs {
  fn accept(&self) -> bool
  fn set_accept(&self, value : bool)
  fn rendezvous_address(&self) -> &String
  fn id(&self) -> &String
  fn connect_headers(&self) -> &String
  fn sub_protocols(&self) -> &String
  fn extensions(&self) -> &String
  fn host(&self) -> &String
  fn remote_address(&self) -> &String
  fn remote_port(&self) -> i32
  fn status_code(&self) -> i32
  fn set_status_code(&self, value : i32)
  fn status_description(&self) -> &String
  fn set_status_description(&self, value : &str)
  fn set_status_description_ref(&self, value : &String)
}

// AzureRelayReceiverConnectionRequestEvent defines the signature of the AzureRelayReceiver ConnectionRequest event's handler function.
pub trait AzureRelayReceiverConnectionRequestEvent {
  fn on_connection_request(&self, sender : AzureRelayReceiver, e : &mut AzureRelayReceiverConnectionRequestEventArgs);
}

impl <'a> AzureRelayReceiver<'a> {
  pub fn on_connection_request(&self) -> &'a dyn AzureRelayReceiverConnectionRequestEvent;
  pub fn set_on_connection_request(&mut self, value : &'a dyn AzureRelayReceiverConnectionRequestEvent);
  ...
}

Remarks

This event fires when a client requests a connection. The parameters of this event may be used to determine whether to accept or reject the connection.

To accept a connection set Accept to True (default). To reject a connection set Accept to False and set StatusCode and StatusDescription.

Accept defines whether the connection request is accepted or rejected. The default value is True. Set this to False to reject the connection.

RendezvousAddress holds the rendezvous URL to which the connection specific websocket connection will be made. This is informational only.

Id holds the Id of the connection. If an Id was specified by the client it is present here, otherwise the Azure Relay Service generates a value. For instance: b3ac97ea-d0f0-4286-bf1d-d493a4a22c27_G23_G22.

ConnectHeaders contains a JSON object with the HTTP headers that have been supplied by the sender to the Azure Relay service. For instance:

"connectHeaders": {
	"Sec-WebSocket-Key": "wIdDlRBg\/J\/Hx12q6iFdUQ==",
	"Sec-WebSocket-Version": "13",
	"Origin": "null",
	"Connection": "Upgrade",
	"Upgrade": "websocket",
	"Accept-Encoding": "gzip, deflate",
	"Host": "nstest.servicebus.windows.net",
	"User-Agent": "IPWorks HTTP Component - www.nsoftware.com"
}

SubProtocols holds the subprotocols (application-level protocols layered over the WebSocket Protocol) sent by the client in the initial WebSocket connection request.

Extensions holds the WebSocket extensions sent by the client in the initial WebSocket connection request.

Host is the Host header value of the connected client.

RemoteAddress is the IP address of the connecting client.

RemotePort is the port used by the connecting client.

StatusCode is a 3 digit HTTP status code used when Accept is set to False. Set this to any 3 digit HTTP status code when rejecting a connection. For instance: 404.

StatusDescription should be set to the text description corresponding to the StatusCode value when rejecting a connection. For instance: Not Found.

on_connection_status event (AzureRelayReceiver Struct)

This event is fired to indicate changes in connection state.

Syntax

// AzureRelayReceiverConnectionStatusEventArgs carries the AzureRelayReceiver ConnectionStatus event's parameters.
pub struct AzureRelayReceiverConnectionStatusEventArgs {
  fn connection_event(&self) -> &String
  fn status_code(&self) -> i32
  fn description(&self) -> &String
}

// AzureRelayReceiverConnectionStatusEvent defines the signature of the AzureRelayReceiver ConnectionStatus event's handler function.
pub trait AzureRelayReceiverConnectionStatusEvent {
  fn on_connection_status(&self, sender : AzureRelayReceiver, e : &mut AzureRelayReceiverConnectionStatusEventArgs);
}

impl <'a> AzureRelayReceiver<'a> {
  pub fn on_connection_status(&self) -> &'a dyn AzureRelayReceiverConnectionStatusEvent;
  pub fn set_on_connection_status(&mut self, value : &'a dyn AzureRelayReceiverConnectionStatusEvent);
  ...
}

Remarks

The on_connection_status event is fired when the connection state changes, such as completion of a firewall or proxy connection or completion of a security handshake.

The connection_event parameter indicates the type of connection event. Values may include the following:

on_disconnected event (AzureRelayReceiver Struct)

Fired when a connection is closed.

Syntax

// AzureRelayReceiverDisconnectedEventArgs carries the AzureRelayReceiver Disconnected event's parameters.
pub struct AzureRelayReceiverDisconnectedEventArgs {
  fn status_code(&self) -> i32
  fn description(&self) -> &String
}

// AzureRelayReceiverDisconnectedEvent defines the signature of the AzureRelayReceiver Disconnected event's handler function.
pub trait AzureRelayReceiverDisconnectedEvent {
  fn on_disconnected(&self, sender : AzureRelayReceiver, e : &mut AzureRelayReceiverDisconnectedEventArgs);
}

impl <'a> AzureRelayReceiver<'a> {
  pub fn on_disconnected(&self) -> &'a dyn AzureRelayReceiverDisconnectedEvent;
  pub fn set_on_disconnected(&mut self, value : &'a dyn AzureRelayReceiverDisconnectedEvent);
  ...
}

Remarks

If the connection is broken normally, status_code is 0 and description is "OK".

If the connection is broken for any other reason, status_code has the error code returned by the Transmission Control Protocol (TCP/IP) subsystem. description contains a description of this code. The value of status_code is equal to the value of the TCP/IP error.

Please refer to the Error Codes section for more information.

on_error event (AzureRelayReceiver Struct)

Fired when information is available about errors during data delivery.

Syntax

// AzureRelayReceiverErrorEventArgs carries the AzureRelayReceiver Error event's parameters.
pub struct AzureRelayReceiverErrorEventArgs {
  fn error_code(&self) -> i32
  fn description(&self) -> &String
}

// AzureRelayReceiverErrorEvent defines the signature of the AzureRelayReceiver Error event's handler function.
pub trait AzureRelayReceiverErrorEvent {
  fn on_error(&self, sender : AzureRelayReceiver, e : &mut AzureRelayReceiverErrorEventArgs);
}

impl <'a> AzureRelayReceiver<'a> {
  pub fn on_error(&self) -> &'a dyn AzureRelayReceiverErrorEvent;
  pub fn set_on_error(&mut self, value : &'a dyn AzureRelayReceiverErrorEvent);
  ...
}

Remarks

The on_error event is fired in case of exceptional conditions during message processing. Normally the struct fails with an error.

The error_code parameter contains an error code, and the description parameter contains a textual description of the error. For a list of valid error codes and their descriptions, please refer to the Error Codes section.

on_header event (AzureRelayReceiver Struct)

Fired every time a header line comes in.

Syntax

// AzureRelayReceiverHeaderEventArgs carries the AzureRelayReceiver Header event's parameters.
pub struct AzureRelayReceiverHeaderEventArgs {
  fn field(&self) -> &String
  fn value(&self) -> &String
}

// AzureRelayReceiverHeaderEvent defines the signature of the AzureRelayReceiver Header event's handler function.
pub trait AzureRelayReceiverHeaderEvent {
  fn on_header(&self, sender : AzureRelayReceiver, e : &mut AzureRelayReceiverHeaderEventArgs);
}

impl <'a> AzureRelayReceiver<'a> {
  pub fn on_header(&self) -> &'a dyn AzureRelayReceiverHeaderEvent;
  pub fn set_on_header(&mut self, value : &'a dyn AzureRelayReceiverHeaderEvent);
  ...
}

Remarks

The field parameter contains the name of the HTTP header (which is the same as it is delivered). The value parameter contains the header contents.

If the header line being retrieved is a continuation header line, then the field parameter contains "" (empty string).

on_http_request event (AzureRelayReceiver Struct)

Fires when an HTTP request is received.

Syntax

// AzureRelayReceiverHTTPRequestEventArgs carries the AzureRelayReceiver HTTPRequest event's parameters.
pub struct AzureRelayReceiverHTTPRequestEventArgs {
  fn connection_id(&self) -> i32
  fn rendezvous_address(&self) -> &String
  fn id(&self) -> &String
  fn request_headers(&self) -> &String
  fn request_target(&self) -> &String
  fn request_method(&self) -> &String
  fn host(&self) -> &String
  fn remote_address(&self) -> &String
  fn remote_port(&self) -> i32
  fn request_data(&self) -> &[u8]
}

// AzureRelayReceiverHTTPRequestEvent defines the signature of the AzureRelayReceiver HTTPRequest event's handler function.
pub trait AzureRelayReceiverHTTPRequestEvent {
  fn on_http_request(&self, sender : AzureRelayReceiver, e : &mut AzureRelayReceiverHTTPRequestEventArgs);
}

impl <'a> AzureRelayReceiver<'a> {
  pub fn on_http_request(&self) -> &'a dyn AzureRelayReceiverHTTPRequestEvent;
  pub fn set_on_http_request(&mut self, value : &'a dyn AzureRelayReceiverHTTPRequestEvent);
  ...
}

Remarks

This event fires when an HTTP request is received. The parameters of this event describe the details of the HTTP request.

The ConnectionId value must be saved and used when calling send_http_response.

Parameter Descriptions

ConnectionId contains an identifier generated by the struct to identify each connection. This identifier is unique to this connection.

RendezvousAddress holds the rendezvous URL to which the connection specific websocket connection may be made. This is for information only, no action needs to be taken based on this value. For instance: wss://g2-prod-by3-003-sb.servicebus.windows.net/$hc/hc1?sb-hc-action=request&sb-hc-id=e1df5efe-0988-450c-9512-f9f1d91b39a0_G2

Id holds the Id of the connection. If an Id was specified by the client it is present here, otherwise the Azure Relay service generates a value. For instance: 2d4acb89-7d15-4aeb-bcd5-66e031580a90_G21_G1.

RequestHeaders contains a JSON object containing the HTTP headers supplied to the Azure Relay service by the sender. Note that authorization values used to authenticate to the Azure Relay service, as well as all headers defined in RFC 7230 with the exception of Via are also stripped. For instance headers such as Content-Length are stripped by the relay and are not present in this value. For instance:

"requestHeaders": {
	"Accept-Encoding": "gzip, deflate",
	"Host": "nstest.servicebus.windows.net",
	"User-Agent": "IPWorks HTTP Component - www.nsoftware.com",
	"Via": "1.1 nstest.servicebus.windows.net"
}

RequestTarget is the request target including query string params, as defined in RFC 7230 section 5.3. For instance /hc1.

RequestMethod contains HTTP method sent in the request. For instance POST or GET.

Host holds the Host header value of the connected client.

RemoteHost contains the IP address of the remote host that initiated the HTTP request (the client).

RemotePort contains the port used by the remote host to establish the connection.

RequestData holds the body of the HTTP request (if any).

on_log event (AzureRelayReceiver Struct)

This event fires once for each log message.

Syntax

// AzureRelayReceiverLogEventArgs carries the AzureRelayReceiver Log event's parameters.
pub struct AzureRelayReceiverLogEventArgs {
  fn connection_id(&self) -> i32
  fn log_level(&self) -> i32
  fn message(&self) -> &String
  fn log_type(&self) -> &String
}

// AzureRelayReceiverLogEvent defines the signature of the AzureRelayReceiver Log event's handler function.
pub trait AzureRelayReceiverLogEvent {
  fn on_log(&self, sender : AzureRelayReceiver, e : &mut AzureRelayReceiverLogEventArgs);
}

impl <'a> AzureRelayReceiver<'a> {
  pub fn on_log(&self) -> &'a dyn AzureRelayReceiverLogEvent;
  pub fn set_on_log(&mut self, value : &'a dyn AzureRelayReceiverLogEvent);
  ...
}

Remarks

This event fires once for each log message generated by the struct. The verbosity is controlled by the LogLevel setting.

LogLevel indicates the level of message. Possible values are as follows:

The value 1 (Info) logs basic information including the URL, HTTP version, and connection status details.

The value 2 (Verbose) logs additional information about the initial HTTP request.

The value 3 (Debug) logs additional debug information (if available).

Message is the log entry.

LogType identifies the type of log entry. Possible values are as follows:

• "Info"
• "Error"
• "Verbose"
• "Debug"

on_redirect event (AzureRelayReceiver Struct)

Fired when a redirection is received from the server.

Syntax

// AzureRelayReceiverRedirectEventArgs carries the AzureRelayReceiver Redirect event's parameters.
pub struct AzureRelayReceiverRedirectEventArgs {
  fn location(&self) -> &String
  fn accept(&self) -> bool
  fn set_accept(&self, value : bool)
}

// AzureRelayReceiverRedirectEvent defines the signature of the AzureRelayReceiver Redirect event's handler function.
pub trait AzureRelayReceiverRedirectEvent {
  fn on_redirect(&self, sender : AzureRelayReceiver, e : &mut AzureRelayReceiverRedirectEventArgs);
}

impl <'a> AzureRelayReceiver<'a> {
  pub fn on_redirect(&self) -> &'a dyn AzureRelayReceiverRedirectEvent;
  pub fn set_on_redirect(&mut self, value : &'a dyn AzureRelayReceiverRedirectEvent);
  ...
}

Remarks

This event is fired in cases in which the client can decide whether or not to continue with the redirection process. The accept parameter is always True by default, but if you do not want to follow the redirection, accept may be set to False, in which case the struct fails with an error. location is the location to which the client is being redirected. Further control over redirection is provided in the follow_redirects property.

on_ssl_server_authentication event (AzureRelayReceiver Struct)

Fired after the server presents its certificate to the client.

Syntax

// AzureRelayReceiverSSLServerAuthenticationEventArgs carries the AzureRelayReceiver SSLServerAuthentication event's parameters.
pub struct AzureRelayReceiverSSLServerAuthenticationEventArgs {
  fn cert_encoded(&self) -> &[u8]
  fn cert_subject(&self) -> &String
  fn cert_issuer(&self) -> &String
  fn status(&self) -> &String
  fn accept(&self) -> bool
  fn set_accept(&self, value : bool)
}

// AzureRelayReceiverSSLServerAuthenticationEvent defines the signature of the AzureRelayReceiver SSLServerAuthentication event's handler function.
pub trait AzureRelayReceiverSSLServerAuthenticationEvent {
  fn on_ssl_server_authentication(&self, sender : AzureRelayReceiver, e : &mut AzureRelayReceiverSSLServerAuthenticationEventArgs);
}

impl <'a> AzureRelayReceiver<'a> {
  pub fn on_ssl_server_authentication(&self) -> &'a dyn AzureRelayReceiverSSLServerAuthenticationEvent;
  pub fn set_on_ssl_server_authentication(&mut self, value : &'a dyn AzureRelayReceiverSSLServerAuthenticationEvent);
  ...
}

Remarks

During this event, the client can decide whether or not to continue with the connection process. The accept parameter is a recommendation on whether to continue or close the connection. This is just a suggestion: application software must use its own logic to determine whether or not to continue.

When accept is False, status shows why the verification failed (otherwise, status contains the string OK). If it is decided to continue, you can override and accept the certificate by setting the accept parameter to True.

on_ssl_status event (AzureRelayReceiver Struct)

Fired when secure connection progress messages are available.

Syntax

// AzureRelayReceiverSSLStatusEventArgs carries the AzureRelayReceiver SSLStatus event's parameters.
pub struct AzureRelayReceiverSSLStatusEventArgs {
  fn message(&self) -> &String
}

// AzureRelayReceiverSSLStatusEvent defines the signature of the AzureRelayReceiver SSLStatus event's handler function.
pub trait AzureRelayReceiverSSLStatusEvent {
  fn on_ssl_status(&self, sender : AzureRelayReceiver, e : &mut AzureRelayReceiverSSLStatusEventArgs);
}

impl <'a> AzureRelayReceiver<'a> {
  pub fn on_ssl_status(&self) -> &'a dyn AzureRelayReceiverSSLStatusEvent;
  pub fn set_on_ssl_status(&mut self, value : &'a dyn AzureRelayReceiverSSLStatusEvent);
  ...
}

Remarks

The event is fired for informational and logging purposes only. This event tracks the progress of the connection.

Config Settings (AzureRelayReceiver Struct)

AzureRelayReceiver Config Settings

WebSocketServer Config Settings

TCPServer Config Settings

SSL Config Settings

-----BEGIN CERTIFICATE-----
MIIEKzCCAxOgAwIBAgIRANTET4LIkxdH6P+CFIiHvTowDQYJKoZIhvcNAQELBQAw
... Intermediate Cert ...
eWHV5OW1K53o/atv59sOiW5K3crjFhsBOd5Q+cJJnU+SWinPKtANXMht+EDvYY2w
F0I1XhM+pKj7FjDr+XNj
-----END CERTIFICATE-----
\r \n
-----BEGIN CERTIFICATE-----
MIIEFjCCAv6gAwIBAgIQetu1SMxpnENAnnOz1P+PtTANBgkqhkiG9w0BAQUFADBp
... Root Cert ...
d8q23djXZbVYiIfE9ebr4g3152BlVCHZ2GyPdjhIuLeH21VbT/dyEHHA
-----END CERTIFICATE-----

-----BEGIN CERTIFICATE-----
MIIEKzCCAxOgAwIBAgIRANTET4LIkxdH6P+CFIiHvTowDQYJKoZIhvcNAQELBQAw
... Intermediate Cert ...
eWHV5OW1K53o/atv59sOiW5K3crjFhsBOd5Q+cJJnU+SWinPKtANXMht+EDvYY2w
F0I1XhM+pKj7FjDr+XNj
-----END CERTIFICATE-----
\r \n
-----BEGIN CERTIFICATE-----
MIIEFjCCAv6gAwIBAgIQetu1SMxpnENAnnOz1P+PtTANBgkqhkiG9w0BAQUFADBp
... Root Cert ...
d8q23djXZbVYiIfE9ebr4g3152BlVCHZ2GyPdjhIuLeH21VbT/dyEHHA
-----END CERTIFICATE-----

-----BEGIN CERTIFICATE-----
MIIEKzCCAxOgAwIBAgIRANTET4LIkxdH6P+CFIiHvTowDQYJKoZIhvcNAQELBQAw
... Intermediate Cert...
eWHV5OW1K53o/atv59sOiW5K3crjFhsBOd5Q+cJJnU+SWinPKtANXMht+EDvYY2w
F0I1XhM+pKj7FjDr+XNj
-----END CERTIFICATE-----
\r \n
-----BEGIN CERTIFICATE-----
MIIEFjCCAv6gAwIBAgIQetu1SMxpnENAnnOz1P+PtTANBgkqhkiG9w0BAQUFADBp
... Root Cert...
d8q23djXZbVYiIfE9ebr4g3152BlVCHZ2GyPdjhIuLeH21VbT/dyEHHA
-----END CERTIFICATE-----

Trappable Errors (AzureRelayReceiver Struct)

WebSocketServer Errors

TCPServer Errors

SSL Errors

TCP/IP Errors