GISBSender Class

Properties   Methods   Events   Config Settings   Errors  

The GISBSender class 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, DataFrom, DataTo, URL, Data, and EDIType. 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 SignData and EncryptData properties to true. The class does not itself implement PGP, instead it uses a

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

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 SSLAcceptServerCert or trap the SSLServerAuthentication 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 ReceiptTo property. The ReceiptType and ReceiptSecurity properties may be used to customize the receipt request; by default, the class 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 class.

Property List

---

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

Method List

---

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

Event List

---

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

Config Settings

---

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

Cookies Property (GISBSender Class)

This property includes a collection of cookies.

Syntax

public HTTPCookieList getCookies();


public void setCookies(HTTPCookieList cookies);

Remarks

This property contains a collection of cookies. To add cookies to outgoing HTTP requests, add cookies (of type HTTPCookie) to this collection.

To see cookies that are set by the server, use the SetCookie event, which displays the cookies and their properties as set by the server. Those cookies also are added to Cookies.

MaxHTTPCookies can be used to control the maximum number of cookies saved.

This collection is indexed from 0 to size -1.

This property is not available at design time.

Please refer to the HTTPCookie type for a complete list of fields.

DataElements Property (GISBSender Class)

Collection of extra data elements for the outgoing request.

Syntax

public GISBElementList getDataElements();


public void setDataElements(GISBElementList dataElements);

Remarks

When you Post to the server the data elements in DataElements will be added to the standard data elements and included with the request.

The following data elements are configured using the appropriate properties, will be added automatically by the class, and should not be included in DataElements:

from, to, receipt-disposition-to, receipt-report-type, input-format, input-data, receipt-security-selection.

This property is not available at design time.

Please refer to the GISBElement type for a complete list of fields.

DataFrom Property (GISBSender Class)

The identity of the sending system.

Syntax

public String getDataFrom();


public void setDataFrom(String dataFrom);

Default Value

""

Remarks

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

DataTo Property (GISBSender Class)

The identity of the receiving system.

Syntax

public String getDataTo();


public void setDataTo(String dataTo);

Default Value

""

Remarks

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

EncryptData Property (GISBSender Class)

Whether or not to encrypt the data.

Syntax

public boolean isEncryptData();


public void setEncryptData(boolean encryptData);

Default Value

False

Remarks

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

Firewall Property (GISBSender Class)

A set of properties related to firewall access.

Syntax

public Firewall getFirewall();


public void setFirewall(Firewall firewall);

Remarks

This is a Firewall-type property, which contains fields describing the firewall through which the class will attempt to connect.

Please refer to the Firewall type for a complete list of fields.

GISBData Property (GISBSender Class)

The EDI Payload of the message.

Syntax

public GISBData getGISBData();


public void setGISBData(GISBData GISBData);

Remarks

The EDI Payload of the message.

This property is not available at design time.

Please refer to the GISBData type for a complete list of fields.

GISBVersion Property (GISBSender Class)

The version of GISB/NAESB being used.

Syntax

public String getGISBVersion();


public void setGISBVersion(String GISBVersion);

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.

LocalHost Property (GISBSender Class)

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

Syntax

public String getLocalHost();


public void setLocalHost(String localHost);

Default Value

""

Remarks

The LocalHost 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 multi-homed hosts (machines with more than one IP interface) setting LocalHost to the value of an interface will make the class initiate connections (or accept in the case of server classs) only through that interface.

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

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

The LocalHost 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 multi-homed hosts (machines with more than one IP interface) setting LocalHost to the value of an interface will make the class initiate connections (or accept in the case of server classs) only through that interface.

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

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

LogDirectory Property (GISBSender Class)

The path to a directory for logging.

Syntax

public String getLogDirectory();


public void setLogDirectory(String logDirectory);

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 class will log the original EDI data, the complete text of the outgoing request and the incoming response.

The class 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 class. 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 LogFile 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.

LogFile Property (GISBSender Class)

The log file written.

Syntax

public String getLogFile();

Default Value

""

Remarks

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

This property is read-only.

Proxy Property (GISBSender Class)

