AzureRelayProxy Class

Properties Methods Events Config Settings Errors

Allows local connections to be proxied to the Azure Relay Service.

Syntax

AzureRelayProxy

Remarks

The AzureRelayProxy class is designed to listen locally and forward received data over a connection to the Azure Relay Service.

This allows any TCP-based client to connect and send data to Azure Relay Service without any additional knowledge. When listening and a client connects a corresponding connection is made to the specified NamespaceAddress and data then flows freely between the connected client and the Azure Relay Service. Each new connection made to AzureRelayProxy results in a new connection made to the Azure Relay Service. Connections are not shared between clients.

The diagram below illustrates the design of this class.

                          +---------+                       +----------+
Client A <---- TCP ----> |  Azure  | <==== WebSocket ====> |  Azure   |
Client B <---- TCP ----> |  Relay  | <==== WebSocket ====> |  Relay   |
Client C <---- TCP ----> |  Proxy  | <==== WebSocket ====> |  Service |
                          +---------+                       +----------+

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 class will begin listening for incoming connection. When a connection is made a corresponding connection is made to the Azure Relay Service. The following properties are required when setting Listening:

AccessKey (required)
AccessKeyName (required)
HybridConnection (required)
NamespaceAddress (required)

To use SSL for incoming connections set SSLCert to a valid certificate with private key and set SSLEnabled to True before setting Listening.

DoEvents should be called in a loop to ensure timely processing of all activity, including connection requests and data transfer.

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

Handling Connections

When a connection is made the ConnectionRequest 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 Connected event fire when the connection completes and is ready to send and receive data.

Data will be proxied between the connected client and the Azure Relay Service. No special steps are required.

When the client disconnects the Disconnected event fires. To initiate the client disconnection call Disconnect.

Property List

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


AccessKey	The Shared Access Key.
AccessKeyName	The Shared Access Key Name.
ConnectionBacklog	This property includes the maximum number of pending connections maintained by the Transmission Control Protocol (TCP)/IP subsystem.
Connections	A collection of currently connected clients.
DefaultIdleTimeout	This property includes the default idle timeout for inactive clients.
DefaultTimeout	This property includes an initial timeout value to be used by incoming connections.
HybridConnection	The hybrid connection name.
KeepAlive	When True, KEEPALIVE packets are enabled (for long connections).
Linger	When set to True, connections are terminated gracefully.
Listening	This property indicates whether the class is listening for incoming connections on LocalPort.
LocalHost	The name of the local host or user-assigned IP interface through which connections are initiated or accepted.
LocalPort	This property includes the Transmission Control Protocol (TCP) port in the local host where the class listens.
NamespaceAddress	The namespace address of the relay.
SSLAuthenticateClients	If set to True, the server asks the client(s) for a certificate.
SSLCert	The certificate to be used during Secure Sockets Layer (SSL) negotiation.
SSLEnabled	This property indicates whether Transport Layer Security/Secure Sockets Layer (TLS/SSL) is enabled.
SSLStartMode	This property determines how the class starts the Secure Sockets Layer (SSL) negotiation.

Method List

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


Config	Sets or retrieves a configuration setting.
Disconnect	This method disconnects the specified client.
DoEvents	This method processes events from the internal message queue.
Reset	This method will reset the class.
Shutdown	This method shuts down the server.
StartListening	This method starts listening for incoming connections.
StopListening	This method stops listening for new connections.

Event List

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


Connected	This event is fired immediately after a connection completes (or fails).
ConnectionRequest	This event is fired when a request for connection comes from a remote host.
Disconnected	This event is fired when a connection is closed.
Error	This event fires information about errors during data delivery.
Log	This event fires once for each log message.
SSLClientAuthentication	This event is fired when the client presents its credentials to the server.
SSLConnectionRequest	This event fires when a Secure Sockets Layer (SSL) connection is requested.
SSLStatus	This event is fired to show the progress of the secure connection.

Config Settings

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


AccessToken	Returns an access token for use outside of the classes.
LogLevel	The level of detail that is logged.
TokenValidity	The validity time in seconds of the access token.
AcceptEncoding	Used to tell the server which types of content encodings the client supports.
AllowHTTPCompression	This property enables HTTP compression for receiving data.
AllowHTTPFallback	Whether HTTP/2 connections are permitted to fallback to HTTP/1.1.
Append	Whether to append data to LocalFile.
Authorization	The Authorization string to be sent to the server.
BytesTransferred	Contains the number of bytes transferred in the response data.
ChunkSize	Specifies the chunk size in bytes when using chunked encoding.
CompressHTTPRequest	Set to true to compress the body of a PUT or POST request.
EncodeURL	If set to True the URL will be encoded by the class.
FollowRedirects	Determines what happens when the server issues a redirect.
GetOn302Redirect	If set to True the class will perform a GET on the new location.
HTTP2HeadersWithoutIndexing	HTTP2 headers that should not update the dynamic header table with incremental indexing.
HTTPVersion	The version of HTTP used by the class.
IfModifiedSince	A date determining the maximum age of the desired document.
KeepAlive	Determines whether the HTTP connection is closed after completion of the request.
KerberosSPN	The Service Principal Name for the Kerberos Domain Controller.
LogLevel	The level of detail that is logged.
MaxRedirectAttempts	Limits the number of redirects that are followed in a request.
NegotiatedHTTPVersion	The negotiated HTTP version.
OtherHeaders	Other headers as determined by the user (optional).
ProxyAuthorization	The authorization string to be sent to the proxy server.
ProxyAuthScheme	The authorization scheme to be used for the proxy.
ProxyPassword	A password if authentication is to be used for the proxy.
ProxyPort	Port for the proxy server (default 80).
ProxyServer	Name or IP address of a proxy server (optional).
ProxyUser	A user name if authentication is to be used for the proxy.
SentHeaders	The full set of headers as sent by the client.
StatusCode	The status code of the last response from the server.
StatusLine	The first line of the last response from the server.
TransferredData	The contents of the last response from the server.
TransferredDataLimit	The maximum number of incoming bytes to be stored by the class.
TransferredHeaders	The full set of headers as received from the server.
TransferredRequest	The full request as sent by the client.
UseChunkedEncoding	Enables or Disables HTTP chunked encoding for transfers.
UseIDNs	Whether to encode hostnames to internationalized domain names.
UsePlatformHTTPClient	Whether or not to use the platform HTTP client.
UseProxyAutoConfigURL	Whether to use a Proxy auto-config file when attempting a connection.
UserAgent	Information about the user agent (browser).
ConnectionTimeout	Sets a separate timeout value for establishing a connection.
FirewallAutoDetect	Tells the class whether or not to automatically detect and use firewall system settings, if available.
FirewallHost	Name or IP address of firewall (optional).
FirewallPassword	Password to be used if authentication is to be used when connecting through the firewall.
FirewallPort	The TCP port for the FirewallHost;.
FirewallType	Determines the type of firewall to connect through.
FirewallUser	A user name if authentication is to be used connecting through a firewall.
KeepAliveInterval	The retry interval, in milliseconds, to be used when a TCP keep-alive packet is sent and no response is received.
KeepAliveRetryCount	The number of keep-alive packets to be sent before the remotehost is considered disconnected.
KeepAliveTime	The inactivity time in milliseconds before a TCP keep-alive packet is sent.
Linger	When set to True, connections are terminated gracefully.
LingerTime	Time in seconds to have the connection linger.
LocalHost	The name of the local host through which connections are initiated or accepted.
LocalPort	The port in the local host where the class binds.
MaxLineLength	The maximum amount of data to accumulate when no EOL is found.
MaxTransferRate	The transfer rate limit in bytes per second.
ProxyExceptionsList	A semicolon separated list of hosts and IPs to bypass when using a proxy.
TCPKeepAlive	Determines whether or not the keep alive socket option is enabled.
TcpNoDelay	Whether or not to delay when sending packets.
UseIPv6	Whether to use IPv6.
LogSSLPackets	Controls whether SSL packets are logged when using the internal security API.
OpenSSLCADir	The path to a directory containing CA certificates.
OpenSSLCAFile	Name of the file containing the list of CA's trusted by your application.
OpenSSLCipherList	A string that controls the ciphers to be used by SSL.
OpenSSLPrngSeedData	The data to seed the pseudo random number generator (PRNG).
ReuseSSLSession	Determines if the SSL session is reused.
SSLCACertFilePaths	The paths to CA certificate files on Unix/Linux.
SSLCACerts	A newline separated list of CA certificates to be included when performing an SSL handshake.
SSLCipherStrength	The minimum cipher strength used for bulk encryption.
SSLClientCACerts	A newline separated list of CA certificates to use during SSL client certificate validation.
SSLEnabledCipherSuites	The cipher suite to be used in an SSL negotiation.
SSLEnabledProtocols	Used to enable/disable the supported security protocols.
SSLEnableRenegotiation	Whether the renegotiation_info SSL extension is supported.
SSLIncludeCertChain	Whether the entire certificate chain is included in the SSLServerAuthentication event.
SSLKeyLogFile	The location of a file where per-session secrets are written for debugging purposes.
SSLNegotiatedCipher	Returns the negotiated cipher suite.
SSLNegotiatedCipherStrength	Returns the negotiated cipher suite strength.
SSLNegotiatedCipherSuite	Returns the negotiated cipher suite.
SSLNegotiatedKeyExchange	Returns the negotiated key exchange algorithm.
SSLNegotiatedKeyExchangeStrength	Returns the negotiated key exchange algorithm strength.
SSLNegotiatedVersion	Returns the negotiated protocol version.
SSLSecurityFlags	Flags that control certificate verification.
SSLServerCACerts	A newline separated list of CA certificates to use during SSL server certificate validation.
TLS12SignatureAlgorithms	Defines the allowed TLS 1.2 signature algorithms when SSLProvider is set to Internal.
TLS12SupportedGroups	The supported groups for ECC.
TLS13KeyShareGroups	The groups for which to pregenerate key shares.
TLS13SignatureAlgorithms	The allowed certificate signature algorithms.
TLS13SupportedGroups	The supported groups for (EC)DHE key exchange.
AbsoluteTimeout	Determines whether timeouts are inactivity timeouts or absolute timeouts.
FirewallData	Used to send extra data to the firewall.
InBufferSize	The size in bytes of the incoming queue of the socket.
OutBufferSize	The size in bytes of the outgoing queue of the socket.

