Struct ipworksedi::GISBSender

Properties   Methods   Events   Config Settings   Errors  

The GISBSender struct implements an GISB / EDM client.

Syntax

ipworksedi::GISBSender

Remarks

The GISBSender component is used to send EDI or other documents using the GISB (Gas Industry Standards Board) / NAESB (North American Energy Standards Board) EDM (Electronic Delivery Mechanism) protocol.

When sending an EDI message, the client should specify, at a minimum, data_from, data_to, url, edi_data, and edi_type. The post method should then be invoked.

Basic Features: GISB Versions 1.4 and above

Security is provided via the use of PGP. If you want to sign and/or encrypt your message set the sign_data and encrypt_data properties to true. The struct does not itself implement PGP, instead it uses a

The following table defines possible values that may be passed to the set_pgp_param.

to allow you to process the PGP data with a library of your choice.

TLS/SSL will also be used if the scheme in url is "https". In case your trading partner is using a self-signed certificate you may set ssl_accept_server_cert or trap the on_ssl_server_authentication event to accept the certificate.

After you post the server will issue a brief reply. If the server indicates some sort of an error an exception will be thrown. However, the absence of an error message does not necessarily mean that the server was able to read the EDI data. The server may attempt to process the data after closing the connection; if it finds an error it might send a separate error notification which may be processed by the GISBReceiver component.

Extended Security Options: NAESB Version 1.6

Version 1.6 of the NAESB/GISB protocol includes extensions to allow additional security. Like the AS2 protocol, version 1.6 allows for the use of receipts.

To request a receipt, set the receipt_to property. The receipt_type and receipt_security properties may be used to customize the receipt request; by default, the struct will request a GISB-Acknowledgement-Receipt signed over an SHA-1 hash. The receipt will be returned in the HTTP reply, and will automatically be verified by the struct.

Object Lifetime

The new() method returns a mutable reference to a struct instance. The object itself is kept in the global list maintained by IPWorksEDI. Due to this, the GISBSender struct cannot be disposed of automatically. Please, call the dispose(&self) method of GISBSender 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.

cookie_count property (GISBSender Struct)

The number of records in the Cookie arrays.

Syntax

fn cookie_count(&self) -> Result<i32, IPWorksEDIError> 
fn set_cookie_count(&self, value : i32) ->  Option<IPWorksEDIError> 

Default Value

0

Remarks

This property controls the size of the following arrays:

• cookie_domain
• cookie_expiration
• cookie_name
• cookie_path
• cookie_secure
• cookie_value

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

Data Type

i32

cookie_domain property (GISBSender Struct)

The domain of a received cookie.

Syntax

fn cookie_domain(&self, CookieIndex : i32) -> Result<String, IPWorksEDIError> 

Default Value

""

Remarks

The domain of a received cookie. This property contains a domain name to limit the cookie to (if provided by the server). If the server does not provide a domain name, this property will contain an empty string. The convention in this case is to use the server name specified by url_server as the cookie domain.

The CookieIndex parameter specifies the index of the item in the array. The size of the array is controlled by the cookie_count property.

This property is read-only.

Data Type

String

cookie_expiration property (GISBSender Struct)

An expiration time for the cookie (if provided by the server).

Syntax

fn cookie_expiration(&self, CookieIndex : i32) -> Result<String, IPWorksEDIError> 

Default Value

""

Remarks

An expiration time for the cookie (if provided by the server). The time format used is "Weekday, DD-Mon-YY HH:MM:SS GMT". If the server does not provide an expiration time, this property will contain an empty string. The convention is to drop the cookie at the end of the session.

The CookieIndex parameter specifies the index of the item in the array. The size of the array is controlled by the cookie_count property.

This property is read-only.

Data Type

String

cookie_name property (GISBSender Struct)

The name of the cookie.

Syntax

fn cookie_name(&self, CookieIndex : i32) -> Result<String, IPWorksEDIError> 
fn set_cookie_name(&self, CookieIndex : i32, value : &str) ->  Option<IPWorksEDIError> 
fn set_cookie_name_ref(&self, CookieIndex : i32, value : &String) ->  Option<IPWorksEDIError> 

Default Value

""

Remarks

This property, along with cookie_value, stores the cookie that is to be sent to the server. The on_set_cookie event displays the cookies sent by the server and their properties.

The CookieIndex parameter specifies the index of the item in the array. The size of the array is controlled by the cookie_count property.

Data Type

String

cookie_path property (GISBSender Struct)

A path name to limit the cookie to (if provided by the server).

Syntax

fn cookie_path(&self, CookieIndex : i32) -> Result<String, IPWorksEDIError> 

Default Value

""

Remarks

A path name to limit the cookie to (if provided by the server). If the server does not provide a cookie path, the path property will be an empty string. The convention in this case is to use the path specified by url_path as the cookie path.

The CookieIndex parameter specifies the index of the item in the array. The size of the array is controlled by the cookie_count property.

This property is read-only.

Data Type

String

cookie_secure property (GISBSender Struct)

The security flag of the received cookie.

Syntax

fn cookie_secure(&self, CookieIndex : i32) -> Result<bool, IPWorksEDIError> 

Default Value

false

Remarks