A set of properties related to proxy access.

Syntax

public Proxy getProxy();


public void setProxy(Proxy proxy);

Remarks

This property contains fields describing the proxy through which the class will attempt to connect.

Please refer to the Proxy type for a complete list of fields.

PublicKeyringData Property (GISBSender Class)

Public keyring data.

Syntax

public byte[] getPublicKeyringData();


public void setPublicKeyringData(byte[] publicKeyringData);

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 SecretKeyringData and the keyring will be loaded from this data instead of the homedir.

ReceiptSecurity Property (GISBSender Class)

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

Syntax

public String getReceiptSecurity();


public void setReceiptSecurity(String receiptSecurity);

Default Value

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

Remarks

Only supported for Version 1.6.

By default, the class 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 ReceiptSecurity 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.

ReceiptSigningProtocol Property (GISBSender Class)

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

Syntax

public String getReceiptSigningProtocol();

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.

ReceiptTo Property (GISBSender Class)

[1.6] Used to request a receipt.

Syntax

public String getReceiptTo();


public void setReceiptTo(String receiptTo);

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

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

ReceiptType Property (GISBSender Class)

[1.6] The type of receipt requested.

Syntax

public String getReceiptType();


public void setReceiptType(String receiptType);

Default Value

"gisb-acknowledgement-receipt"

Remarks

Only supported for Version 1.6.

If ReceiptTo is set, the class will request a receipt of the indicated type. Note that the only type of receipt readable by the class 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 ReceiptSecurity.

ReplyHeaders Property (GISBSender Class)

The HTTP headers provided for the Response .

Syntax

public String getReplyHeaders();

Default Value

""

Remarks

The HTTP headers provided for the Response.

This property is read-only.

RequestStatus Property (GISBSender Class)

The status of the request.

Syntax

public String getRequestStatus();

Default Value

"ok"

Remarks

RequestStatus will be determined from the server response after a Post. If the request status is anything other than "ok" the class will throw an exception. Note that servers are not required to process data immediately, and a RequestStatus 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 class 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.

ResponseContent Property (GISBSender Class)

The response returned from the server.

Syntax

public byte[] getResponseContent();

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, ResponseContent will contain the unsigned receipt, together with its MIME headers.

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

This property is read-only.

SecretKeyringData Property (GISBSender Class)

Secret keyring data.

Syntax

public byte[] getSecretKeyringData();


public void setSecretKeyringData(byte[] secretKeyringData);

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 PublicKeyringData and the keyring will be loaded from this data instead of the homedir.

SignData Property (GISBSender Class)

Whether or not to sign the data.

Syntax

public boolean isSignData();


public void setSignData(boolean signData);

Default Value

False

Remarks

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

SSLAcceptServerCert Property (GISBSender Class)

Instructs the class to unconditionally accept the server certificate that matches the supplied certificate.

Syntax

public Certificate getSSLAcceptServerCert();


public void setSSLAcceptServerCert(Certificate SSLAcceptServerCert);

Remarks

If it finds any issues with the certificate presented by the server, the class will normally terminate the connection with an error.

You may override this behavior by supplying a value for SSLAcceptServerCert. If the certificate supplied in SSLAcceptServerCert is the same as the certificate presented by the server, then the server certificate is accepted unconditionally, and the connection will continue normally.

Please note that this functionality is provided only for cases where you otherwise know that you are communicating with the right server. If used improperly, this property may create a security breach. Use it at your own risk.

Please refer to the Certificate type for a complete list of fields.

SSLCert Property (GISBSender Class)

The certificate to be used during SSL negotiation.

Syntax

public Certificate getSSLCert();


public void setSSLCert(Certificate SSLCert);

Remarks

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

Please refer to the Certificate type for a complete list of fields.

SSLProvider Property (GISBSender Class)

This specifies the SSL/TLS implementation to use.

Syntax

public int getSSLProvider();


public void setSSLProvider(int SSLProvider);


Enumerated values:
  public final static int sslpAutomatic = 0;
  public final static int sslpPlatform = 1;
  public final static int sslpInternal = 2;

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 class 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:

Additional Notes

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