AccessKey Property (AzureRelayProxy Class)

The Shared Access Key.

Syntax

ANSI (Cross Platform)
char* GetAccessKey();
int SetAccessKey(const char* lpszAccessKey);

Unicode (Windows)
LPWSTR GetAccessKey();
INT SetAccessKey(LPCWSTR lpszAccessKey);

char* ipworksmq_azurerelayproxy_getaccesskey(void* lpObj);
int ipworksmq_azurerelayproxy_setaccesskey(void* lpObj, const char* lpszAccessKey);

QString GetAccessKey();
int SetAccessKey(QString qsAccessKey);

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

AccessKeyName Property (AzureRelayProxy Class)

The Shared Access Key Name.

Syntax

ANSI (Cross Platform)
char* GetAccessKeyName();
int SetAccessKeyName(const char* lpszAccessKeyName);

Unicode (Windows)
LPWSTR GetAccessKeyName();
INT SetAccessKeyName(LPCWSTR lpszAccessKeyName);

char* ipworksmq_azurerelayproxy_getaccesskeyname(void* lpObj);
int ipworksmq_azurerelayproxy_setaccesskeyname(void* lpObj, const char* lpszAccessKeyName);

QString GetAccessKeyName();
int SetAccessKeyName(QString qsAccessKeyName);

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

ConnectionBacklog Property (AzureRelayProxy Class)

This property includes the maximum number of pending connections maintained by the Transmission Control Protocol (TCP)/IP subsystem.

Syntax

ANSI (Cross Platform)
int GetConnectionBacklog();
int SetConnectionBacklog(int iConnectionBacklog);

Unicode (Windows)
INT GetConnectionBacklog();
INT SetConnectionBacklog(INT iConnectionBacklog);

int ipworksmq_azurerelayproxy_getconnectionbacklog(void* lpObj);
int ipworksmq_azurerelayproxy_setconnectionbacklog(void* lpObj, int iConnectionBacklog);

int GetConnectionBacklog();
int SetConnectionBacklog(int iConnectionBacklog);

Default Value

Remarks

This property contains the maximum number of pending connections maintained by the TCP/IP subsystem. This value reflects the SOMAXCONN option for the main listening socket. The default value for most systems is 5. You may set this property to a larger value if the server is expected to receive a large number of connections, and queuing them is desirable.

This property is not available at design time.

Data Type

Integer

Connections Property (AzureRelayProxy Class)

A collection of currently connected clients.

Syntax

IPWorksMQList<IPWorksMQAzureRelayProxyConnection>* GetConnections();

int ipworksmq_azurerelayproxy_getazurerelayproxyconnectioncount(void* lpObj);

int ipworksmq_azurerelayproxy_getazurerelayproxyconnectionconnected(void* lpObj, int connectionid);

int ipworksmq_azurerelayproxy_getazurerelayproxyconnectionconnectionid(void* lpObj, int connectionid);

int ipworksmq_azurerelayproxy_getazurerelayproxyconnectionidletimeout(void* lpObj, int connectionid);
int ipworksmq_azurerelayproxy_setazurerelayproxyconnectionidletimeout(void* lpObj, int connectionid, int iAzureRelayProxyConnectionIdleTimeout);

char* ipworksmq_azurerelayproxy_getazurerelayproxyconnectionlocaladdress(void* lpObj, int connectionid);

char* ipworksmq_azurerelayproxy_getazurerelayproxyconnectionremotehost(void* lpObj, int connectionid);

int ipworksmq_azurerelayproxy_getazurerelayproxyconnectionremoteport(void* lpObj, int connectionid);

int ipworksmq_azurerelayproxy_getazurerelayproxyconnectiontimeout(void* lpObj, int connectionid);
int ipworksmq_azurerelayproxy_setazurerelayproxyconnectiontimeout(void* lpObj, int connectionid, int iAzureRelayProxyConnectionTimeout);

int ipworksmq_azurerelayproxy_getazurerelayproxyconnectionuserdata(void* lpObj, int connectionid, char** lpAzureRelayProxyConnectionUserData, int* lenAzureRelayProxyConnectionUserData);
int ipworksmq_azurerelayproxy_setazurerelayproxyconnectionuserdata(void* lpObj, int connectionid, const char* lpAzureRelayProxyConnectionUserData, int lenAzureRelayProxyConnectionUserData);

int GetAzureRelayProxyConnectionCount();

bool GetAzureRelayProxyConnectionConnected(int iConnectionId);

int GetAzureRelayProxyConnectionConnectionId(int iConnectionId);

int GetAzureRelayProxyConnectionIdleTimeout(int iConnectionId);
int SetAzureRelayProxyConnectionIdleTimeout(int iConnectionId, int iAzureRelayProxyConnectionIdleTimeout);

QString GetAzureRelayProxyConnectionLocalAddress(int iConnectionId);

QString GetAzureRelayProxyConnectionRemoteHost(int iConnectionId);

int GetAzureRelayProxyConnectionRemotePort(int iConnectionId);

int GetAzureRelayProxyConnectionTimeout(int iConnectionId);
int SetAzureRelayProxyConnectionTimeout(int iConnectionId, int iAzureRelayProxyConnectionTimeout);

QByteArray GetAzureRelayProxyConnectionUserData(int iConnectionId);
int SetAzureRelayProxyConnectionUserData(int iConnectionId, QByteArray qbaAzureRelayProxyConnectionUserData);

Remarks

This property is a collection of currently connected clients. All of the connections may be managed using this property. Each connection is described by the different fields of the AzureRelayProxyConnection type.

This collection is a hashtable type of collection, in which the connection Id string is used as the key to the desired connection. The connection Id is present when events such as the Connected event fires.

This property is read-only.

Data Type

IPWorksMQAzureRelayProxyConnection

DefaultIdleTimeout Property (AzureRelayProxy Class)

This property includes the default idle timeout for inactive clients.

Syntax

ANSI (Cross Platform)
int GetDefaultIdleTimeout();
int SetDefaultIdleTimeout(int iDefaultIdleTimeout);

Unicode (Windows)
INT GetDefaultIdleTimeout();
INT SetDefaultIdleTimeout(INT iDefaultIdleTimeout);

int ipworksmq_azurerelayproxy_getdefaultidletimeout(void* lpObj);
int ipworksmq_azurerelayproxy_setdefaultidletimeout(void* lpObj, int iDefaultIdleTimeout);

int GetDefaultIdleTimeout();
int SetDefaultIdleTimeout(int iDefaultIdleTimeout);

Default Value

Remarks

This property specifies the idle timeout (in seconds) for clients. When set to a positive value, the class will disconnect idle clients after the specified timeout.

This applies only to clients that have not sent or received data within DefaultIdleTimeout seconds.

If set to 0 (default), no idle timeout is applied.

Note: DoEvents must be called for the class to check existing connections.

Data Type

Integer

DefaultTimeout Property (AzureRelayProxy Class)

This property includes an initial timeout value to be used by incoming connections.

Syntax

ANSI (Cross Platform)
int GetDefaultTimeout();
int SetDefaultTimeout(int iDefaultTimeout);

Unicode (Windows)
INT GetDefaultTimeout();
INT SetDefaultTimeout(INT iDefaultTimeout);

int ipworksmq_azurerelayproxy_getdefaulttimeout(void* lpObj);
int ipworksmq_azurerelayproxy_setdefaulttimeout(void* lpObj, int iDefaultTimeout);

int GetDefaultTimeout();
int SetDefaultTimeout(int iDefaultTimeout);

Default Value

Remarks

This property is used by the class 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

Integer

HybridConnection Property (AzureRelayProxy Class)

The hybrid connection name.

Syntax

ANSI (Cross Platform)
char* GetHybridConnection();
int SetHybridConnection(const char* lpszHybridConnection);

Unicode (Windows)
LPWSTR GetHybridConnection();
INT SetHybridConnection(LPCWSTR lpszHybridConnection);

char* ipworksmq_azurerelayproxy_gethybridconnection(void* lpObj);
int ipworksmq_azurerelayproxy_sethybridconnection(void* lpObj, const char* lpszHybridConnection);