The security flag of the received cookie. This property specifies whether the cookie is secure. If the value of this property is True, the cookie value must be submitted only through a secure (HTTPS) connection.

The CookieIndex parameter specifies the index of the item in the array. The size of the array is controlled by the cookie_count property.

This property is read-only.

Data Type

bool

cookie_value property (GISBSender Struct)

The value of the cookie.

Syntax

fn cookie_value(&self, CookieIndex : i32) -> Result<String, IPWorksEDIError> 
fn set_cookie_value(&self, CookieIndex : i32, value : &str) ->  Option<IPWorksEDIError> 
fn set_cookie_value_ref(&self, CookieIndex : i32, value : &String) ->  Option<IPWorksEDIError> 

Default Value

""

Remarks

The value of the cookie. A corresponding value is associated with the cookie specified by cookie_name. This property holds that value.

The on_set_cookie event provides the cookies set by the server.

The CookieIndex parameter specifies the index of the item in the array. The size of the array is controlled by the cookie_count property.

Data Type

String

data_element_count property (GISBSender Struct)

The number of records in the DataElement arrays.

Syntax

fn data_element_count(&self) -> Result<i32, IPWorksEDIError> 
fn set_data_element_count(&self, value : i32) ->  Option<IPWorksEDIError> 

Default Value

0

Remarks

This property controls the size of the following arrays:

• data_element_name
• data_element_value

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

Data Type

i32

data_element_name property (GISBSender Struct)

The name of the current data element.

Syntax

fn data_element_name(&self, ElementIndex : i32) -> Result<String, IPWorksEDIError> 
fn set_data_element_name(&self, ElementIndex : i32, value : &str) ->  Option<IPWorksEDIError> 
fn set_data_element_name_ref(&self, ElementIndex : i32, value : &String) ->  Option<IPWorksEDIError> 

Default Value

""

Remarks

The name of the current data element.

The ElementIndex parameter specifies the index of the item in the array. The size of the array is controlled by the data_element_count property.

Data Type

String

data_element_value property (GISBSender Struct)

The value of the current data element.

Syntax

fn data_element_value(&self, ElementIndex : i32) -> Result<String, IPWorksEDIError> 
fn set_data_element_value(&self, ElementIndex : i32, value : &str) ->  Option<IPWorksEDIError> 
fn set_data_element_value_ref(&self, ElementIndex : i32, value : &String) ->  Option<IPWorksEDIError> 

Default Value

""

Remarks

The value of the current data element.

The ElementIndex parameter specifies the index of the item in the array. The size of the array is controlled by the data_element_count property.

Data Type

String

data_from property (GISBSender Struct)

The identity of the sending system.

Syntax

fn data_from(&self) -> Result<String, IPWorksEDIError> 
fn set_data_from(&self, value : &str) ->  Option<IPWorksEDIError> 
fn set_data_from_ref(&self, value : &String) ->  Option<IPWorksEDIError> 

Default Value

""

Remarks

Will generally be the DUNS number of the sending trading partner. Required.

Data Type

String

data_to property (GISBSender Struct)

The identity of the receiving system.

Syntax

fn data_to(&self) -> Result<String, IPWorksEDIError> 
fn set_data_to(&self, value : &str) ->  Option<IPWorksEDIError> 
fn set_data_to_ref(&self, value : &String) ->  Option<IPWorksEDIError> 

Default Value

""

Remarks

Will generally be the DUNS number of the receiving trading partner. Required.

Data Type

String

encrypt_data property (GISBSender Struct)

Whether or not to encrypt the data.

Syntax

fn encrypt_data(&self) -> Result<bool, IPWorksEDIError> 
fn set_encrypt_data(&self, value : bool) ->  Option<IPWorksEDIError> 

Default Value

false

Remarks

If true, then the data will be encrypted before sending to the server.

Data Type

bool

firewall_auto_detect property (GISBSender Struct)

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

Syntax

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

Default Value

false

Remarks

Data Type

bool

firewall_type property (GISBSender Struct)

The type of firewall to connect through.

Syntax

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

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 (GISBSender Struct)

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

Syntax

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

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 (GISBSender Struct)

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

Syntax

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

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 (GISBSender Struct)

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

Syntax

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

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_type is set to a valid value. See the description of the firewall_type property for details.

Data Type

i32

firewall_user property (GISBSender Struct)

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

Syntax

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

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

edi_data property (GISBSender Struct)

This property contains the EDI payload of the transmission.

Syntax

fn edi_data(&self) -> Result<Vec<u8>, IPWorksEDIError> 
fn set_edi_data(&self, value : Vec<u8>) ->  Option<IPWorksEDIError> 
fn set_edi_data_ref(&self, value : &[u8]) ->  Option<IPWorksEDIError> 

Default Value

""

Remarks

In a receiver, this property will only be populated if edi_output_stream has not been specified and parse_request finishes without an error. edi_data will contain the full decrypted text of the EDI message.

Data Type

Vec<u8>

edi_type property (GISBSender Struct)

The EDIType of the EDI message.

Syntax

fn edi_type(&self) -> Result<String, IPWorksEDIError> 
fn set_edi_type(&self, value : &str) ->  Option<IPWorksEDIError> 
fn set_edi_type_ref(&self, value : &String) ->  Option<IPWorksEDIError> 