When Automatic is selected the platform implementation is used by default. When TLS 1.3 is enabled via SSLEnabledProtocols the internal implementation is used.

SSLServerCert Property (GISBSender Class)

The server certificate for the last established connection.

Syntax

public Certificate getSSLServerCert();

Remarks

SSLServerCert contains the server certificate for the last established connection.

SSLServerCert is reset every time a new connection is attempted.

This property is read-only.

Please refer to the Certificate type for a complete list of fields.

Subject Property (GISBSender Class)

The subject of the message.

Syntax

public String getSubject();


public void setSubject(String subject);

Default Value

""

Remarks

The optional human-readable subject of the message.

Timeout Property (GISBSender Class)

A timeout for the class.

Syntax

public int getTimeout();


public void setTimeout(int timeout);

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 class will wait for the operation to complete before returning control.

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

If Timeout expires, and the operation is not yet complete, the class throws an exception.

Please note that by default, all timeouts are inactivity timeouts, i.e. 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.

TransactionId Property (GISBSender Class)

The transaction ID of the message.

Syntax

public String getTransactionId();

Default Value

""

Remarks

A unique ID for the transaction. In GISB the TransactionId 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.

URL Property (GISBSender Class)

The URL to post to.

Syntax

public String getURL();


public void setURL(String URL);

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.

UserAgent Property (GISBSender Class)

Information about the user agent.

Syntax

public String getUserAgent();


public void setUserAgent(String userAgent);

Default Value

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

Remarks

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

Config Method (Gisbsender Class)

Sets or retrieves a configuration setting.

Syntax

public String config(String configurationString);

Remarks

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

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

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

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

DoEvents Method (Gisbsender Class)

Processes events from the internal message queue.

Syntax

public void doEvents();

Remarks

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

Post Method (Gisbsender Class)

Post data to the server, and check the receipt.

Syntax

public void post();

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

Resets the state of the control.

Syntax

public void reset();

Remarks

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

SetPGPParam Method (Gisbsender Class)

Sets a parameter in the PGP provider.

Syntax

public void setPGPParam(String name, String value);

Remarks

Invoke SetPGPParam 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 SetPGPParam.

SetUploadStream Method (Gisbsender Class)

Sets the stream to be uploaded to the server.

Syntax

public void setUploadStream(java.io.InputStream uploadStream);

Remarks

If you specify EDIData the data will be taken from there instead. Otherwise the contents of the stream will be written to EDIData before transmission. The stream should be open and normally set to position 0.

The class will automatically close this stream if CloseStreamAfterTransfer is true (default). If the stream is closed, you will need to call SetUploadStream again before the next send.

The content of the stream will be read from the current position all the way to the end.

Connected Event (Gisbsender Class)

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

Syntax

public class DefaultGisbsenderEventListener implements GisbsenderEventListener {
  ...
  public void connected(GisbsenderConnectedEvent e) {}
  ...
}

public class GisbsenderConnectedEvent {
  public int statusCode;
  public String description;
}

Remarks

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

If the connection fails, StatusCode has the error code returned by the Transmission Control Protocol (TCP)/IP stack. Description contains a description of this code. The value of StatusCode is equal to the value of the error.

Please refer to the Error Codes section for more information.

Disconnected Event (Gisbsender Class)

This event is fired when a connection is closed.

Syntax

public class DefaultGisbsenderEventListener implements GisbsenderEventListener {
  ...
  public void disconnected(GisbsenderDisconnectedEvent e) {}
  ...
}

public class GisbsenderDisconnectedEvent {
  public int statusCode;
  public String description;
}

Remarks

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

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

Please refer to the Error Codes section for more information.

EndTransfer Event (Gisbsender Class)

This event is fired when a document finishes transferring.

Syntax

public class DefaultGisbsenderEventListener implements GisbsenderEventListener {
  ...
  public void endTransfer(GisbsenderEndTransferEvent e) {}
  ...
}

public class GisbsenderEndTransferEvent {
  public int direction;
}

Remarks

The EndTransfer 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.

Error Event (Gisbsender Class)

Fired when information is available about errors during data delivery.