QString GetHybridConnection();
int SetHybridConnection(QString qsHybridConnection);

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

KeepAlive Property (AzureRelayProxy Class)

When True, KEEPALIVE packets are enabled (for long connections).

Syntax

ANSI (Cross Platform)
int GetKeepAlive();
int SetKeepAlive(int bKeepAlive);

Unicode (Windows)
BOOL GetKeepAlive();
INT SetKeepAlive(BOOL bKeepAlive);

int ipworksmq_azurerelayproxy_getkeepalive(void* lpObj);
int ipworksmq_azurerelayproxy_setkeepalive(void* lpObj, int bKeepAlive);

bool GetKeepAlive();
int SetKeepAlive(bool bKeepAlive);

Default Value

FALSE

Remarks

This property enables the SO_KEEPALIVE option on the incoming connections. This option prevents long connections from timing out in case of inactivity.

Note: System Transmission Control Protocol (TCP)/IP stack implementations are not required to support SO_KEEPALIVE.

This property is shared among incoming connections. When the property is set, the corresponding value is set for incoming connections as they are accepted. Existing connections are not modified.

Data Type

Boolean

Linger Property (AzureRelayProxy Class)

When set to True, connections are terminated gracefully.

Syntax

ANSI (Cross Platform)
int GetLinger();
int SetLinger(int bLinger);

Unicode (Windows)
BOOL GetLinger();
INT SetLinger(BOOL bLinger);

int ipworksmq_azurerelayproxy_getlinger(void* lpObj);
int ipworksmq_azurerelayproxy_setlinger(void* lpObj, int bLinger);

bool GetLinger();
int SetLinger(bool bLinger);

Default Value

TRUE

Remarks

This property controls how a connection is closed. The default is True. In this case, the connection is closed only after all the data are sent. Setting it to False forces an abrupt (hard) disconnection. Any data that were in the sending queue may be lost.

The default behavior (which is also the default mode for stream sockets) might result in an indefinite delay in closing the connection. Although the class returns control immediately, the system might indefinitely hold system resources until all pending data are sent (even after your application closes). This means that valuable system resources might be wasted.

Setting this property to False forces an immediate disconnection. If you know that the other side has received all the data you have sent (e.g., by a client acknowledgment), then setting this property to False might be the appropriate course of action.

This property is shared among incoming connections. When the property is set, the corresponding value is set for incoming connections as they are accepted. Existing connections are not modified.

Data Type

Boolean

Listening Property (AzureRelayProxy Class)

This property indicates whether the class is listening for incoming connections on LocalPort.

Syntax

ANSI (Cross Platform)
int GetListening();

Unicode (Windows)
BOOL GetListening();

int ipworksmq_azurerelayproxy_getlistening(void* lpObj);

bool GetListening();

Default Value

FALSE

Remarks

This property indicates whether the class is listening for connections on the port specified by the LocalPort property. Use the StartListening and StopListening methods to control whether the class is listening.

This property is read-only and not available at design time.

Data Type

Boolean

LocalHost Property (AzureRelayProxy Class)

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

Syntax

ANSI (Cross Platform)
char* GetLocalHost();
int SetLocalHost(const char* lpszLocalHost);

Unicode (Windows)
LPWSTR GetLocalHost();
INT SetLocalHost(LPCWSTR lpszLocalHost);

char* ipworksmq_azurerelayproxy_getlocalhost(void* lpObj);
int ipworksmq_azurerelayproxy_setlocalhost(void* lpObj, const char* lpszLocalHost);

QString GetLocalHost();
int SetLocalHost(QString qsLocalHost);

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 class initiate connections (or accept in the case of server classs) 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 class is connected, the LocalHost 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: LocalHost is not persistent. You must always set it in code, and never in the property window.

Data Type

String

LocalPort Property (AzureRelayProxy Class)

This property includes the Transmission Control Protocol (TCP) port in the local host where the class listens.

Syntax

ANSI (Cross Platform)
int GetLocalPort();
int SetLocalPort(int iLocalPort);

Unicode (Windows)
INT GetLocalPort();
INT SetLocalPort(INT iLocalPort);

int ipworksmq_azurerelayproxy_getlocalport(void* lpObj);
int ipworksmq_azurerelayproxy_setlocalport(void* lpObj, int iLocalPort);

int GetLocalPort();
int SetLocalPort(int iLocalPort);

Default Value

Remarks

This property must be set before the class can start listening. If its value is 0, then the TCP/IP subsystem picks a port number at random. The port number can be found by checking the value of this property after the class is listening (i.e., after successfully assigning True to the Listening property).

The service port is not shared among servers so two classs cannot be listening on the same port at the same time.

Data Type

Integer

NamespaceAddress Property (AzureRelayProxy Class)

The namespace address of the relay.

Syntax

ANSI (Cross Platform)
char* GetNamespaceAddress();
int SetNamespaceAddress(const char* lpszNamespaceAddress);

Unicode (Windows)
LPWSTR GetNamespaceAddress();
INT SetNamespaceAddress(LPCWSTR lpszNamespaceAddress);

char* ipworksmq_azurerelayproxy_getnamespaceaddress(void* lpObj);
int ipworksmq_azurerelayproxy_setnamespaceaddress(void* lpObj, const char* lpszNamespaceAddress);

QString GetNamespaceAddress();
int SetNamespaceAddress(QString qsNamespaceAddress);

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

SSLAuthenticateClients Property (AzureRelayProxy Class)

If set to True, the server asks the client(s) for a certificate.

Syntax

ANSI (Cross Platform)
int GetSSLAuthenticateClients();
int SetSSLAuthenticateClients(int bSSLAuthenticateClients);

Unicode (Windows)
BOOL GetSSLAuthenticateClients();
INT SetSSLAuthenticateClients(BOOL bSSLAuthenticateClients);

int ipworksmq_azurerelayproxy_getsslauthenticateclients(void* lpObj);
int ipworksmq_azurerelayproxy_setsslauthenticateclients(void* lpObj, int bSSLAuthenticateClients);

bool GetSSLAuthenticateClients();
int SetSSLAuthenticateClients(bool bSSLAuthenticateClients);

Default Value

FALSE

Remarks

This property is used in conjunction with the SSLClientAuthentication event. Please refer to the documentation of the SSLClientAuthentication event for details.

Data Type

Boolean

SSLCert Property (AzureRelayProxy Class)

The certificate to be used during Secure Sockets Layer (SSL) negotiation.

Syntax

IPWorksMQCertificate* GetSSLCert();
int SetSSLCert(IPWorksMQCertificate* val);

char* ipworksmq_azurerelayproxy_getsslcerteffectivedate(void* lpObj);

char* ipworksmq_azurerelayproxy_getsslcertexpirationdate(void* lpObj);

char* ipworksmq_azurerelayproxy_getsslcertextendedkeyusage(void* lpObj);

char* ipworksmq_azurerelayproxy_getsslcertfingerprint(void* lpObj);

char* ipworksmq_azurerelayproxy_getsslcertfingerprintsha1(void* lpObj);

char* ipworksmq_azurerelayproxy_getsslcertfingerprintsha256(void* lpObj);

char* ipworksmq_azurerelayproxy_getsslcertissuer(void* lpObj);

char* ipworksmq_azurerelayproxy_getsslcertprivatekey(void* lpObj);

int ipworksmq_azurerelayproxy_getsslcertprivatekeyavailable(void* lpObj);

char* ipworksmq_azurerelayproxy_getsslcertprivatekeycontainer(void* lpObj);

char* ipworksmq_azurerelayproxy_getsslcertpublickey(void* lpObj);

char* ipworksmq_azurerelayproxy_getsslcertpublickeyalgorithm(void* lpObj);

int ipworksmq_azurerelayproxy_getsslcertpublickeylength(void* lpObj);

char* ipworksmq_azurerelayproxy_getsslcertserialnumber(void* lpObj);

char* ipworksmq_azurerelayproxy_getsslcertsignaturealgorithm(void* lpObj);

int ipworksmq_azurerelayproxy_getsslcertstore(void* lpObj, char** lpSSLCertStore, int* lenSSLCertStore);
int ipworksmq_azurerelayproxy_setsslcertstore(void* lpObj, const char* lpSSLCertStore, int lenSSLCertStore);

char* ipworksmq_azurerelayproxy_getsslcertstorepassword(void* lpObj);
int ipworksmq_azurerelayproxy_setsslcertstorepassword(void* lpObj, const char* lpszSSLCertStorePassword);

int ipworksmq_azurerelayproxy_getsslcertstoretype(void* lpObj);
int ipworksmq_azurerelayproxy_setsslcertstoretype(void* lpObj, int iSSLCertStoreType);

char* ipworksmq_azurerelayproxy_getsslcertsubjectaltnames(void* lpObj);

char* ipworksmq_azurerelayproxy_getsslcertthumbprintmd5(void* lpObj);

char* ipworksmq_azurerelayproxy_getsslcertthumbprintsha1(void* lpObj);

char* ipworksmq_azurerelayproxy_getsslcertthumbprintsha256(void* lpObj);

char* ipworksmq_azurerelayproxy_getsslcertusage(void* lpObj);

int ipworksmq_azurerelayproxy_getsslcertusageflags(void* lpObj);

char* ipworksmq_azurerelayproxy_getsslcertversion(void* lpObj);