Default Value

"X12"

Remarks

The EDIType of the EDI message. The default value is "X12". edi_type may also be set to "error", in which case the message is an error relating to a previous message. In this case the error_message property and related properties will provide more information.

Data Type

String

edi_file_name property (GISBSender Struct)

In a sender, if FileName is specified, the file specified will be used for the EDI payload of the transmission.

Syntax

fn edi_file_name(&self) -> Result<String, IPWorksEDIError> 
fn set_edi_file_name(&self, value : &str) ->  Option<IPWorksEDIError> 
fn set_edi_file_name_ref(&self, value : &String) ->  Option<IPWorksEDIError> 

Default Value

""

Remarks

In a sender, if edi_file_name is specified, the file specified will be used for the EDI payload of the transmission. edi_name will be populated with the name of the file.

In a receiver, if this property is set prior to calling parse_form_data and parse_request the incoming data will be decrypted and written to the file at the specified path.

Note: When edi_output_stream is set, the data will be written to the stream and this property will not be populated.

Data Type

String

edi_name property (GISBSender Struct)

Name is the final name to be associated with the contents of either the Data or FileName properties.

Syntax

fn edi_name(&self) -> Result<String, IPWorksEDIError> 
fn set_edi_name(&self, value : &str) ->  Option<IPWorksEDIError> 
fn set_edi_name_ref(&self, value : &String) ->  Option<IPWorksEDIError> 

Default Value

"rfc1767.edi"

Remarks

edi_name is the final name to be associated with the contents of either the edi_data or edi_file_name properties. This corresponds to the filename attribute of the Content-Disposition header for the EDI payload.

When constructing EDI data to be sent, edi_name will be set to the same value as edi_file_name, but can be overridden after setting edi_file_name to indicate that another name should be used in the outbound request's Content-Disposition MIME header.

When receiving EDI data, edi_name will be read out of the "filename" attribute of the inbound request's Content-Disposition MIME header.

Data Type

String

gisb_version property (GISBSender Struct)

The version of GISB/NAESB being used.

Syntax

fn gisb_version(&self) -> Result<String, IPWorksEDIError> 
fn set_gisb_version(&self, value : &str) ->  Option<IPWorksEDIError> 
fn set_gisb_version_ref(&self, value : &String) ->  Option<IPWorksEDIError> 

Default Value

"1.6"

Remarks

The version of the GISB/NAESB EDM being used. Supported values are "1.4", "1.6", "2.0", and "2.1". Note that requesting a receipt is only supported in version 1.6 and up.

Data Type

String