Syntax

public class DefaultGisbsenderEventListener implements GisbsenderEventListener {
  ...
  public void error(GisbsenderErrorEvent e) {}
  ...
}

public class GisbsenderErrorEvent {
  public int errorCode;
  public String description;
}

Remarks

The Error event is fired in case of exceptional conditions during message processing. Normally the class throws an exception.

The ErrorCode 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.

Header Event (Gisbsender Class)

This event is fired every time a header line comes in.

Syntax

public class DefaultGisbsenderEventListener implements GisbsenderEventListener {
  ...
  public void header(GisbsenderHeaderEvent e) {}
  ...
}

public class GisbsenderHeaderEvent {
  public String field;
  public String value;
}

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

Log Event (Gisbsender Class)

Fired with log information while processing a message.

Syntax

public class DefaultGisbsenderEventListener implements GisbsenderEventListener {
  ...
  public void log(GisbsenderLogEvent e) {}
  ...
}

public class GisbsenderLogEvent {
  public String logType;
  public byte[] logMessage;
}

Remarks

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

Log messages available through this event correspond to log files written to LogDirectory. This event provides a way to obtain log messages without relying on files on disk. This event fires regardless of the value of LogDirectory (i.e. when LogDirectory 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:

SetCookie Event (Gisbsender Class)

This event is fired for every cookie set by the server.

Syntax

public class DefaultGisbsenderEventListener implements GisbsenderEventListener {
  ...
  public void setCookie(GisbsenderSetCookieEvent e) {}
  ...
}

public class GisbsenderSetCookieEvent {
  public String name;
  public String value;
  public String expires;
  public String domain;
  public String path;
  public boolean secure;
}

Remarks

The SetCookie 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 (URLServer) 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 (URLPath) 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.

SSLServerAuthentication Event (Gisbsender Class)

Fired after the server presents its certificate to the client.

Syntax

public class DefaultGisbsenderEventListener implements GisbsenderEventListener {
  ...
  public void SSLServerAuthentication(GisbsenderSSLServerAuthenticationEvent e) {}
  ...
}

public class GisbsenderSSLServerAuthenticationEvent {
  public byte[] certEncoded;
  public String certSubject;
  public String certIssuer;
  public String status;
  public boolean accept;
}

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

SSLStatus Event (Gisbsender Class)

Fired when secure connection progress messages are available.

Syntax

public class DefaultGisbsenderEventListener implements GisbsenderEventListener {
  ...
  public void SSLStatus(GisbsenderSSLStatusEvent e) {}
  ...
}

public class GisbsenderSSLStatusEvent {
  public String message;
}

Remarks

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

StartTransfer Event (Gisbsender Class)

This event is fired when a document starts transferring (after the headers).

Syntax

public class DefaultGisbsenderEventListener implements GisbsenderEventListener {
  ...
  public void startTransfer(GisbsenderStartTransferEvent e) {}
  ...
}

public class GisbsenderStartTransferEvent {
  public int direction;
}

Remarks

The StartTransfer 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.

Transfer Event (Gisbsender Class)

This event is fired while a document transfers (delivers document).

Syntax

public class DefaultGisbsenderEventListener implements GisbsenderEventListener {
  ...
  public void transfer(GisbsenderTransferEvent e) {}
  ...
}

public class GisbsenderTransferEvent {
  public int direction;
  public long bytesTransferred;
  public int percentDone;
  public byte[] text;
}

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

Certificate Type

This is the digital certificate being used.

Remarks

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

Fields

Constructors

public Certificate();

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

public Certificate( certificateFile);

Opens CertificateFile and reads out the contents as an X.509 public key.

public Certificate( certificateData);

Parses CertificateData as an X.509 public key.

public Certificate( certStoreType,  store,  storePassword,  subject);

CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. Store is a file containing the certificate store. StorePassword is the password used to protect the store. After the store has been successfully opened, the class will attempt to find the certificate identified by Subject . This can be either a complete or a substring match of the X.509 certificate's subject Distinguished Name (DN).

public Certificate( certStoreType,  store,  storePassword,  subject,  configurationString);

CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. Store is a file containing the certificate store. StorePassword is the password used to protect the store. ConfigurationString is a newline separated list of name-value pairs that may be used to modify the default behavior. Possible values include "PersistPFXKey", which shows whether or not the PFX key is persisted after performing operations with the private key. This correlates to the PKCS12_NO_PERSIST_KEY CryptoAPI option. The default value is True (the key is persisted). "Thumbprint" - an MD5, SHA-1, or SHA-256 thumbprint of the certificate to load. When specified, this value is used to select the certificate in the store. This is applicable to cstUser, cstMachine, cstPublicKeyFile, and cstPFXFile store types. "UseInternalSecurityAPI" shows whether the platform (default) or the internal security API is used when performing certificate-related operations. After the store has been successfully opened, the class will attempt to find the certificate identified by Subject . This can be either a complete or a substring match of the X.509 certificate's subject Distinguished Name (DN).

public Certificate( certStoreType,  store,  storePassword,  encoded);

CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. Store is a file containing the certificate store. StorePassword is the password used to protect the store. After the store has been successfully opened, the class will load Encoded as an X.509 certificate and search the opened store for a corresponding private key.

public Certificate( certStoreType,  storeBlob,  storePassword,  subject);

CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. StoreBlob is a string (binary- or Base64-encoded) containing the certificate data. StorePassword is the password used to protect the store. After the store has been successfully opened, the class will attempt to find the certificate identified by Subject . This can be either a complete or a substring match of the X.509 certificate's subject Distinguished Name (DN).

public Certificate( certStoreType,  storeBlob,  storePassword,  subject,  configurationString);

CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. StoreBlob is a string (binary- or Base64-encoded) containing the certificate data. StorePassword is the password used to protect the store. After the store has been successfully opened, the class will attempt to find the certificate identified by Subject . This can be either a complete or a substring match of the X.509 certificate's subject Distinguished Name (DN).

public Certificate( certStoreType,  storeBlob,  storePassword,  encoded);

CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. Store is a string (binary- or Base64-encoded) containing the certificate store. StorePassword is the password used to protect the store. After the store has been successfully opened, the class will load Encoded as an X.509 certificate and search the opened store for a corresponding private key.

Firewall Type

The firewall the class will connect through.

Remarks

When connecting through a firewall, this type is used to specify different properties of the firewall, such as the firewall Host and the FirewallType.

Fields

Constructors

public Firewall();

GISBData Type

The EDI payload of the message.

Remarks

The EDI payload of the message.

Fields

Constructors

public GISBData();

public GISBData( data,  EDIType);

public GISBData( filename,  EDIType);

GISBElement Type

A name-value pair for extra data to be sent with a GISB message.

Remarks

A name-value pair for extra data to be sent with a GISB message.

Fields

Constructors

public GISBElement();

public GISBElement( name,  value);

HTTPCookie Type

An HTTP cookie can be either sent to or received from the server.

Remarks

An HTTP cookie can store the cookies that are to be sent to the server. It also may store the cookies sent by the server.

Cookies that are to be sent to the server must have the Name and Value fields supplied before submitting the URL. When the SetCookie event is fired, however, all of the fields of an HTTPCookie are filled out accordingly.

Fields

Constructors

public HTTPCookie();

public HTTPCookie( name,  value);

Proxy Type

The proxy the class will connect to.

Remarks

When connecting through a proxy, this type is used to specify different properties of the proxy, such as the Server and the AuthScheme.

Fields

Constructors

public Proxy();

public Proxy( server,  port);

public Proxy( server,  port,  user,  password);

Config Settings (Gisbsender Class)

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

GISBSender Config Settings

Base Config Settings

Trappable Errors (Gisbsender Class)

GISBSender Errors

	651   Required field unspecified (by client).
	662   Invalid request status reported by server (details follow).
	664   Data was not processed by PGP.
	701   Unable to write log file.
	713   Unable to decompress message.

MIME Errors

	3   Can't create the file for write (illegal name or disk is write-protected).
	4   Can't open the file for read (doesn't exist?).
	5   Can't read from file.
	6   Can't write to file (disk full?).
	280   Invalid Part Index.
	281   Unknown MIME type.
	282   No MIME-boundary found.
	283   No file given.
	284   The class is busy.
	285   Can't create a temporary file to decode the data.
	286   Can't read Message file.
	287   No header separator found.
	289   No separator found.
	290   Input stream must have seeking enabled.