char* ipworksmq_azurerelayproxy_getsslcertsubject(void* lpObj);
int ipworksmq_azurerelayproxy_setsslcertsubject(void* lpObj, const char* lpszSSLCertSubject);

int ipworksmq_azurerelayproxy_getsslcertencoded(void* lpObj, char** lpSSLCertEncoded, int* lenSSLCertEncoded);
int ipworksmq_azurerelayproxy_setsslcertencoded(void* lpObj, const char* lpSSLCertEncoded, int lenSSLCertEncoded);

QString GetSSLCertEffectiveDate();

QString GetSSLCertExpirationDate();

QString GetSSLCertExtendedKeyUsage();

QString GetSSLCertFingerprint();

QString GetSSLCertFingerprintSHA1();

QString GetSSLCertFingerprintSHA256();

QString GetSSLCertIssuer();

QString GetSSLCertPrivateKey();

bool GetSSLCertPrivateKeyAvailable();

QString GetSSLCertPrivateKeyContainer();

QString GetSSLCertPublicKey();

QString GetSSLCertPublicKeyAlgorithm();

int GetSSLCertPublicKeyLength();

QString GetSSLCertSerialNumber();

QString GetSSLCertSignatureAlgorithm();

QByteArray GetSSLCertStore();
int SetSSLCertStore(QByteArray qbaSSLCertStore);

QString GetSSLCertStorePassword();
int SetSSLCertStorePassword(QString qsSSLCertStorePassword);

int GetSSLCertStoreType();
int SetSSLCertStoreType(int iSSLCertStoreType);

QString GetSSLCertSubjectAltNames();

QString GetSSLCertThumbprintMD5();

QString GetSSLCertThumbprintSHA1();

QString GetSSLCertThumbprintSHA256();

QString GetSSLCertUsage();

int GetSSLCertUsageFlags();

QString GetSSLCertVersion();

QString GetSSLCertSubject();
int SetSSLCertSubject(QString qsSSLCertSubject);

QByteArray GetSSLCertEncoded();
int SetSSLCertEncoded(QByteArray qbaSSLCertEncoded);

Remarks

This property includes the digital certificate that the class will use during SSL negotiation. Set this property to a valid certificate before starting SSL negotiation. To set a certificate, you may set the Encoded field to the encoded certificate. To select a certificate, use the store and subject fields.

Data Type

IPWorksMQCertificate

SSLEnabled Property (AzureRelayProxy Class)

This property indicates whether Transport Layer Security/Secure Sockets Layer (TLS/SSL) is enabled.

Syntax

ANSI (Cross Platform)
int GetSSLEnabled();
int SetSSLEnabled(int bSSLEnabled);

Unicode (Windows)
BOOL GetSSLEnabled();
INT SetSSLEnabled(BOOL bSSLEnabled);

int ipworksmq_azurerelayproxy_getsslenabled(void* lpObj);
int ipworksmq_azurerelayproxy_setsslenabled(void* lpObj, int bSSLEnabled);

bool GetSSLEnabled();
int SetSSLEnabled(bool bSSLEnabled);

Default Value

FALSE

Remarks

This property specifies whether TLS/SSL is enabled in the class. When False (default), the class operates in plaintext mode. When True, TLS/SSL is enabled.

TLS/SSL may also be enabled by setting SSLStartMode. Setting SSLStartMode will automatically update this property value.

This property is not available at design time.

Data Type

Boolean

SSLStartMode Property (AzureRelayProxy Class)

This property determines how the class starts the Secure Sockets Layer (SSL) negotiation.

Syntax

ANSI (Cross Platform)
int GetSSLStartMode();
int SetSSLStartMode(int iSSLStartMode);

Unicode (Windows)
INT GetSSLStartMode();
INT SetSSLStartMode(INT iSSLStartMode);

Possible Values

SSL_AUTOMATIC(0), 
SSL_IMPLICIT(1), 
SSL_EXPLICIT(2), 
SSL_NONE(3)

int ipworksmq_azurerelayproxy_getsslstartmode(void* lpObj);
int ipworksmq_azurerelayproxy_setsslstartmode(void* lpObj, int iSSLStartMode);

int GetSSLStartMode();
int SetSSLStartMode(int iSSLStartMode);

Default Value

Remarks

The SSLStartMode property may have one of the following values:


0 (sslAutomatic)	If the remote port is set to the standard plaintext port of the protocol (where applicable), the class will behave the same as if SSLStartMode is set to sslExplicit. In all other cases, SSL negotiation will be implicit (sslImplicit).
1 (sslImplicit)	The SSL negotiation will start immediately after the connection is established.
2 (sslExplicit)	The class will first connect in plaintext, and then will explicitly start SSL negotiation through a protocol command such as STARTTLS.
3 (sslNone - default)	No SSL negotiation; no SSL security. All communication will be in plaintext mode.

Data Type

Integer

Config Method (AzureRelayProxy Class)

Sets or retrieves a configuration setting.

Syntax

ANSI (Cross Platform)
char* Config(const char* lpszConfigurationString);

Unicode (Windows)
LPWSTR Config(LPCWSTR lpszConfigurationString);

char* ipworksmq_azurerelayproxy_config(void* lpObj, const char* lpszConfigurationString);

QString Config(const QString& qsConfigurationString);

Remarks

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

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, 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.

Error Handling (C++)

This method returns a String value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

Disconnect Method (AzureRelayProxy Class)

This method disconnects the specified client.

Syntax

ANSI (Cross Platform)
int Disconnect(int iConnectionId);

Unicode (Windows)
INT Disconnect(INT iConnectionId);

int ipworksmq_azurerelayproxy_disconnect(void* lpObj, int iConnectionId);

int Disconnect(int iConnectionId);

Remarks

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

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

DoEvents Method (AzureRelayProxy Class)

This method processes events from the internal message queue.

Syntax

ANSI (Cross Platform)
int DoEvents();

Unicode (Windows)
INT DoEvents();

int ipworksmq_azurerelayproxy_doevents(void* lpObj);

int DoEvents();

Remarks

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

Error Handling (C++)

Reset Method (AzureRelayProxy Class)

This method will reset the class.

Syntax

ANSI (Cross Platform)
int Reset();

Unicode (Windows)
INT Reset();

int ipworksmq_azurerelayproxy_reset(void* lpObj);

int Reset();

Remarks

This method will reset the class's properties to their default values.

Error Handling (C++)

Shutdown Method (AzureRelayProxy Class)

This method shuts down the server.

Syntax

ANSI (Cross Platform)
int Shutdown();

Unicode (Windows)
INT Shutdown();

int ipworksmq_azurerelayproxy_shutdown(void* lpObj);

int Shutdown();

Remarks

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

Error Handling (C++)

StartListening Method (AzureRelayProxy Class)

This method starts listening for incoming connections.

Syntax

ANSI (Cross Platform)
int StartListening();

Unicode (Windows)
INT StartListening();

int ipworksmq_azurerelayproxy_startlistening(void* lpObj);

int StartListening();

Remarks

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

To stop listening for new connections, call StopListening. To stop listening for new connections and to disconnect all existing clients, call Shutdown.

Error Handling (C++)

StopListening Method (AzureRelayProxy Class)

This method stops listening for new connections.

Syntax

ANSI (Cross Platform)
int StopListening();

Unicode (Windows)
INT StopListening();

int ipworksmq_azurerelayproxy_stoplistening(void* lpObj);

int StopListening();

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.

Error Handling (C++)

Connected Event (AzureRelayProxy Class)

This event is fired immediately after a connection completes (or fails).

Syntax

ANSI (Cross Platform)
virtual int FireConnected(AzureRelayProxyConnectedEventParams *e);

typedef struct {
  int ConnectionId;
  int StatusCode;
  const char *Description;
  int reserved;
} AzureRelayProxyConnectedEventParams;


Unicode (Windows)
virtual INT FireConnected(AzureRelayProxyConnectedEventParams *e);

typedef struct {
  INT ConnectionId;
  INT StatusCode;
  LPCWSTR Description;
  INT reserved;
} AzureRelayProxyConnectedEventParams;

#define EID_AZURERELAYPROXY_CONNECTED 1

virtual INT IPWORKSMQ_CALL FireConnected(INT &iConnectionId, INT &iStatusCode, LPSTR &lpszDescription);

class AzureRelayProxyConnectedEventParams {
public:
  int ConnectionId();

  int StatusCode();

  const QString &Description();

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void Connected(AzureRelayProxyConnectedEventParams *e);

// Or, subclass AzureRelayProxy and override this emitter function.
virtual int FireConnected(AzureRelayProxyConnectedEventParams *e) {...}

Remarks

If the connection is made normally, StatusCode is 0, and Description is "OK".

If the connection fails, StatusCode has the error code returned by the system. Description contains a description of this code. The value of StatusCode is equal to the value of the system error.

Please refer to the Error Codes section for more information.

ConnectionRequest Event (AzureRelayProxy Class)

This event is fired when a request for connection comes from a remote host.

Syntax

ANSI (Cross Platform)
virtual int FireConnectionRequest(AzureRelayProxyConnectionRequestEventParams *e);

typedef struct {
  const char *Address;
  int Port;
  int Accept;
  int reserved;
} AzureRelayProxyConnectionRequestEventParams;


Unicode (Windows)
virtual INT FireConnectionRequest(AzureRelayProxyConnectionRequestEventParams *e);

typedef struct {
  LPCWSTR Address;
  INT Port;
  BOOL Accept;
  INT reserved;
} AzureRelayProxyConnectionRequestEventParams;

#define EID_AZURERELAYPROXY_CONNECTIONREQUEST 2

virtual INT IPWORKSMQ_CALL FireConnectionRequest(LPSTR &lpszAddress, INT &iPort, BOOL &bAccept);

class AzureRelayProxyConnectionRequestEventParams {
public:
  const QString &Address();