local_host property (GISBSender 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, IPWorksEDIError> 
fn set_local_host(&self, value : &str) ->  Option<IPWorksEDIError> 
fn set_local_host_ref(&self, value : &String) ->  Option<IPWorksEDIError> 

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

log_directory property (GISBSender Struct)

The path to a directory for logging.

Syntax

fn log_directory(&self) -> Result<String, IPWorksEDIError> 
fn set_log_directory(&self, value : &str) ->  Option<IPWorksEDIError> 
fn set_log_directory_ref(&self, value : &String) ->  Option<IPWorksEDIError> 

Default Value

""

Remarks

Setting LogDirectory will instruct the component to log the details of each transmission to unique files in the specified directory. For each request processed, the struct will log the original EDI data, the complete text of the outgoing request and the incoming response.

The struct will write a single file for each transmission, with extension ".log". In case of error an additional file will be written with extension ".err", and the error will be reported in both files.

The filenames will be chosen automatically by the struct. Each filename will be the system time, in the format YYYY-MM-DD-HH-MM-SS-MMMM, with extensions "-2", "-3", used in case files of those names already exist. After each transaction is processed log_file will contain the name of the files just written, minus the extension ".log" or ".err".

If logs cannot be written an exception will be thrown.

Data Type

String

log_file property (GISBSender Struct)

The log file written.

Syntax

fn log_file(&self) -> Result<String, IPWorksEDIError> 

Default Value

""

Remarks

In case log_directory is specified a log file will be written in the specified directory and log_file will contain the path. A diagnostic log will be written with filename log_file + ".log", and in case of error, an additional file will be written with filename log_file + ".dat".

This property is read-only.

Data Type

String

proxy_auth_scheme property (GISBSender Struct)

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

Syntax

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

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 (GISBSender Struct)

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

Syntax

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

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 (GISBSender Struct)

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

Syntax

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

Default Value

""

Remarks

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 (GISBSender Struct)

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

Syntax

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

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 (GISBSender 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, IPWorksEDIError> 
fn set_proxy_server(&self, value : &str) ->  Option<IPWorksEDIError> 
fn set_proxy_server_ref(&self, value : &String) ->  Option<IPWorksEDIError> 

Default Value

""

Remarks

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 (GISBSender Struct)

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

Syntax

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

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 (GISBSender Struct)

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

Syntax

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

Default Value

""

Remarks

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

public_keyring_data property (GISBSender Struct)

Public keyring data.

Syntax

fn public_keyring_data(&self) -> Result<Vec<u8>, IPWorksEDIError> 
fn set_public_keyring_data(&self, value : Vec<u8>) ->  Option<IPWorksEDIError> 
fn set_public_keyring_data_ref(&self, value : &[u8]) ->  Option<IPWorksEDIError> 

Default Value

""

Remarks

This property allows the public keyring data to be specific in the form of a byte array. Use this in conjunction with secret_keyring_data and the keyring will be loaded from this data instead of the homedir.

Data Type

Vec<u8>

receipt_security property (GISBSender Struct)

[1.6] Used to indicate the security options requested for the receipt.

Syntax

fn receipt_security(&self) -> Result<String, IPWorksEDIError> 
fn set_receipt_security(&self, value : &str) ->  Option<IPWorksEDIError> 
fn set_receipt_security_ref(&self, value : &String) ->  Option<IPWorksEDIError> 

Default Value

"signed-receipt-protocol=optional, pgp-signature; signed-receipt-micalg=optional, sha1, md5"

Remarks

Only supported for Version 1.6.

By default, the struct will request that the receipt be signed with a PGP signature over an SHA1 or MD5 hash (if these algorithms are supported by the server).

Set receipt_security to an empty string to request an unsigned receipt.

The string format is that of the Disposition-notification-options HTTP header, as specified in RFC 3335.

Data Type

String

receipt_signing_protocol property (GISBSender Struct)

[1.6] Indicates the protocol used to sign the receipt.

Syntax

fn receipt_signing_protocol(&self) -> Result<String, IPWorksEDIError> 

Default Value

""

Remarks

Only supported for Version 1.6.

This property will be populated after a receipt is received from the server and validated. It will contain the MIME type of the signature used, if any (i.e., "application/pgp-signature"). It will contain an empty string if the receipt is unsigned.

This property is read-only.

Data Type

String

receipt_to property (GISBSender Struct)

[1.6] Used to request a receipt.

Syntax

fn receipt_to(&self) -> Result<String, IPWorksEDIError> 
fn set_receipt_to(&self, value : &str) ->  Option<IPWorksEDIError> 
fn set_receipt_to_ref(&self, value : &String) ->  Option<IPWorksEDIError> 

Default Value

""

Remarks

Only supported for Version 1.6.

If this property is set, a Receipt-Notification-To form variable will be added to the request, and a receipt will be requested. Generally this should be the same as data_from.

By default, the struct will request a GISB-Acknowledgement-Receipt, signed with PGP and delivered synchronously in the HTTP reply. You may set receipt_security to request a different type of signature, or no signature at all.

Data Type

String

receipt_type property (GISBSender Struct)

[1.6] The type of receipt requested.

Syntax

fn receipt_type(&self) -> Result<String, IPWorksEDIError> 
fn set_receipt_type(&self, value : &str) ->  Option<IPWorksEDIError> 
fn set_receipt_type_ref(&self, value : &String) ->  Option<IPWorksEDIError> 

Default Value

"gisb-acknowledgement-receipt"

Remarks

Only supported for Version 1.6.

If receipt_to is set, the struct will request a receipt of the indicated type. Note that the only type of receipt readable by the struct is a gisb-acknowledgement-receipt, and only if using version 1.6 of the GISB/NAESB protocol.

The security settings for the receipt (signed or unsigned) may be configured by setting receipt_security.

Data Type

String

reply_headers property (GISBSender Struct)

The HTTP headers provided for the ResponseContent .

Syntax

fn reply_headers(&self) -> Result<String, IPWorksEDIError> 

Default Value

""

Remarks

The HTTP headers provided for the response_content.

This property is read-only.

Data Type

String

request_status property (GISBSender Struct)

The status of the request.

Syntax

fn request_status(&self) -> Result<String, IPWorksEDIError> 

Default Value

"ok"

Remarks

request_status will be determined from the server response after a post. If the request status is anything other than "ok" the struct will throw an exception. Note that servers are not required to process data immediately, and a request_status of "ok" is not a guarantee that the server was able to process your data.

The following is the complete list of error codes defined by the GISB 1.4 and NAESB 1.6 specifications.

The following is the complete list of error codes defined by the GISB 1.4 and NAESB 1.6 specification. Error codes only defined in version 1.6 are notated with "1.6" below, and errors that will be detected and reported automatically by the GISBReceiver struct are indicated with an asterisk.

The following is the complete list of error codes defined by the GISB 1.4 specification.

EEDM100*: Missing From Common Code Identifier Code

EEDM101*: Missing To Common Code Identifier Code

EEDM102*: Missing Input Format

EEDM103*: Missing Data File

EEDM104: Missing Transaction Set

EEDM105: Invalid From Common Code Identifier

EEDM106: Invalid To Common Code Identifier

EEDM107: Invalid Input Format

EEDM108: Invalid Transaction Set

EEDM109: No Parameters Supplied

EEDM110: (1.6) Invalid "version"

EEDM111: (1.6) Missing "version"

EEDM112: (1.6) "receipt-security-selection" not mutually agreed

EEDM113*: (1.6) Invalid "receipt-security-selection"

EEDM114: (1.6) Missing "receipt-disposition-to"

EEDM115: (1.6) Invalid "receipt-disposition-to"

EEDM116: (1.6) Missing "receipt-report-type"

EEDM117: (1.6) Invalid "receipt-report-type"

EEDM118: (1.6) Missing "receipt-security-selection"

EEDM119: (1.6) Mutually agreed element, refnum, not present

EEDM601: Public Key Invalid

EEDM602: File Not Encrypted

EEDM603: Encrypted File Truncated

EEDM604*: Encrypted File Not Signed Or Signature Not Matched

EEDM699: Decryption Error

EEDM701: EDM Party Not Associated With EDI Party

EEDM702: Data Structure Error

EEDM703: Data Set Exchange Not Established For Trading Partner

EEDM999: System Error

WEDM100: Transaction Set Sent Not Mutually Agreed

WEDM102: (1.6) "receipt-security-selection" not mutually agreed

WEDM103: (1.6) Missing "receipt-security-selection"

WEDM104: (1.6) Element refnum received; not mutually agreed; ignored

This property is read-only.

Data Type

String

response_content property (GISBSender Struct)

The response returned from the server.

Syntax

fn response_content(&self) -> Result<Vec<u8>, IPWorksEDIError> 

Default Value

""

Remarks

This property will be populated after a response is received from the server. If a receipt was requested this property will contain the receipt; otherwise this property will contain at least a small bit of HTML describing whether or not the transmission succeeded.

In case the receipt was signed, response_content will contain the unsigned receipt, together with its MIME headers.

Note that if a signature was requested but an unsigned receipt is received the struct will throw an exception.

This property is read-only.

Data Type

Vec<u8>

secret_keyring_data property (GISBSender Struct)

Secret keyring data.

Syntax

fn secret_keyring_data(&self) -> Result<Vec<u8>, IPWorksEDIError> 
fn set_secret_keyring_data(&self, value : Vec<u8>) ->  Option<IPWorksEDIError> 
fn set_secret_keyring_data_ref(&self, value : &[u8]) ->  Option<IPWorksEDIError> 

Default Value

""

Remarks

This property allows the secret keyring data to be specific in the form of a byte array. Use this in conjunction with public_keyring_data and the keyring will be loaded from this data instead of the homedir.

Data Type

Vec<u8>

sign_data property (GISBSender Struct)

Whether or not to sign the data.

Syntax

fn sign_data(&self) -> Result<bool, IPWorksEDIError> 
fn set_sign_data(&self, value : bool) ->  Option<IPWorksEDIError> 

Default Value

false

Remarks

If true, then the data will be signed before sending to the server.

Data Type

bool

ssl_accept_server_cert_effective_date property (GISBSender Struct)

The date on which this certificate becomes valid.

Syntax

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

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 (GISBSender Struct)

The date on which the certificate expires.

Syntax

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

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 (GISBSender Struct)

A comma-delimited list of extended key usage identifiers.

Syntax

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

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 (GISBSender Struct)

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

Syntax

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

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 (GISBSender Struct)

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

Syntax

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

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 (GISBSender Struct)

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

Syntax

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

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 (GISBSender Struct)

The issuer of the certificate.

Syntax

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

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 (GISBSender Struct)

The private key of the certificate (if available).

Syntax

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

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 (GISBSender Struct)

Whether a PrivateKey is available for the selected certificate.

Syntax

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

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 (GISBSender Struct)

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

Syntax

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

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 (GISBSender Struct)

The public key of the certificate.

Syntax

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

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 (GISBSender Struct)

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

Syntax

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

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 (GISBSender Struct)

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

Syntax

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

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 (GISBSender Struct)

The serial number of the certificate encoded as a string.

Syntax

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

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 (GISBSender Struct)

The text description of the certificate's signature algorithm.

Syntax

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

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 (GISBSender Struct)

The name of the certificate store for the client certificate.

Syntax

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

Default Value

"MY"

Remarks

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<u8>

ssl_accept_server_cert_store_password property (GISBSender 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, IPWorksEDIError> 
fn set_ssl_accept_server_cert_store_password(&self, value : &str) ->  Option<IPWorksEDIError> 
fn set_ssl_accept_server_cert_store_password_ref(&self, value : &String) ->  Option<IPWorksEDIError> 

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 (GISBSender Struct)

The type of certificate store for this certificate.

Syntax

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

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 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 (GISBSender Struct)

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

Syntax

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

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 (GISBSender Struct)

The MD5 hash of the certificate.

Syntax

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

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 (GISBSender Struct)

The SHA-1 hash of the certificate.

Syntax

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

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 (GISBSender Struct)

The SHA-256 hash of the certificate.

Syntax

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

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 (GISBSender Struct)

The text description of UsageFlags .

Syntax

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

Default Value

""

Remarks

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 (GISBSender Struct)

The flags that show intended use for the certificate.

Syntax

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

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 (GISBSender Struct)

The certificate's version number.

Syntax

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

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 (GISBSender Struct)

The subject of the certificate used for client authentication.

Syntax

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

Default Value

""

Remarks

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 (GISBSender Struct)

The certificate (PEM/Base64 encoded).

Syntax

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

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<u8>

ssl_cert_effective_date property (GISBSender Struct)

The date on which this certificate becomes valid.

Syntax

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

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 (GISBSender Struct)

The date on which the certificate expires.

Syntax

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

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 (GISBSender Struct)

A comma-delimited list of extended key usage identifiers.

Syntax

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

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 (GISBSender Struct)

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

Syntax

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

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 (GISBSender Struct)

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

Syntax

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

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 (GISBSender Struct)

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

Syntax

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

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 (GISBSender Struct)

The issuer of the certificate.

Syntax

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

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 (GISBSender Struct)

The private key of the certificate (if available).

Syntax

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

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 (GISBSender Struct)

Whether a PrivateKey is available for the selected certificate.

Syntax

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

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 (GISBSender Struct)

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

Syntax

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

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 (GISBSender Struct)

The public key of the certificate.

Syntax

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

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 (GISBSender Struct)

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

Syntax

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

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 (GISBSender Struct)

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

Syntax

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

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 (GISBSender Struct)

The serial number of the certificate encoded as a string.

Syntax

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

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 (GISBSender Struct)

The text description of the certificate's signature algorithm.

Syntax

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

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 (GISBSender Struct)

The name of the certificate store for the client certificate.

Syntax

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

Default Value

"MY"

Remarks

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<u8>

ssl_cert_store_password property (GISBSender 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, IPWorksEDIError> 
fn set_ssl_cert_store_password(&self, value : &str) ->  Option<IPWorksEDIError> 
fn set_ssl_cert_store_password_ref(&self, value : &String) ->  Option<IPWorksEDIError> 

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 (GISBSender Struct)

The type of certificate store for this certificate.

Syntax

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

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 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 (GISBSender Struct)

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

Syntax

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

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 (GISBSender Struct)

The MD5 hash of the certificate.

Syntax

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

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 (GISBSender Struct)

The SHA-1 hash of the certificate.

Syntax

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

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 (GISBSender Struct)

The SHA-256 hash of the certificate.

Syntax

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

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 (GISBSender Struct)

The text description of UsageFlags .

Syntax

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

Default Value

""

Remarks

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 (GISBSender Struct)

The flags that show intended use for the certificate.

Syntax

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

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 (GISBSender Struct)

The certificate's version number.

Syntax

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

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 (GISBSender Struct)

The subject of the certificate used for client authentication.

Syntax

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

Default Value

""

Remarks

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 (GISBSender Struct)

The certificate (PEM/Base64 encoded).

Syntax

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

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<u8>

ssl_provider property (GISBSender Struct)

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

Syntax

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

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:

Additional Notes

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 (GISBSender Struct)

The date on which this certificate becomes valid.

Syntax

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

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 (GISBSender Struct)

The date on which the certificate expires.

Syntax

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

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 (GISBSender Struct)

A comma-delimited list of extended key usage identifiers.

Syntax

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

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 (GISBSender Struct)

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

Syntax

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

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 (GISBSender Struct)

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

Syntax

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

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 (GISBSender Struct)

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

Syntax

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

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 (GISBSender Struct)

The issuer of the certificate.

Syntax

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

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 (GISBSender Struct)

The private key of the certificate (if available).

Syntax

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

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 (GISBSender Struct)

Whether a PrivateKey is available for the selected certificate.

Syntax

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

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 (GISBSender Struct)

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

Syntax

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

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 (GISBSender Struct)

The public key of the certificate.

Syntax

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

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 (GISBSender Struct)

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

Syntax

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

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 (GISBSender Struct)

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

Syntax

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

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 (GISBSender Struct)

The serial number of the certificate encoded as a string.

Syntax

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

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 (GISBSender Struct)

The text description of the certificate's signature algorithm.

Syntax

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

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 (GISBSender Struct)

The name of the certificate store for the client certificate.

Syntax

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

Default Value

"MY"

Remarks

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<u8>

ssl_server_cert_store_password property (GISBSender 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, IPWorksEDIError> 

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 (GISBSender Struct)

The type of certificate store for this certificate.

Syntax

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

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 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 (GISBSender Struct)

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

Syntax

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

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 (GISBSender Struct)

The MD5 hash of the certificate.

Syntax

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

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 (GISBSender Struct)

The SHA-1 hash of the certificate.

Syntax

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

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 (GISBSender Struct)

The SHA-256 hash of the certificate.

Syntax

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

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 (GISBSender Struct)

The text description of UsageFlags .

Syntax

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

Default Value

""

Remarks

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 (GISBSender Struct)

The flags that show intended use for the certificate.

Syntax

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

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 (GISBSender Struct)

The certificate's version number.

Syntax

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

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 (GISBSender Struct)

The subject of the certificate used for client authentication.

Syntax

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

Default Value

""

Remarks

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 (GISBSender Struct)

The certificate (PEM/Base64 encoded).

Syntax

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

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<u8>

subject property (GISBSender Struct)

The subject of the message.

Syntax

fn subject(&self) -> Result<String, IPWorksEDIError> 
fn set_subject(&self, value : &str) ->  Option<IPWorksEDIError> 
fn set_subject_ref(&self, value : &String) ->  Option<IPWorksEDIError> 

Default Value

""

Remarks

The optional human-readable subject of the message.

Data Type

String

timeout property (GISBSender Struct)

The timeout for the struct.

Syntax

fn timeout(&self) -> Result<i32, IPWorksEDIError> 
fn set_timeout(&self, value : i32) ->  Option<IPWorksEDIError> 

Default Value

60

Remarks

If the timeout property is set to 0, all operations will run uninterrupted until successful completion or an error condition is encountered.

If timeout is set to a positive value, the struct will wait for the operation to complete before returning control.

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 timeout property is 60 seconds.

Data Type

i32

transaction_id property (GISBSender Struct)

The transaction ID of the message.

Syntax

fn transaction_id(&self) -> Result<String, IPWorksEDIError> 

Default Value

""

Remarks

A unique ID for the transaction. In GISB the transaction_id will be generated by the server, so this property will be populated whenever you receive a response from the server.

This property is read-only.

Data Type

String

url property (GISBSender Struct)

The URL to post to.

Syntax

fn url(&self) -> Result<String, IPWorksEDIError> 
fn set_url(&self, value : &str) ->  Option<IPWorksEDIError> 
fn set_url_ref(&self, value : &String) ->  Option<IPWorksEDIError> 

Default Value

""

Remarks

SSL will be used if and only if the URL scheme is "https". Note that generally signed, unencrypted messages would be sent using SSL, as encrypting the message would be redundant.

Data Type

String

user_agent property (GISBSender Struct)

Information about the user agent.

Syntax

fn user_agent(&self) -> Result<String, IPWorksEDIError> 
fn set_user_agent(&self, value : &str) ->  Option<IPWorksEDIError> 
fn set_user_agent_ref(&self, value : &String) ->  Option<IPWorksEDIError> 

Default Value

"IPWorks EDI GISBSender Component - www.nsoftware.com"

Remarks

Override the default with the name and version of your software.

Data Type

String

config method (GISBSender Struct)

Sets or retrieves a configuration setting.

Syntax

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

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.

do_events method (GISBSender Struct)

This method processes events from the internal message queue.

Syntax

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

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.

post method (GISBSender Struct)

Post data to the server, and check the receipt.

Syntax

fn post(&self) -> Result<(), IPWorksEDIError>

Remarks

post will generate the request and post it to the server. The reply will be checked; if a receipt was requested it will be validated, and any response will be checked for error messages.

reset method (GISBSender Struct)

Resets the state of the control.

Syntax

fn reset(&self) -> Result<(), IPWorksEDIError>

Remarks

Resets all HTTP headers as well as edi_data, etc. After invoking this method the struct may be reused as if it were newly created.

set_pgp_param method (GISBSender Struct)

Sets a parameter in the PGP provider.

Syntax

fn set_pgp_param(&self, name : &str, value : &str) -> Result<(), IPWorksEDIError>

Remarks

Invoke set_pgp_param to set parameters of your PGP provider. Please refer to the documentation provided with the PGP provider for the parameters required.

The following table defines possible values that may be passed to the set_pgp_param.

on_connected event (GISBSender Struct)

Fired immediately after a connection completes (or fails).

Syntax

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

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

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

Remarks

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 Transmission Control Protocol (TCP)/IP stack. description contains a description of this code. The value of status_code is equal to the value of the error.

Please refer to the Error Codes section for more information.

on_disconnected event (GISBSender Struct)

Fired when a connection is closed.

Syntax

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

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

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

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_end_transfer event (GISBSender Struct)

Fired when a document finishes transferring.

Syntax

// GISBSenderEndTransferEventArgs carries the GISBSender EndTransfer event's parameters.
pub struct GISBSenderEndTransferEventArgs {
  fn direction(&self) -> i32
}

// GISBSenderEndTransferEvent defines the signature of the GISBSender EndTransfer event's handler function.
pub trait GISBSenderEndTransferEvent {
  fn on_end_transfer(&self, sender : GISBSender, e : &mut GISBSenderEndTransferEventArgs);
}

impl <'a> GISBSender<'a> {
  pub fn on_end_transfer(&self) -> &'a dyn GISBSenderEndTransferEvent;
  pub fn set_on_end_transfer(&mut self, value : &'a dyn GISBSenderEndTransferEvent);
  ...
}

Remarks

This event is fired first when the client finishes sending data to the server (in a POST or PUT request) and then when the document text finishes transferring from the server to the local host.

The Direction parameter shows whether the client (0) or the server (1) is sending the data.

on_error event (GISBSender Struct)

Fired when information is available about errors during data delivery.

Syntax

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

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

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

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 (GISBSender Struct)

Fired every time a header line comes in.

Syntax

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

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

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

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_log event (GISBSender Struct)

Fired with log information while processing a message.

Syntax

// GISBSenderLogEventArgs carries the GISBSender Log event's parameters.
pub struct GISBSenderLogEventArgs {
  fn log_type(&self) -> &String
  fn log_message(&self) -> &[u8]
}

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

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

Remarks

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

Log messages available through this event correspond to log files written to log_directory. This event provides a way to obtain log messages without relying on files on disk. This event fires regardless of the value of log_directory (i.e. when log_directory is empty the event will still fire).

The LogMessage event parameter holds the raw log data.

The LogType event parameter indicates the type of log. Possible values are:

on_set_cookie event (GISBSender Struct)

Fired for every cookie set by the server.

Syntax

// GISBSenderSetCookieEventArgs carries the GISBSender SetCookie event's parameters.
pub struct GISBSenderSetCookieEventArgs {
  fn name(&self) -> &String
  fn value(&self) -> &String
  fn expires(&self) -> &String
  fn domain(&self) -> &String
  fn path(&self) -> &String
  fn secure(&self) -> bool
}

// GISBSenderSetCookieEvent defines the signature of the GISBSender SetCookie event's handler function.
pub trait GISBSenderSetCookieEvent {
  fn on_set_cookie(&self, sender : GISBSender, e : &mut GISBSenderSetCookieEventArgs);
}

impl <'a> GISBSender<'a> {
  pub fn on_set_cookie(&self) -> &'a dyn GISBSenderSetCookieEvent;
  pub fn set_on_set_cookie(&mut self, value : &'a dyn GISBSenderSetCookieEvent);
  ...
}

Remarks

This event is fired for every Set-Cookie: header received from the HTTP server.

The name parameter contains the name of the cookie, with the corresponding value supplied in the value parameter.

The expires parameter contains an expiration time for the cookie (if provided by the server). The time format used is "Weekday, DD-Mon-YY HH:MM:SS GMT". If the server does not provide an expiration time, the expires parameter will be an empty string. In this case, the convention is to drop the cookie at the end of the session.

The domain parameter contains a domain name to limit the cookie to (if provided by the server). If the server does not provide a domain name, the domain parameter will be an empty string. The convention in this case is to use the server specified in the URL (url_server) as the cookie domain.

The path parameter contains a path name to limit the cookie to (if provided by the server). If the server does not provide a cookie path, the path parameter will be an empty string. The convention in this case is to use the path specified in the URL (url_path) as the cookie path.

The secure parameter specifies whether the cookie is secure. If the value of this parameter is True, the cookie value must be submitted only through a secure (HTTPS) connection.

on_ssl_server_authentication event (GISBSender Struct)

Fired after the server presents its certificate to the client.

Syntax

// GISBSenderSSLServerAuthenticationEventArgs carries the GISBSender SSLServerAuthentication event's parameters.
pub struct GISBSenderSSLServerAuthenticationEventArgs {
  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)
}

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

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

Remarks

This event is where the client can decide whether to continue with the connection process or not. 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 to continue or not.

When Accept is False, Status shows why the verification failed (otherwise, Status contains the string "OK").

on_ssl_status event (GISBSender Struct)

Fired when secure connection progress messages are available.

Syntax

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

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

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

Remarks

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

on_start_transfer event (GISBSender Struct)

Fired when a document starts transferring (after the headers).

Syntax

// GISBSenderStartTransferEventArgs carries the GISBSender StartTransfer event's parameters.
pub struct GISBSenderStartTransferEventArgs {
  fn direction(&self) -> i32
}

// GISBSenderStartTransferEvent defines the signature of the GISBSender StartTransfer event's handler function.
pub trait GISBSenderStartTransferEvent {
  fn on_start_transfer(&self, sender : GISBSender, e : &mut GISBSenderStartTransferEventArgs);
}

impl <'a> GISBSender<'a> {
  pub fn on_start_transfer(&self) -> &'a dyn GISBSenderStartTransferEvent;
  pub fn set_on_start_transfer(&mut self, value : &'a dyn GISBSenderStartTransferEvent);
  ...
}

Remarks

This event is fired first when the client starts sending data to the server (in a POST or PUT request) and then when the document text starts transferring from the server to the local host.

The Direction parameter shows whether the client (0) or the server (1) is sending the data.

on_transfer event (GISBSender Struct)

Fired while a document transfers (delivers document).

Syntax

// GISBSenderTransferEventArgs carries the GISBSender Transfer event's parameters.
pub struct GISBSenderTransferEventArgs {
  fn direction(&self) -> i32
  fn bytes_transferred(&self) -> i64
  fn percent_done(&self) -> i32
  fn text(&self) -> &[u8]
}

// GISBSenderTransferEvent defines the signature of the GISBSender Transfer event's handler function.
pub trait GISBSenderTransferEvent {
  fn on_transfer(&self, sender : GISBSender, e : &mut GISBSenderTransferEventArgs);
}

impl <'a> GISBSender<'a> {
  pub fn on_transfer(&self) -> &'a dyn GISBSenderTransferEvent;
  pub fn set_on_transfer(&mut self, value : &'a dyn GISBSenderTransferEvent);
  ...
}

Remarks

The text parameter contains the portion of the document text being received. It is empty if data are being posted to the server.

The bytes_transferred parameter contains the number of bytes transferred in this direction since the beginning of the document text (excluding HTTP response headers).

The Direction parameter shows whether the client (0) or the server (1) is sending the data.

The PercentDone parameter shows the progress of the transfer in the corresponding direction. If PercentDone can not be calculated the value will be -1.

NOTE: Events are not re-entrant. Performing time-consuming operations within this event will prevent it from firing again in a timely manner and may affect overall performance.

Config Settings (GISBSender Struct)

The struct 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 struct, access to these internal properties is provided through the config method.

GISBSender Config Settings

Base Config Settings

Trappable Errors (GISBSender Struct)

GISBSender Errors

MIME Errors

HTTP Errors

The class may also return one of the following error codes, which are inherited from other classes.

TCPClient Errors

TCP/IP Errors