HTTP Errors

	118   Firewall Error. Error description contains detailed message.
	143   Busy executing current method.
	151   HTTP protocol error. The error message has the server response.
	152   No server specified in URL
	153   Specified URLScheme is invalid.
	155   Range operation is not supported by server.
	156   Invalid cookie index (out of range).
	301   Interrupted.
	302   Can't open AttachedFile.

TCPClient Errors

	100   You cannot change the RemotePort at this time. A connection is in progress.
	101   You cannot change the RemoteHost (Server) at this time. A connection is in progress.
	102   The RemoteHost address is invalid (0.0.0.0).
	104   Already connected. If you want to reconnect, close the current connection first.
	106   You cannot change the LocalPort at this time. A connection is in progress.
	107   You cannot change the LocalHost at this time. A connection is in progress.
	112   You cannot change MaxLineLength at this time. A connection is in progress.
	116   RemotePort cannot be zero. Please specify a valid service port number.
	117   You cannot change the UseConnection option while the class is active.
	135   Operation would block.
	201   Timeout.
	211   Action impossible in control's present state.
	212   Action impossible while not connected.
	213   Action impossible while listening.
	301   Timeout.
	303   Could not open file.
	434   Unable to convert string to selected CodePage.
	1105   Already connecting. If you want to reconnect, close the current connection first.
	1117   You need to connect first.
	1119   You cannot change the LocalHost at this time. A connection is in progress.
	1120   Connection dropped by remote host.