  int Port();

  bool Accept();
  void SetAccept(bool bAccept);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void ConnectionRequest(AzureRelayProxyConnectionRequestEventParams *e);

// Or, subclass AzureRelayProxy and override this emitter function.
virtual int FireConnectionRequest(AzureRelayProxyConnectionRequestEventParams *e) {...}

Remarks

This event indicates an incoming connection. The connection is accepted by default. Address and Port will contain information about the remote host requesting the inbound connection. If you want to refuse it, you can set the Accept parameter to False.

Disconnected Event (AzureRelayProxy Class)

This event is fired when a connection is closed.

Syntax

ANSI (Cross Platform)
virtual int FireDisconnected(AzureRelayProxyDisconnectedEventParams *e);

typedef struct {
  int ConnectionId;
  int StatusCode;
  const char *Description;
  int reserved;
} AzureRelayProxyDisconnectedEventParams;


Unicode (Windows)
virtual INT FireDisconnected(AzureRelayProxyDisconnectedEventParams *e);

typedef struct {
  INT ConnectionId;
  INT StatusCode;
  LPCWSTR Description;
  INT reserved;
} AzureRelayProxyDisconnectedEventParams;

#define EID_AZURERELAYPROXY_DISCONNECTED 3

virtual INT IPWORKSMQ_CALL FireDisconnected(INT &iConnectionId, INT &iStatusCode, LPSTR &lpszDescription);

class AzureRelayProxyDisconnectedEventParams {
public:
  int ConnectionId();

  int StatusCode();

  const QString &Description();

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void Disconnected(AzureRelayProxyDisconnectedEventParams *e);

// Or, subclass AzureRelayProxy and override this emitter function.
virtual int FireDisconnected(AzureRelayProxyDisconnectedEventParams *e) {...}

Remarks

If the connection is broken normally, StatusCode is 0, and Description is "OK".

If the connection is broken for any other reason, StatusCode has the error code returned by the system. Description contains a description of this code. The value of StatusCode is equal to the value of the system error.

Please refer to the Error Codes section for more information.

Error Event (AzureRelayProxy Class)

This event fires information about errors during data delivery.

Syntax

ANSI (Cross Platform)
virtual int FireError(AzureRelayProxyErrorEventParams *e);

typedef struct {
  int ConnectionId;
  int ErrorCode;
  const char *Description;
  int reserved;
} AzureRelayProxyErrorEventParams;


Unicode (Windows)
virtual INT FireError(AzureRelayProxyErrorEventParams *e);

typedef struct {
  INT ConnectionId;
  INT ErrorCode;
  LPCWSTR Description;
  INT reserved;
} AzureRelayProxyErrorEventParams;

#define EID_AZURERELAYPROXY_ERROR 4

virtual INT IPWORKSMQ_CALL FireError(INT &iConnectionId, INT &iErrorCode, LPSTR &lpszDescription);

class AzureRelayProxyErrorEventParams {
public:
  int ConnectionId();

  int ErrorCode();

  const QString &Description();

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void Error(AzureRelayProxyErrorEventParams *e);

// Or, subclass AzureRelayProxy and override this emitter function.
virtual int FireError(AzureRelayProxyErrorEventParams *e) {...}

Remarks

The Error event is fired in case of exceptional conditions during message processing. Normally, the class fails with an error.

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.

ConnectionId indicates the connection for which the error is applicable.

Log Event (AzureRelayProxy Class)

This event fires once for each log message.

Syntax

ANSI (Cross Platform)
virtual int FireLog(AzureRelayProxyLogEventParams *e);

typedef struct {
  int ConnectionId;
  int LogLevel;
  const char *Message;
  const char *LogType;
  int reserved;
} AzureRelayProxyLogEventParams;


Unicode (Windows)
virtual INT FireLog(AzureRelayProxyLogEventParams *e);

typedef struct {
  INT ConnectionId;
  INT LogLevel;
  LPCWSTR Message;
  LPCWSTR LogType;
  INT reserved;
} AzureRelayProxyLogEventParams;

#define EID_AZURERELAYPROXY_LOG 5

virtual INT IPWORKSMQ_CALL FireLog(INT &iConnectionId, INT &iLogLevel, LPSTR &lpszMessage, LPSTR &lpszLogType);

class AzureRelayProxyLogEventParams {
public:
  int ConnectionId();

  int LogLevel();

  const QString &Message();

  const QString &LogType();

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void Log(AzureRelayProxyLogEventParams *e);

// Or, subclass AzureRelayProxy and override this emitter function.
virtual int FireLog(AzureRelayProxyLogEventParams *e) {...}

Remarks

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

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


0 (None)	No events are logged.
1 (Info - default)	Informational events are logged.
2 (Verbose)	Detailed data are logged.
3 (Debug)	Debug data are logged.

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"

ConnectionId specifies the Id of the connection to which the log applies.

SSLClientAuthentication Event (AzureRelayProxy Class)

This event is fired when the client presents its credentials to the server.

Syntax

ANSI (Cross Platform)
virtual int FireSSLClientAuthentication(AzureRelayProxySSLClientAuthenticationEventParams *e);

typedef struct {
  int ConnectionId;
  const char *CertEncoded;
  int lenCertEncoded;
  const char *CertSubject;
  const char *CertIssuer;
  const char *Status;
  int Accept;
  int reserved;
} AzureRelayProxySSLClientAuthenticationEventParams;


Unicode (Windows)
virtual INT FireSSLClientAuthentication(AzureRelayProxySSLClientAuthenticationEventParams *e);

typedef struct {
  INT ConnectionId;
  LPCSTR CertEncoded;
  INT lenCertEncoded;
  LPCWSTR CertSubject;
  LPCWSTR CertIssuer;
  LPCWSTR Status;
  BOOL Accept;
  INT reserved;
} AzureRelayProxySSLClientAuthenticationEventParams;

#define EID_AZURERELAYPROXY_SSLCLIENTAUTHENTICATION 6

virtual INT IPWORKSMQ_CALL FireSSLClientAuthentication(INT &iConnectionId, LPSTR &lpCertEncoded, INT &lenCertEncoded, LPSTR &lpszCertSubject, LPSTR &lpszCertIssuer, LPSTR &lpszStatus, BOOL &bAccept);

class AzureRelayProxySSLClientAuthenticationEventParams {
public:
  int ConnectionId();

  const QByteArray &CertEncoded();

  const QString &CertSubject();

  const QString &CertIssuer();

  const QString &Status();

  bool Accept();
  void SetAccept(bool bAccept);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void SSLClientAuthentication(AzureRelayProxySSLClientAuthenticationEventParams *e);

// Or, subclass AzureRelayProxy and override this emitter function.
virtual int FireSSLClientAuthentication(AzureRelayProxySSLClientAuthenticationEventParams *e) {...}

Remarks

This event enables the server to decide whether or not to continue. The Accept parameter is a recommendation on whether to continue or to 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").

SSLConnectionRequest Event (AzureRelayProxy Class)

This event fires when a Secure Sockets Layer (SSL) connection is requested.

Syntax

ANSI (Cross Platform)
virtual int FireSSLConnectionRequest(AzureRelayProxySSLConnectionRequestEventParams *e);

typedef struct {
  int ConnectionId;
  const char *SupportedCipherSuites;
  const char *SupportedSignatureAlgs;
  int CertStoreType;
  char *CertStore;
  char *CertPassword;
  char *CertSubject;
  int reserved;
} AzureRelayProxySSLConnectionRequestEventParams;


Unicode (Windows)
virtual INT FireSSLConnectionRequest(AzureRelayProxySSLConnectionRequestEventParams *e);

typedef struct {
  INT ConnectionId;
  LPCWSTR SupportedCipherSuites;
  LPCWSTR SupportedSignatureAlgs;
  INT CertStoreType;
  LPWSTR CertStore;
  LPWSTR CertPassword;
  LPWSTR CertSubject;
  INT reserved;
} AzureRelayProxySSLConnectionRequestEventParams;

#define EID_AZURERELAYPROXY_SSLCONNECTIONREQUEST 7

virtual INT IPWORKSMQ_CALL FireSSLConnectionRequest(INT &iConnectionId, LPSTR &lpszSupportedCipherSuites, LPSTR &lpszSupportedSignatureAlgs, INT &iCertStoreType, LPSTR &lpszCertStore, LPSTR &lpszCertPassword, LPSTR &lpszCertSubject);

class AzureRelayProxySSLConnectionRequestEventParams {
public:
  int ConnectionId();

  const QString &SupportedCipherSuites();

  const QString &SupportedSignatureAlgs();

  int CertStoreType();
  void SetCertStoreType(int iCertStoreType);