TCP/IP Errors

	10004   [10004] Interrupted system call.
	10009   [10009] Bad file number.
	10013   [10013] Access denied.
	10014   [10014] Bad address.
	10022   [10022] Invalid argument.
	10024   [10024] Too many open files.
	10035   [10035] Operation would block.
	10036   [10036] Operation now in progress.
	10037   [10037] Operation already in progress.
	10038   [10038] Socket operation on non-socket.
	10039   [10039] Destination address required.
	10040   [10040] Message too long.
	10041   [10041] Protocol wrong type for socket.
	10042   [10042] Bad protocol option.
	10043   [10043] Protocol not supported.
	10044   [10044] Socket type not supported.
	10045   [10045] Operation not supported on socket.
	10046   [10046] Protocol family not supported.
	10047   [10047] Address family not supported by protocol family.
	10048   [10048] Address already in use.
	10049   [10049] Can't assign requested address.
	10050   [10050] Network is down.
	10051   [10051] Network is unreachable.
	10052   [10052] Net dropped connection or reset.
	10053   [10053] Software caused connection abort.
	10054   [10054] Connection reset by peer.
	10055   [10055] No buffer space available.
	10056   [10056] Socket is already connected.
	10057   [10057] Socket is not connected.
	10058   [10058] Can't send after socket shutdown.
	10059   [10059] Too many references, can't splice.
	10060   [10060] Connection timed out.
	10061   [10061] Connection refused.
	10062   [10062] Too many levels of symbolic links.
	10063   [10063] File name too long.
	10064   [10064] Host is down.
	10065   [10065] No route to host.
	10066   [10066] Directory not empty
	10067   [10067] Too many processes.
	10068   [10068] Too many users.
	10069   [10069] Disc Quota Exceeded.
	10070   [10070] Stale NFS file handle.
	10071   [10071] Too many levels of remote in path.
	10091   [10091] Network subsystem is unavailable.
	10092   [10092] WINSOCK DLL Version out of range.
	10093   [10093] Winsock not loaded yet.
	11001   [11001] Host not found.
	11002   [11002] Non-authoritative 'Host not found' (try again or check DNS setup).
	11003   [11003] Non-recoverable errors: FORMERR, REFUSED, NOTIMP.
	11004   [11004] Valid name, no data record (check DNS setup).