  const QString &CertStore();
  void SetCertStore(const QString &qsCertStore);

  const QString &CertPassword();
  void SetCertPassword(const QString &qsCertPassword);

  const QString &CertSubject();
  void SetCertSubject(const QString &qsCertSubject);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void SSLConnectionRequest(AzureRelayProxySSLConnectionRequestEventParams *e);

// Or, subclass AzureRelayProxy and override this emitter function.
virtual int FireSSLConnectionRequest(AzureRelayProxySSLConnectionRequestEventParams *e) {...}

Remarks

This event fires when an SSL connection is requested and SSLProvider is set to Internal. This event provides an opportunity to select an alternative certificate to the connecting client. This event does not fire when SSLProvider is set to Platform.

This event allows the class to be configured to use both RSA and ECDSA certificates depending on the connecting client's capabilities.

ConnectionId is the connection Id of the client requesting the connection.

SupportedCipherSuites is a comma-separated list of cipher suites that the client supports.

SupportedSignatureAlgs is a comma-separated list of certificate signature algorithms that the client supports.

CertStoreType is the store type of the alternate certificate to use for this connection. The class supports both public and private keys in a variety of formats. When the cstAuto value is used, the class will automatically determine the type. This field can take one of the following values:


0 (cstUser - default)	For Windows, this specifies that the certificate store is a certificate store owned by the current user. Note: This store type is not available in Java.
1 (cstMachine)	For Windows, this specifies that the certificate store is a machine store. Note: This store type is not available in Java.
2 (cstPFXFile)	The certificate store is the name of a PFX (PKCS#12) file containing certificates.
3 (cstPFXBlob)	The certificate store is a string (binary or Base64-encoded) representing a certificate store in PFX (PKCS#12) format.
4 (cstJKSFile)	The certificate store is the name of a Java Key Store (JKS) file containing certificates. Note: This store type is only available in Java.
5 (cstJKSBlob)	The certificate store is a string (binary or Base64-encoded) representing a certificate store in Java Key Store (JKS) format. Note: This store type is only available in Java.
6 (cstPEMKeyFile)	The certificate store is the name of a PEM-encoded file that contains a private key and an optional certificate.
7 (cstPEMKeyBlob)	The certificate store is a string (binary or Base64-encoded) that contains a private key and an optional certificate.
8 (cstPublicKeyFile)	The certificate store is the name of a file that contains a PEM- or DER-encoded public key certificate.
9 (cstPublicKeyBlob)	The certificate store is a string (binary or Base64-encoded) that contains a PEM- or DER-encoded public key certificate.
10 (cstSSHPublicKeyBlob)	The certificate store is a string (binary or Base64-encoded) that contains an SSH-style public key.
11 (cstP7BFile)	The certificate store is the name of a PKCS#7 file containing certificates.
12 (cstP7BBlob)	The certificate store is a string (binary) representing a certificate store in PKCS#7 format.
13 (cstSSHPublicKeyFile)	The certificate store is the name of a file that contains an SSH-style public key.
14 (cstPPKFile)	The certificate store is the name of a file that contains a PPK (PuTTY Private Key).
15 (cstPPKBlob)	The certificate store is a string (binary) that contains a PPK (PuTTY Private Key).
16 (cstXMLFile)	The certificate store is the name of a file that contains a certificate in XML format.
17 (cstXMLBlob)	The certificate store is a string that contains a certificate in XML format.
18 (cstJWKFile)	The certificate store is the name of a file that contains a JWK (JSON Web Key).
19 (cstJWKBlob)	The certificate store is a string that contains a JWK (JSON Web Key).
21 (cstBCFKSFile)	The certificate store is the name of a file that contains a BCFKS (Bouncy Castle FIPS Key Store). Note: This store type is only available in Java and .NET.
22 (cstBCFKSBlob)	The certificate store is a string (binary or Base64-encoded) representing a certificate store in BCFKS (Bouncy Castle FIPS Key Store) format. Note: This store type is only available in Java and .NET.
23 (cstPKCS11)	The certificate is present on a physical security key accessible via a PKCS#11 interface. To use a security key, the necessary data must first be collected using the CertMgr class. The ListStoreCertificates method may be called after setting CertStoreType to `cstPKCS11`, CertStorePassword to the PIN, and CertStore to the full path of the PKCS#11 DLL. The certificate information returned in the CertList event's `CertEncoded` parameter may be saved for later use. When using a certificate, pass the previously saved security key information as the Store and set StorePassword to the PIN. Code Example. SSH Authentication with Security Key: `certmgr.CertStoreType = CertStoreTypes.cstPKCS11; certmgr.OnCertList += (s, e) => { secKeyBlob = e.CertEncoded; }; certmgr.CertStore = @"C:\Program Files\OpenSC Project\OpenSC\pkcs11\opensc-pkcs11.dll"; certmgr.CertStorePassword = "123456"; //PIN certmgr.ListStoreCertificates(); sftp.SSHCert = new Certificate(CertStoreTypes.cstPKCS11, secKeyBlob, "123456", "*"); sftp.SSHUser = "test"; sftp.SSHLogon("myhost", 22);`
99 (cstAuto)	The store type is automatically detected from the input data. This setting may be used with both public and private keys and can detect any of the supported formats automatically.

CertStore is the store name or location of the alternate certificate to use for this connection.

Designations of certificate stores are platform dependent.

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


MY	A certificate store holding personal certificates with their associated private keys.
CA	Certifying authority certificates.
ROOT	Root certificates.

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).

CertPassword is the password of the certificate store containing the alternate certificate to use for this connection.

CertSubject is the subject of the alternate certificate to use for this connection.

The special value * matches any subject and will select the first certificate in the 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=support@nsoftware.com". Common fields and their meanings are as follows:


Field	Meaning
CN	Common Name. This is commonly a hostname like www.server.com.
O	Organization
OU	Organizational Unit
L	Locality
S	State
C	Country
E	Email Address

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

SSLStatus Event (AzureRelayProxy Class)

This event is fired to show the progress of the secure connection.

Syntax

ANSI (Cross Platform)
virtual int FireSSLStatus(AzureRelayProxySSLStatusEventParams *e);

typedef struct {
  int ConnectionId;
  const char *Message;
  int reserved;
} AzureRelayProxySSLStatusEventParams;


Unicode (Windows)
virtual INT FireSSLStatus(AzureRelayProxySSLStatusEventParams *e);

typedef struct {
  INT ConnectionId;
  LPCWSTR Message;
  INT reserved;
} AzureRelayProxySSLStatusEventParams;

#define EID_AZURERELAYPROXY_SSLSTATUS 8

virtual INT IPWORKSMQ_CALL FireSSLStatus(INT &iConnectionId, LPSTR &lpszMessage);

class AzureRelayProxySSLStatusEventParams {
public:
  int ConnectionId();

  const QString &Message();

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void SSLStatus(AzureRelayProxySSLStatusEventParams *e);

// Or, subclass AzureRelayProxy and override this emitter function.
virtual int FireSSLStatus(AzureRelayProxySSLStatusEventParams *e) {...}

Remarks

The event is fired for informational and logging purposes only. It is used to track the progress of the connection.

AzureRelayProxyConnection Type

A currently connected client.

Syntax

IPWorksMQAzureRelayProxyConnection (declared in ipworksmq.h)

Remarks

This type describes the connection of a client which is currently connected to the class. You may use the different fields of this type to manage the connection.

The following fields are available:

Fields

Connected
int (read-only)
Default Value: FALSE

This field indicates the status of individual connections.

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

ConnectionId
int (read-only)
Default Value: 0

This field contains an identifier generated by the class to identify each connection. This identifier is unique to this connection.

IdleTimeout
int
Default Value: 0

This field contains the idle timeout for this connection. This field is similar to DefaultIdleTimeout but may be set on a per-connection basis to override DefaultIdleTimeout. This field specifies the idle timeout (in seconds) for the connected client. When set to a positive value, the class will disconnect idle clients after the specified timeout.

This applies only to clients that have not sent to received data within the specified number of seconds.

If set to 0 (default), no idle timeout is applied.

Note: DoEvents must be called for the class to check existing connections.

LocalAddress
char* (read-only)
Default Value: ""

This field shows the IP address of the interface through which the connection is passing.

LocalAddress is important for multihomed hosts so that it can be used to find the particular network interface through which an individual connection is going.

RemoteHost
char* (read-only)
Default Value: ""

This field shows the IP address of the remote host through which the connection is coming.

The connection must be valid or an error will be fired.

If the class is configured to use a SOCKS firewall, the value assigned to this property may be preceded with an "*". If this is the case, the host name is passed to the firewall unresolved and the firewall performs the DNS resolution.

RemotePort
int (read-only)
Default Value: 0

This field shows the Transmission Control Protocol (TCP) port on the remote host through which the connection is coming.

The connection must be valid or an error will be fired.

Timeout
int
Default Value: 0

This field specifies a timeout for the class.

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

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

The class will use DoEvents 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 class 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 Timeout field is 0 (asynchronous operation).

UserData
char*
Default Value: ""

The UserData field holds connection-specific user-specified data.

User-specified data may be set or retrieved at any point while the connection is valid. This provides a simple way to associate arbitrary data with a specific connection.

Constructors

AzureRelayProxyConnection()

Certificate Type

This is the digital certificate being used.

Syntax

IPWorksMQCertificate (declared in ipworksmq.h)

Remarks

This type describes the current digital certificate. The certificate may be a public or private key. The fields are used to identify or select certificates.

The following fields are available:

Fields

EffectiveDate
char* (read-only)
Default Value: ""

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.

ExpirationDate
char* (read-only)
Default Value: ""

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.

ExtendedKeyUsage
char* (read-only)
Default Value: ""

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

Fingerprint
char* (read-only)
Default Value: ""

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

FingerprintSHA1
char* (read-only)
Default Value: ""

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

FingerprintSHA256
char* (read-only)
Default Value: ""

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

Issuer
char* (read-only)
Default Value: ""

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

PrivateKey
char* (read-only)
Default Value: ""

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

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

PrivateKeyAvailable
int (read-only)
Default Value: FALSE

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

PrivateKeyContainer
char* (read-only)
Default Value: ""

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

PublicKey
char* (read-only)
Default Value: ""

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

PublicKeyAlgorithm
char* (read-only)
Default Value: ""

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.

PublicKeyLength
int (read-only)
Default Value: 0

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

SerialNumber
char* (read-only)
Default Value: ""

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.

SignatureAlgorithm
char* (read-only)
Default Value: ""

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.

Store
char*
Default Value: "MY"

The name of the certificate store for the client certificate.

The StoreType field denotes the type of the certificate store specified by Store. If the store is password-protected, specify the password in StorePassword.

Store is used in conjunction with the Subject field to specify client certificates. If Store has a value, and Subject or Encoded is set, a search for a certificate is initiated. Please see the Subject field for details.

Designations of certificate stores are platform dependent.

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


MY	A certificate store holding personal certificates with their associated private keys.
CA	Certifying authority certificates.
ROOT	Root certificates.

StorePassword
char*
Default Value: ""

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

StoreType
int
Default Value: 0

The type of certificate store for this certificate.

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


0 (cstUser - default)	For Windows, this specifies that the certificate store is a certificate store owned by the current user. Note: This store type is not available in Java.
1 (cstMachine)	For Windows, this specifies that the certificate store is a machine store. Note: This store type is not available in Java.
2 (cstPFXFile)	The certificate store is the name of a PFX (PKCS#12) file containing certificates.
3 (cstPFXBlob)	The certificate store is a string (binary or Base64-encoded) representing a certificate store in PFX (PKCS#12) format.
4 (cstJKSFile)	The certificate store is the name of a Java Key Store (JKS) file containing certificates. Note: This store type is only available in Java.
5 (cstJKSBlob)	The certificate store is a string (binary or Base64-encoded) representing a certificate store in Java Key Store (JKS) format. Note: This store type is only available in Java.
6 (cstPEMKeyFile)	The certificate store is the name of a PEM-encoded file that contains a private key and an optional certificate.
7 (cstPEMKeyBlob)	The certificate store is a string (binary or Base64-encoded) that contains a private key and an optional certificate.
8 (cstPublicKeyFile)	The certificate store is the name of a file that contains a PEM- or DER-encoded public key certificate.
9 (cstPublicKeyBlob)	The certificate store is a string (binary or Base64-encoded) that contains a PEM- or DER-encoded public key certificate.
10 (cstSSHPublicKeyBlob)	The certificate store is a string (binary or Base64-encoded) that contains an SSH-style public key.
11 (cstP7BFile)	The certificate store is the name of a PKCS#7 file containing certificates.
12 (cstP7BBlob)	The certificate store is a string (binary) representing a certificate store in PKCS#7 format.
13 (cstSSHPublicKeyFile)	The certificate store is the name of a file that contains an SSH-style public key.
14 (cstPPKFile)	The certificate store is the name of a file that contains a PPK (PuTTY Private Key).
15 (cstPPKBlob)	The certificate store is a string (binary) that contains a PPK (PuTTY Private Key).
16 (cstXMLFile)	The certificate store is the name of a file that contains a certificate in XML format.
17 (cstXMLBlob)	The certificate store is a string that contains a certificate in XML format.
18 (cstJWKFile)	The certificate store is the name of a file that contains a JWK (JSON Web Key).
19 (cstJWKBlob)	The certificate store is a string that contains a JWK (JSON Web Key).
21 (cstBCFKSFile)	The certificate store is the name of a file that contains a BCFKS (Bouncy Castle FIPS Key Store). Note: This store type is only available in Java and .NET.
22 (cstBCFKSBlob)	The certificate store is a string (binary or Base64-encoded) representing a certificate store in BCFKS (Bouncy Castle FIPS Key Store) format. Note: This store type is only available in Java and .NET.
23 (cstPKCS11)	The certificate is present on a physical security key accessible via a PKCS#11 interface. To use a security key, the necessary data must first be collected using the CertMgr class. The ListStoreCertificates method may be called after setting CertStoreType to `cstPKCS11`, CertStorePassword to the PIN, and CertStore to the full path of the PKCS#11 DLL. The certificate information returned in the CertList event's `CertEncoded` parameter may be saved for later use. When using a certificate, pass the previously saved security key information as the Store and set StorePassword to the PIN. Code Example. SSH Authentication with Security Key: `certmgr.CertStoreType = CertStoreTypes.cstPKCS11; certmgr.OnCertList += (s, e) => { secKeyBlob = e.CertEncoded; }; certmgr.CertStore = @"C:\Program Files\OpenSC Project\OpenSC\pkcs11\opensc-pkcs11.dll"; certmgr.CertStorePassword = "123456"; //PIN certmgr.ListStoreCertificates(); sftp.SSHCert = new Certificate(CertStoreTypes.cstPKCS11, secKeyBlob, "123456", "*"); sftp.SSHUser = "test"; sftp.SSHLogon("myhost", 22);`
99 (cstAuto)	The store type is automatically detected from the input data. This setting may be used with both public and private keys and can detect any of the supported formats automatically.

SubjectAltNames
char* (read-only)
Default Value: ""

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

ThumbprintMD5
char* (read-only)
Default Value: ""

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.

ThumbprintSHA1
char* (read-only)
Default Value: ""

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.

ThumbprintSHA256
char* (read-only)
Default Value: ""

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.

Usage
char* (read-only)
Default Value: ""

The text description of UsageFlags.

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.

UsageFlags
int (read-only)
Default Value: 0

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


0x80	Digital Signature
0x40	Non-Repudiation
0x20	Key Encipherment
0x10	Data Encipherment
0x08	Key Agreement
0x04	Certificate Signing
0x02	CRL Signing
0x01	Encipher Only

Please see the Usage field for a text representation of UsageFlags.

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

Version
char* (read-only)
Default Value: ""

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

Subject
char*
Default Value: ""

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 field 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=support@nsoftware.com". Common fields and their meanings are as follows:


Field	Meaning
CN	Common Name. This is commonly a hostname like www.server.com.
O	Organization
OU	Organizational Unit
L	Locality
S	State
C	Country
E	Email Address

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

Encoded
char*
Default Value: ""

The certificate (PEM/Base64 encoded). This field is used to assign a specific certificate. The Store and Subject fields also may be used to specify a certificate.

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

Constructors

Certificate()

Creates a instance whose properties can be set. This is useful for use with when generating new certificates.

Certificate(const char* lpEncoded, int lenEncoded)

Parses Encoded as an X.509 public key.

Certificate(int iStoreType, const char* lpStore, int lenStore, const char* lpszStorePassword, const char* lpszSubject)

StoreType identifies the type of certificate store to use. See for descriptions of the different certificate stores. Store is a byte array containing the certificate data. StorePassword is the password used to protect the store.

After the store has been successfully opened, the component will attempt to find the certificate identified by Subject . This can be either a complete or a substring match of the X.509 certificate's subject Distinguished Name (DN). The Subject parameter can also take an MD5, SHA-1, or SHA-256 thumbprint of the certificate to load in a "Thumbprint=value" format.

IPWorksMQList Type

Syntax

IPWorksMQList<T> (declared in ipworksmq.h)

Remarks

IPWorksMQList is a generic class that is used to hold a collection of objects of type T, where T is one of the custom types supported by the AzureRelayProxy class.

Methods

GetCount	This method returns the current size of the collection. int GetCount() {}
SetCount	This method sets the size of the collection. This method returns `0` if setting the size was successful; or `-1` if the collection is `ReadOnly`. When adding additional objects to a collection call this method to specify the new size. Increasing the size of the collection preserves existing objects in the collection. int SetCount(int count) {}
Get	This method gets the item at the specified position. The `index` parameter specifies the index of the item in the collection. This method returns `NULL` if an invalid `index` is specified. T* Get(int index) {}
Set	This method sets the item at the specified position. The `index` parameter specifies the index of the item in the collection that is being set. This method returns `-1` if an invalid `index` is specified. Note: Objects created using the `new` operator must be freed using the `delete` operator; they will not be automatically freed by the class. T* Set(int index, T* value) {}

Config Settings (AzureRelayProxy Class)

The class accepts one or more of the following configuration settings. Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, access to these internal properties is provided through the Config method.

AzureRelayProxy Config Settings

AccessToken: Returns an access token for use outside of the components.

This setting returns an access token suitable for use in the HTTP Authorization header of a request. This is useful when a separate HTTP client is used to make a HTTP request to the relay service. The value returned by this setting can be set directly as the value for the Authorization header.

The value will be in the format:

SharedAccessSignature sr=sb%3a%2f%2fnstest.servicebus.windows.net%2fhc1&sig=a2EjYWw%2fDlg%2bPcNb%2fC7%2fxBbM11JjfgdO6ZVsQRm18Gg%3d&se=1555368805&skn=RootManageSharedAccessKey

LogLevel: The level of detail that is logged.

This setting controls the level of detail that is logged through the Log event. Possible values are:


0 (None)	No events are logged.
1 (Info - default)	Informational events are logged.
2 (Verbose)	Detailed data is logged.
3 (Debug)	Debug data is logged.

The value 1 (Info) logs basic information about the connection and connecting clients.

The value 2 (Verbose) logs detailed information about each connection and the control connection.

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

TokenValidity: The validity time in seconds of the access token.

This setting specifies the validity time of the access token to create when authenticating. The default value is 3600 seconds.

HTTP Config Settings

AcceptEncoding: Used to tell the server which types of content encodings the client supports.

When AllowHTTPCompression is True, the class adds an Accept-Encoding header to the request being sent to the server. By default, this header's value is "gzip, deflate". This configuration setting allows you to change the value of the Accept-Encoding header. Note: The class only supports gzip and deflate decompression algorithms.

AllowHTTPCompression: This property enables HTTP compression for receiving data.

This configuration setting enables HTTP compression for receiving data. When set to True (default), the class will accept compressed data. It then will uncompress the data it has received. The class will handle data compressed by both gzip and deflate compression algorithms.

When True, the class adds an Accept-Encoding header to the outgoing request. The value for this header can be controlled by the AcceptEncoding configuration setting. The default value for this header is "gzip, deflate".

The default value is True.

AllowHTTPFallback: Whether HTTP/2 connections are permitted to fallback to HTTP/1.1.

This configuration setting controls whether HTTP/2 connections are permitted to fall back to HTTP/1.1 when the server does not support HTTP/2. This setting is applicable only when HTTPVersion is set to "2.0".

If set to True (default), the class will automatically use HTTP/1.1 if the server does not support HTTP/2. If set to False, the class fails with an error if the server does not support HTTP/2.

The default value is True.

Append: Whether to append data to LocalFile.

This configuration setting determines whether data will be appended when writing to LocalFile. When set to True, downloaded data will be appended to LocalFile. This may be used in conjunction with Range to resume a failed download. This is applicable only when LocalFile is set. The default value is False.

Authorization: The Authorization string to be sent to the server.

If the Authorization property contains a nonempty string, an Authorization HTTP request header is added to the request. This header conveys Authorization information to the server.

This property is provided so that the HTTP class can be extended with other security schemes in addition to the authorization schemes already implemented by the class.

The AuthScheme property defines the authentication scheme used. In the case of HTTP Basic Authentication (default), every time User and Password are set, they are Base64 encoded, and the result is put in the Authorization property in the form "Basic [encoded-user-password]".

BytesTransferred: Contains the number of bytes transferred in the response data.

This configuration setting returns the raw number of bytes from the HTTP response data, before the component processes the data, whether it is chunked or compressed. This returns the same value as the Transfer event, by BytesTransferred.

ChunkSize: Specifies the chunk size in bytes when using chunked encoding.

This is applicable only when UseChunkedEncoding is True. This setting specifies the chunk size in bytes to be used when posting data. The default value is 16384.

CompressHTTPRequest: Set to true to compress the body of a PUT or POST request.

If set to True, the body of a PUT or POST request will be compressed into gzip format before sending the request. The "Content-Encoding" header is also added to the outgoing request.

The default value is False.

EncodeURL: If set to True the URL will be encoded by the class.

If set to True, the URL passed to the class will be URL encoded. The default value is False.

FollowRedirects: Determines what happens when the server issues a redirect.

This option determines what happens when the server issues a redirect. Normally, the class returns an error if the server responds with an "Object Moved" message. If this property is set to 1 (always), the new URL for the object is retrieved automatically every time.

If this property is set to 2 (Same Scheme), the new URL is retrieved automatically only if the URL Scheme is the same; otherwise, the class fails with an error.

Note: Following the HTTP specification, unless this option is set to 1 (Always), automatic redirects will be performed only for GET or HEAD requests. Other methods potentially could change the conditions of the initial request and create security vulnerabilities.

Furthermore, if either the new URL server or port are different from the existing one, User and Password are also reset to empty, unless this property is set to 1 (Always), in which case the same credentials are used to connect to the new server.

A Redirect event is fired for every URL the product is redirected to. In the case of automatic redirections, the Redirect event is a good place to set properties related to the new connection (e.g., new authentication parameters).

The default value is 0 (Never). In this case, redirects are never followed, and the class fails with an error instead.

Following are the valid options:

0 - Never
1 - Always
2 - Same Scheme

GetOn302Redirect: If set to True the class will perform a GET on the new location.

The default value is False. If set to True, the class will perform a GET on the new location. Otherwise, it will use the same HTTP method again.

HTTP2HeadersWithoutIndexing: HTTP2 headers that should not update the dynamic header table with incremental indexing.

HTTP/2 servers maintain a dynamic table of headers and values seen over the course of a connection. Typically, these headers are inserted into the table through incremental indexing (also known as HPACK, defined in RFC 7541). To tell the component not to use incremental indexing for certain headers, and thus not update the dynamic table, set this configuration option to a comma-delimited list of the header names.

HTTPVersion: The version of HTTP used by the class.

This property specifies the HTTP version used by the class. Possible values are as follows:

"1.0"
"1.1" (default)
"2.0"
"3.0"

When using HTTP/2 ("2.0"), additional restrictions apply. Please see the following notes for details.

HTTP/2 Notes

When using HTTP/2, a secure Secure Sockets Layer/Transport Layer Security (TLS/SSL) connection is required. Attempting to use a plaintext URL with HTTP/2 will result in an error.

If the server does not support HTTP/2, the class will automatically use HTTP/1.1 instead. This is done to provide compatibility without the need for any additional settings. To see which version was used, check NegotiatedHTTPVersion after calling a method. The AllowHTTPFallback setting controls whether this behavior is allowed (default) or disallowed.

HTTP/3 Notes

HTTP/3 is supported only in .NET and Java.

When using HTTP/3, a secure (TLS/SSL) connection is required. Attempting to use a plaintext URL with HTTP/3 will result in an error.

IfModifiedSince: A date determining the maximum age of the desired document.

If this setting contains a nonempty string, an If-Modified-Since HTTP header is added to the request. The value of this header is used to make the HTTP request conditional: if the requested documented has not been modified since the time specified in the field, a copy of the document will not be returned from the server; instead, a 304 (not modified) response will be returned by the server and the component throws an exception

The format of the date value for IfModifiedSince is detailed in the HTTP specs. For example: Sat, 29 Oct 2017 19:43:31 GMT.

KeepAlive: Determines whether the HTTP connection is closed after completion of the request.

If true, the component will not send the Connection: Close header. The absence of the Connection header indicates to the server that HTTP persistent connections should be used if supported. Note: Not all servers support persistent connections. If false, the connection will be closed immediately after the server response is received.

The default value for KeepAlive is false.

KerberosSPN: The Service Principal Name for the Kerberos Domain Controller.

If the Service Principal Name on the Kerberos Domain Controller is not the same as the URL that you are authenticating to, the Service Principal Name should be set here.

LogLevel: The level of detail that is logged.

This configuration setting controls the level of detail that is logged through the Log event. Possible values are as follows:


0 (None)	No events are logged.
1 (Info - default)	Informational events are logged.
2 (Verbose)	Detailed data are logged.
3 (Debug)	Debug data are logged.

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

The value 2 (Verbose) logs additional information about the request and response.

The value 3 (Debug) logs the headers and body for both the request and response, as well as additional debug information (if any).

MaxRedirectAttempts: Limits the number of redirects that are followed in a request.

When FollowRedirects is set to any value other than frNever, the class will follow redirects until this maximum number of redirect attempts are made. The default value is 20.

NegotiatedHTTPVersion: The negotiated HTTP version.

This configuration setting may be queried after the request is complete to indicate the HTTP version used. When HTTPVersion is set to "2.0" (if the server does not support "2.0"), then the class will fall back to using "1.1" automatically. This setting will indicate which version was used.

OtherHeaders: Other headers as determined by the user (optional).

This configuration setting can be set to a string of headers to be appended to the HTTP request headers.

The headers must follow the format "header: value" as described in the HTTP specifications. Header lines should be separated by CRLF ("\r\n") .

Use this configuration setting with caution. If this configuration setting contains invalid headers, HTTP requests may fail.

This configuration setting is useful for extending the functionality of the class beyond what is provided.

ProxyAuthorization: The authorization string to be sent to the proxy server.

This is similar to the Authorization configuration setting, but is used for proxy authorization. If this configuration setting contains a nonempty string, a Proxy-Authorization HTTP request header is added to the request. This header conveys proxy Authorization information to the server. If User and Password are specified, this value is calculated using the algorithm specified by AuthScheme.

ProxyAuthScheme: The authorization scheme to be used for the proxy.