# GISBReceiver Component

The GISBReceiver component is used to process EDI messages and generate receipts.

## Syntax

```text
nsoftware.IPWorksEDI.GISBReceiver
```

## Remarks

The GISBReceiver implements server-side processing of EDI messages, as specified in versions 1.4 and 1.6 of the GISB/NAESB specification. It can be used to decrypt and verify incoming messages; in version 1.6, it may additionally be used to generate signed receipts. The component is designed to be easily incorporated into an HTTP server, and features custom functionality for server environments such as ASP.NET.

*Basic Operation*

The [ProcessRequest](#processrequest-method-gisbreceiver-component) method is used to process incoming messages and generate responses. [ProcessRequest](#processrequest-method-gisbreceiver-component) will parse the form data, determine [DataFrom](#datafrom-property-gisbreceiver-component) and [DataTo](#datato-property-gisbreceiver-component), and then attempt to process any signed or encrypted data using PGP.

The following table defines possible values that may be passed to the [SetPGPParam](#setpgpparam-method-gisbreceiver-component).

|  |  |
| --- | --- |
| homedir | The directory containing the public keyring, secret keyring and trust database. Please note this defaults to the application preferences directory of the user, hence if the GNUPG provider is being used from a ASP.NET application, homedir should be specified. |
| passphrase | The passphrase to access the secret keys in the secret-keyring. |
| userid | The identifier used to identify a secret key within the secret-keyring. Note: When decrypting if this value is not specified the component will attempt to find the key within the keyring automatically based on information available in the PGP message itself. |
| recipient-userid | The identifier used to identify a public key within the public keyring. Note: When verifying a signature if this value is not specified the component will attempt to find the key within the keyring automatically based on information available in the PGP message itself. |
| timeout | The timeout in milliseconds that the provider will wait for a response from the OpenPGP executable. The default is 5000 (5 seconds). |
| usetempfile | If set to "true" the provider will write data to be processed to a temporary file on disk. This is useful when working with large files or binary files. |
| signingalgorithm | The signing algorithm to use when SignData is True. Possible values are: SHA1 MD5 SHA256 (default) SHA384 SHA512 SHA224 RIPEMD160 |
| encryptingalgorithm | The encrypting algorithm to use when EncryptData is True. Possible values are: CAST5 3DES AES256 AES192 AES128 (default) BLOWFISH TWOFISH IDEA |
| compressionmethod | The compression method to use. Possible values are: zip (default) zlib bzip2 none |

Finally, the component will generate a [Response](#response-property-gisbreceiver-component) which you may send to the client with [SendResponse](#sendresponse-method-gisbreceiver-component).

The most important part of the [Response](#response-property-gisbreceiver-component) is the [RequestStatus](#requeststatus-property-gisbreceiver-component); this property will contain either "ok" or an error message to be returned to the requesting client. By default the component will accept any post that conforms to the standard. If you want to be more restrictive you should first invoke [ParseRequest](#parserequest-method-gisbreceiver-component) to determine the sender, check the message security used, and extract the EDI data. If there is a problem you may then set [RequestStatus](#requeststatus-property-gisbreceiver-component) to an error before calling [CreateResponse](#createresponse-method-gisbreceiver-component). Please see the [RequestStatus](#requeststatus-property-gisbreceiver-component) property for a list of standard error messages.

If you use version 1.4 of the GISB/NAESB protocol, the response will be a simple HTML reply. If you use version 1.6 the sender has the option of requesting a signed receipt. In all cases the response may be created with [CreateResponse](#createresponse-method-gisbreceiver-component) and sent with [SendResponse](#sendresponse-method-gisbreceiver-component).

To create log files, set [LogDirectory](#logdirectory-property-gisbreceiver-component) prior to invoking [ProcessRequest](#processrequest-method-gisbreceiver-component). This will log all incoming and outgoing data, and will also write the received EDI files to disk.

*Additional Server-Side Functionality*

When used in a server environment such as ASP, ASP.NET, etc., the component may be used to interface directly with the underlying HTTP context. If [Request](#request-property-gisbreceiver-component) is not set by the user [ParseRequest](#parserequest-method-gisbreceiver-component) and [ProcessRequest](#processrequest-method-gisbreceiver-component) will first get the request from the underlying HTTP environment, if possible. [SendResponse](#sendresponse-method-gisbreceiver-component) will send the reply in this environment if able; otherwise the reply will be directed to standard out.

## Property List

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

|  |  |
| --- | --- |
| [DataElements](#dataelements-property-gisbreceiver-component) | Collection of data elements for the client's request. |
| [DataFrom](#datafrom-property-gisbreceiver-component) | The identity of the sending system. |
| [DataTo](#datato-property-gisbreceiver-component) | The identity of the receiving system. |
| [ErrorMessage](#errormessage-property-gisbreceiver-component) | If the client sent an error notification, the error message. |
| [GISBData](#gisbdata-property-gisbreceiver-component) | The EDI Payload of the message. |
| [GISBVersion](#gisbversion-property-gisbreceiver-component) | The version of the GISB/NAESB protocol used. |
| [LogDirectory](#logdirectory-property-gisbreceiver-component) | The path to a directory for logging. |
| [LogFile](#logfile-property-gisbreceiver-component) | The log file written. |
| [PublicKeyringData](#publickeyringdata-property-gisbreceiver-component) | Public keyring data. |
| [ReceiptSigningProtocol](#receiptsigningprotocol-property-gisbreceiver-component) | The protocol used to sign the receipt, if any. |
| [ReceiptType](#receipttype-property-gisbreceiver-component) | The type of receipt to be returned, if any. |
| [Request](#request-property-gisbreceiver-component) | The HTTP request to be processed. |
| [RequestHeaders](#requestheaders-property-gisbreceiver-component) | The HTTP headers in the request. |
| [RequestStatus](#requeststatus-property-gisbreceiver-component) | The status of the request. |
| [Response](#response-property-gisbreceiver-component) | The response generated by the component. |
| [ResponseHeaders](#responseheaders-property-gisbreceiver-component) | The response headers generated by the component. |
| [SecretKeyringData](#secretkeyringdata-property-gisbreceiver-component) | Secret keyring data. |
| [ServerId](#serverid-property-gisbreceiver-component) | The ID of your server. |
| [TransactionId](#transactionid-property-gisbreceiver-component) | The transaction ID of the message. |

## Method List

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

|  |  |
| --- | --- |
| [Config](#config-method-gisbreceiver-component) | Sets or retrieves a configuration setting. |
| [CreateResponse](#createresponse-method-gisbreceiver-component) | Creates the response. |
| [ParseFormData](#parseformdata-method-gisbreceiver-component) | Processes the form data, and populates the appropriate properties. |
| [ParseRequest](#parserequest-method-gisbreceiver-component) | Processes the EDI data. |
| [ProcessRequest](#processrequest-method-gisbreceiver-component) | Processes the EDI data, and generates the receipt. |
| [ReadRequest](#readrequest-method-gisbreceiver-component) | Reads the AS2 request from the given HTTP servlet request. |
| [Reset](#reset-method-gisbreceiver-component) | Resets the state of the control. |
| [SendResponse](#sendresponse-method-gisbreceiver-component) | In a server environment, responds to the requesting client. |
| [SetPGPParam](#setpgpparam-method-gisbreceiver-component) | Sets a parameter in the PGP provider. |

## Event List

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

|  |  |
| --- | --- |
| [Error](#error-event-gisbreceiver-component) | Fired when information is available about errors during data delivery. |
| [Log](#log-event-gisbreceiver-component) | Fired with log information while processing a message. |

## Config Settings

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

|  |  |
| --- | --- |
| [LogFilename](#LogFilename) | The base name of the log file. |
| [LogLevel](#LogLevel) | Specifies the level of detail that is logged. |
| [RequireEncryption](#RequireEncryption) | Whether an error should be thrown if an unencrypted message is received. |
| [RequireSignature](#RequireSignature) | Whether an error should be thrown if an unsigned message is received. |
| [TimeCFormat](#TimeCFormat) | The format of the Time-C data element. |
| [TimeCQualifier](#TimeCQualifier) | The UTC off-set of the server. |
| [BuildInfo](#BuildInfo) | Information about the product's build. |
| [GUIAvailable](#GUIAvailable) | Whether or not a message loop is available for processing events. |
| [LicenseInfo](#LicenseInfo) | Information about the current license. |
| [MaskSensitiveData](#MaskSensitiveData) | Whether sensitive data is masked in log messages. |
| [UseFIPSCompliantAPI](#UseFIPSCompliantAPI) | Tells the component whether or not to use FIPS certified APIs. |
| [UseInternalSecurityAPI](#UseInternalSecurityAPI) | Whether or not to use the system security libraries or an internal implementation. |

# DataElements Property ([GISBReceiver](#gisbreceiver-component) Component)

Collection of data elements for the client's request.

## Syntax

```text
public GISBElementList DataElements { get; }
```

## Remarks

Data elements will include required elements such as "to", "from", "input-format", etc., and may contain other elements as sent by your trading partner.

This property is not available at design time.

 Please refer to the [GISBElement](#gisbelement-type) type for a complete list of fields.

# DataFrom Property ([GISBReceiver](#gisbreceiver-component) Component)

The identity of the sending system.

## Syntax

```text
public string DataFrom { get; }
```

## Default Value

""

## Remarks

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

This property is read-only.

# DataTo Property ([GISBReceiver](#gisbreceiver-component) Component)

The identity of the receiving system.

## Syntax

```text
public string DataTo { get; }
```

## Default Value

""

## Remarks

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

This property is read-only.

# ErrorMessage Property ([GISBReceiver](#gisbreceiver-component) Component)

If the client sent an error notification, the error message.

## Syntax

```text
public string ErrorMessage { get; }
```

## Default Value

""

## Remarks

ErrorMessage will be set in case the [Request](#request-property-gisbreceiver-component) is an error notification rather than a post. The ErrorMessage will contain the entire contents of the error notification.

For example, the following might be returned:

```text
orig-from=123456789*
orig-to=234567890*
orig-input-format=X12*
resp-time-c=11960619102855*
resp-server-id=coolhost*
resp-trans-id=234423897*
request-status=EEDM601: Public Key Invalid*
comments=Please contact 1-800-555-1212 for correct public key*
```

This property is read-only.

# GISBData Property ([GISBReceiver](#gisbreceiver-component) Component)

The EDI Payload of the message.

## Syntax

```text
public GISBData GISBData { get; }
```

## Remarks

The EDI Payload of the message.

This property is read-only.

 Please refer to the [GISBData](#gisbdata-type) type for a complete list of fields.

# GISBVersion Property ([GISBReceiver](#gisbreceiver-component) Component)

The version of the GISB/NAESB protocol used.

## Syntax

```text
public string GISBVersion { get; }
```

## Default Value

"1.4"

## Remarks

The version of the GISB/NAESB protocol used. Note that when receiving documents the version will be determined automatically.

This property is read-only.

# LogDirectory Property ([GISBReceiver](#gisbreceiver-component) Component)

The path to a directory for logging.

## Syntax

```text
public string LogDirectory { get; set; }
```

## 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 component will log the complete text of the incoming request, the EDI data (if it was able to be determined), and the outgoing response.

Two files will be written for each transmission. The diagnostic log will have the extension ".log" and will log the complete text of the incoming request, the EDI data (if it was able to be determined), and the outgoing response. The data file will have the extension ".dat" and will store the EDI data only. In case of error an additional file with extension ".err" file will be written, and the error information will also be written to the ".log" file.

The filenames will be chosen automatically by the component. 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](#logfile-property-gisbreceiver-component) will contain the name of the files just written, minus the extension ".log" or ".dat".

If either log cannot be written an exception will be thrown; server applications should ensure that the server has the appropriate write permissions.

# LogFile Property ([GISBReceiver](#gisbreceiver-component) Component)

The log file written.

## Syntax

```text
public string LogFile { get; }
```

## Default Value

""

## Remarks

In case [LogDirectory](#logdirectory-property-gisbreceiver-component) is specified two log files will be written in the specified directory and LogFile will contain the path. A diagnostic log will be written with filename LogFile + ".log" and the EDI data will be written with filename LogFile + ".dat". In case of error an additional file will be written with filename LogFile + ".err".

This property is read-only.

# PublicKeyringData Property ([GISBReceiver](#gisbreceiver-component) Component)

Public keyring data.

## Syntax

```text
public string PublicKeyringData { get; set; }
public byte[] PublicKeyringDataB { get; set; }
```

## 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](#secretkeyringdata-property-gisbreceiver-component) and the keyring will be loaded from this data instead of the *homedir*.

# ReceiptSigningProtocol Property ([GISBReceiver](#gisbreceiver-component) Component)

The protocol used to sign the receipt, if any.

## Syntax

```text
public string ReceiptSigningProtocol { get; set; }
```

## Default Value

""

## Remarks

After you invoke [ParseRequest](#parserequest-method-gisbreceiver-component) this property will contain the signing protocol requested by the client (either an empty string or "pgp-signature"; other values are not supported). When you invoke [CreateResponse](#createresponse-method-gisbreceiver-component) this protocol will be used to sign the receipt.

# ReceiptType Property ([GISBReceiver](#gisbreceiver-component) Component)

The type of receipt to be returned, if any.

## Syntax

```text
public string ReceiptType { get; }
```

## Default Value

""

## Remarks

The type of receipt to be returned. If this property is empty a simple HTML response will be returned. For a value of "GISB-Acknowledgement-Receipt" a more detailed receipt will be generated.

Other values are not supported and will cause the component to throw an exception. You may, if you wish, catch this exception, generate your own [Response](#response-property-gisbreceiver-component), and send it using [SendResponse](#sendresponse-method-gisbreceiver-component).

This property is read-only.

# Request Property ([GISBReceiver](#gisbreceiver-component) Component)

The HTTP request to be processed.

## Syntax

```text
public string Request { get; set; }
public byte[] RequestB { get; set; }
```

## Default Value

""

## Remarks

The body of the request to be processed. You may include the HTTP headers or specify them separately in [RequestHeaders](#requestheaders-property-gisbreceiver-component).

Typically the request may be read directly from the HTTP context, without setting this property.

This property is not available at design time.

# RequestHeaders Property ([GISBReceiver](#gisbreceiver-component) Component)

The HTTP headers in the request.

## Syntax

```text
public string RequestHeaders { get; set; }
```

## Default Value

""

## Remarks

The entire list of HTTP and MIME headers.

# RequestStatus Property ([GISBReceiver](#gisbreceiver-component) Component)

The status of the request.

## Syntax

```text
public string RequestStatus { get; set; }
```

## Default Value

"ok"

## Remarks

RequestStatus will be determined by [ParseRequest](#parserequest-method-gisbreceiver-component) or [ProcessRequest](#processrequest-method-gisbreceiver-component), and will contain the string "ok" or an error message to be returned in the [Response](#response-property-gisbreceiver-component).

Errors relating to message processing (e.g., "EEDM104: Missing Data File") will automatically be discovered and reported by the component. Other types of errors are by mutual agreement. In particular **the use of message security is not enforced by the component by default.** To require encryption or signing set [RequireEncryption](#RequireEncryption) or [RequireSignature](#RequireSignature) and specify error EEDM602 or EEDM604 as appropriate.

It is recommended that you set RequestStatus to one of the standard errors listed below. The specification additionally allows for a supplemental error message; separate this from the standard error with a semicolon. For example, "EEDM107: Invalid input format; expected X12."

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** component 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

# Response Property ([GISBReceiver](#gisbreceiver-component) Component)

The response generated by the component.

## Syntax

```text
public string Response { get; }
public byte[] ResponseB { get; }
```

## Default Value

""

## Remarks

The response generated by the component after invoking [ProcessRequest](#processrequest-method-gisbreceiver-component) or [CreateResponse](#createresponse-method-gisbreceiver-component). The format of the response may range from a simple HTML response to a signed GISB-Acknowledgement-Receipt, depending on the client's request. In any case it will report success or failure as appropriate. If you wish to reject the request you may set [RequestStatus](#requeststatus-property-gisbreceiver-component) to an appropriate value before invoking [CreateResponse](#createresponse-method-gisbreceiver-component).

This property is read-only.

# ResponseHeaders Property ([GISBReceiver](#gisbreceiver-component) Component)

The response headers generated by the component.

## Syntax

```text
public string ResponseHeaders { get; }
```

## Default Value

""

## Remarks

The response headers generated by the component after invoking [ProcessRequest](#processrequest-method-gisbreceiver-component) or [CreateResponse](#createresponse-method-gisbreceiver-component). In general ResponseHeaders will consist of a single "Content-Type" header or an empty string.

This property is read-only.

# SecretKeyringData Property ([GISBReceiver](#gisbreceiver-component) Component)

Secret keyring data.

## Syntax

```text
public string SecretKeyringData { get; set; }
public byte[] SecretKeyringDataB { get; set; }
```

## 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](#publickeyringdata-property-gisbreceiver-component) and the keyring will be loaded from this data instead of the *homedir*.

# ServerId Property ([GISBReceiver](#gisbreceiver-component) Component)

The ID of your server.

## Syntax

```text
public string ServerId { get; set; }
```

## Default Value

""

## Remarks

The ID of your server, as it will be described in the response. If you do not specify ServerId the component will attempt to determine it when you call [ProcessRequest](#processrequest-method-gisbreceiver-component) or [CreateResponse](#createresponse-method-gisbreceiver-component).

# TransactionId Property ([GISBReceiver](#gisbreceiver-component) Component)

The transaction ID of the message.

## Syntax

```text
public string TransactionId { get; set; }
```

## Default Value

""

## Remarks

A unique ID for the transaction. In GISB a TransactionId will **generated by the server** whenever you process a request. You may either allow the component to generate unique values for TransactionId, or devise your own scheme and set TransactionId before invoking [CreateResponse](#createresponse-method-gisbreceiver-component).

If you devise your own scheme you should set TransactionId after invoking [ParseRequest](#parserequest-method-gisbreceiver-component) as [ParseRequest](#parserequest-method-gisbreceiver-component) will generate a new ID for the request.

# Config Method ([GISBReceiver](#gisbreceiver-component) Component)

Sets or retrieves a configuration setting.

## Syntax

```text
public string Config(string configurationString);

Async Version
public async Task<string> Config(string configurationString);
public async Task<string> Config(string configurationString, CancellationToken cancellationToken);
```

## Remarks

Config is a generic method available in every component. It is used to set and retrieve [configuration settings](#config-settings-gisbreceiver-component) for the component.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the component, 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](#config-settings-gisbreceiver-component), you must call *Config("PROPERTY")*. The value will be returned as a string.

# CreateResponse Method ([GISBReceiver](#gisbreceiver-component) Component)

Creates the response.

## Syntax

```text
public void CreateResponse();

Async Version
public async Task CreateResponse();
public async Task CreateResponse(CancellationToken cancellationToken);
```

## Remarks

Creates a response to the incoming request. The format of the request (signed receipt or simple HTML, for example) will depend on the request of the client.

# ParseFormData Method ([GISBReceiver](#gisbreceiver-component) Component)

Processes the form data, and populates the appropriate properties.

## Syntax

```text
public void ParseFormData();

Async Version
public async Task ParseFormData();
public async Task ParseFormData(CancellationToken cancellationToken);
```

## Remarks

Invoking ParseFormData scans the form data, allowing you to determine the identity of the sender. The following properties will be populated: [DataFrom](#datafrom-property-gisbreceiver-component), [DataTo](#datato-property-gisbreceiver-component), [EDIType](#GISBData_f_EDIType), [GISBVersion](#gisbversion-property-gisbreceiver-component), and [ReceiptType](#receipttype-property-gisbreceiver-component). [ParseRequest](#parserequest-method-gisbreceiver-component) may be used to read the entire message.

If [RequestHeaders](#requestheaders-property-gisbreceiver-component) is empty and [Request](#request-property-gisbreceiver-component) contains both the headers and the message, [Request](#request-property-gisbreceiver-component) will be split and stored in [Request](#request-property-gisbreceiver-component) and [RequestHeaders](#requestheaders-property-gisbreceiver-component) as described in the [Request](#request-property-gisbreceiver-component)'s description.

# ParseRequest Method ([GISBReceiver](#gisbreceiver-component) Component)

Processes the EDI data.

## Syntax

```text
public void ParseRequest();

Async Version
public async Task ParseRequest();
public async Task ParseRequest(CancellationToken cancellationToken);
```

## Remarks

Invoking ParseRequest parses the incoming request and attempts to determine the [GISBData](#gisbdata-property-gisbreceiver-component) sent by the client. The method will first parse the form data unless you have already called [ParseFormData](#parseformdata-method-gisbreceiver-component).

The method will throw an exception if any errors are found. Regardless of success or failure the method will determine an appropriate value for [RequestStatus](#requeststatus-property-gisbreceiver-component). It is recommended that you catch any exceptions and invoke [CreateResponse](#createresponse-method-gisbreceiver-component) and [SendResponse](#sendresponse-method-gisbreceiver-component) in case of either success or failure.

Invoking [ProcessRequest](#processrequest-method-gisbreceiver-component) is equivalent to invoking ParseRequest and then [CreateResponse](#createresponse-method-gisbreceiver-component). Calling the methods separately allows you to change the value of [RequestStatus](#requeststatus-property-gisbreceiver-component) before generating the response; for example, you may choose to feed [GISBData](#gisbdata-property-gisbreceiver-component) to an EDI translator before generating a positive response.

# ProcessRequest Method ([GISBReceiver](#gisbreceiver-component) Component)

Processes the EDI data, and generates the receipt.

## Syntax

```text
public void ProcessRequest();

Async Version
public async Task ProcessRequest();
public async Task ProcessRequest(CancellationToken cancellationToken);
```

## Remarks

Invoking **ProcessRequest** automates the entire server process. The method scans the request, determines the EDIData, and generates the [Response](#response-property-gisbreceiver-component) and [ResponseHeaders](#responseheaders-property-gisbreceiver-component). The method's functionality is the same as the combined functionality of [ParseFormData](#parseformdata-method-gisbreceiver-component), [ParseRequest](#parserequest-method-gisbreceiver-component), and [CreateResponse](#createresponse-method-gisbreceiver-component).

The method will throw an exception if any errors are found. However, the [Response](#response-property-gisbreceiver-component) will still be generated and will contain information about any errors. It is recommended that you catch any exceptions and invoke [SendResponse](#sendresponse-method-gisbreceiver-component) in case of either success or failure.

The component will populate EDIData if possible.

# ReadRequest Method ([GISBReceiver](#gisbreceiver-component) Component)

Reads the AS2 request from the given HTTP servlet request.

## Syntax

```text
public void ReadRequest();

Async Version
public async Task ReadRequest();
public async Task ReadRequest(CancellationToken cancellationToken);
```

## Remarks

In the **Java** edition, reads the request from the specified *HttpServletRequest*. The request will be stored in [Request](#request-property-gisbreceiver-component) and the headers in [RequestHeaders](#requestheaders-property-gisbreceiver-component). [ParseRequest](#parserequest-method-gisbreceiver-component) may then be invoked.

In versions other than Java, this method has no effect.

# Reset Method ([GISBReceiver](#gisbreceiver-component) Component)

Resets the state of the control.

## Syntax

```text
public void Reset();

Async Version
public async Task Reset();
public async Task Reset(CancellationToken cancellationToken);
```

## Remarks

**Reset** resets the state of the component. All properties will be set to their default values.

# SendResponse Method ([GISBReceiver](#gisbreceiver-component) Component)

In a server environment, responds to the requesting client.

## Syntax

```text
public void SendResponse();

Async Version
public async Task SendResponse();
public async Task SendResponse(CancellationToken cancellationToken);
```

## Remarks

When called from within a server environment, **SendResponse** will respond to the requesting client with the [Response](#response-property-gisbreceiver-component). The [Response](#response-property-gisbreceiver-component) may be a simple HTML block (this will always be the case in version 1.4) or a GISB-Acknowledgement-Receipt, if requested by the client.

The exact behavior of the method is specific to the environment. In ASP or ASP.NET, the receipt will be sent within the current HTTP context. In Java, the receipt will be sent within the provided *HttpServletResponse*. Otherwise, the receipt will be directed to stdout. If this is impossible an exception will be thrown.

This method should only be invoked after [Response](#response-property-gisbreceiver-component) has been generated by [CreateResponse](#createresponse-method-gisbreceiver-component) or [ProcessRequest](#processrequest-method-gisbreceiver-component).

# SetPGPParam Method ([GISBReceiver](#gisbreceiver-component) Component)

Sets a parameter in the PGP provider.

## Syntax

```text
public void SetPGPParam(string name, string value);

Async Version
public async Task SetPGPParam(string name, string value);
public async Task SetPGPParam(string name, string value, CancellationToken cancellationToken);
```

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

|  |  |
| --- | --- |
| homedir | The directory containing the public keyring, secret keyring and trust database. Please note this defaults to the application preferences directory of the user, hence if the GNUPG provider is being used from a ASP.NET application, homedir should be specified. |
| passphrase | The passphrase to access the secret keys in the secret-keyring. |
| userid | The identifier used to identify a secret key within the secret-keyring. Note: When decrypting if this value is not specified the component will attempt to find the key within the keyring automatically based on information available in the PGP message itself. |
| recipient-userid | The identifier used to identify a public key within the public keyring. Note: When verifying a signature if this value is not specified the component will attempt to find the key within the keyring automatically based on information available in the PGP message itself. |
| timeout | The timeout in milliseconds that the provider will wait for a response from the OpenPGP executable. The default is 5000 (5 seconds). |
| usetempfile | If set to "true" the provider will write data to be processed to a temporary file on disk. This is useful when working with large files or binary files. |
| signingalgorithm | The signing algorithm to use when SignData is True. Possible values are: SHA1 MD5 SHA256 (default) SHA384 SHA512 SHA224 RIPEMD160 |
| encryptingalgorithm | The encrypting algorithm to use when EncryptData is True. Possible values are: CAST5 3DES AES256 AES192 AES128 (default) BLOWFISH TWOFISH IDEA |
| compressionmethod | The compression method to use. Possible values are: zip (default) zlib bzip2 none |

# Error Event ([GISBReceiver](#gisbreceiver-component) Component)

Fired when information is available about errors during data delivery.

## Syntax

```text
public event OnErrorHandler OnError;

public delegate void OnErrorHandler(object sender, GISBReceiverErrorEventArgs e);

public class GISBReceiverErrorEventArgs : EventArgs {
  public int ErrorCode { get; }
  public string Description { get; }
}
```

## Remarks

The Error event is fired in case of exceptional conditions during message processing. Normally the component 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](#trappable-errors-gisbreceiver-component) section.

# Log Event ([GISBReceiver](#gisbreceiver-component) Component)

Fired with log information while processing a message.

## Syntax

```text
public event OnLogHandler OnLog;

public delegate void OnLogHandler(object sender, GISBReceiverLogEventArgs e);

public class GISBReceiverLogEventArgs : EventArgs {
  public string LogType { get; }
  public string LogMessage { get; }  public byte[] LogMessageB { get; }
}
```

## Remarks

This event fires once for each log message generated by the component. The verbosity is controlled by the [LogLevel](#LogLevel) setting.

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

|  |  |
| --- | --- |
| "LOG" | Information about the status of the process. |
| "ERR" | An error was encountered. |
| "DAT" | The EDI payload. |
| "REQ" | The raw request |
| "MDN" | The MDN response. |
| "DEBUG" | Debug information. |
| "DAT.INPUT" | Debug information when processing payload. Only applicable when [LogDebug](#LogDebug) is True. |
| "DAT.ENCRYPT" | Debug information when processing payload. Only applicable when [LogDebug](#LogDebug) is True. |
| "DAT.COMPRESS" | Debug information when processing payload. Only applicable when [LogDebug](#LogDebug) is True. |
| "DAT.SIGN" | Debug information when processing payload. Only applicable when [LogDebug](#LogDebug) is True. |
| "DAT.DECRYPT" | Debug information when processing payload. Only applicable when [LogDebug](#LogDebug) is True. |
| "DAT.DECOMPRESS" | Debug information when processing payload. Only applicable when [LogDebug](#LogDebug) is True. |
| "DAT.VERIFY" | Debug information when processing payload. Only applicable when [LogDebug](#LogDebug) is True. |
| "DAT.DEBUG" | Debug information when processing payload. Only applicable when [LogDebug](#LogDebug) is True. |

# GISBData Type

The EDI payload of the message.

## Remarks

The EDI payload of the message.

The following fields are available:

- [Data](#GISBData_f_Data)

- [EDIType](#GISBData_f_EDIType)

- [FileName](#GISBData_f_FileName)

- [InputStream](#GISBData_f_InputStream)

- [Name](#GISBData_f_Name)

- [OutputStream](#GISBData_f_OutputStream)

## Fields

 **Data** *string*
Default: ""

This field contains the EDI payload of the transmission.

In a receiver, this field will only be populated if [OutputStream](#GISBData_f_OutputStream) has not been specified and ParseRequest finishes without an error. [Data](#GISBData_f_Data) will contain the full decrypted text of the EDI message.

 **DataB** *byte []*
Default: ""

This field contains the EDI payload of the transmission.

In a receiver, this field will only be populated if [OutputStream](#GISBData_f_OutputStream) has not been specified and ParseRequest finishes without an error. [Data](#GISBData_f_Data) will contain the full decrypted text of the EDI message.

 **EDIType** *string*
Default: "X12"

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

 **FileName** *string*
Default: ""

In a sender, if [FileName](#GISBData_f_FileName) is specified, the file specified will be used for the EDI payload of the transmission. [Name](#GISBData_f_Name) will be populated with the name of the file.

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

Note: When [OutputStream](#GISBData_f_OutputStream) is set, the data will be written to the stream and this field will not be populated.

 **InputStream** *System.IO.Stream*
Default: ""

In a sender, if [InputStream](#GISBData_f_InputStream) is specified, the data from the specified stream will be used for the EDI payload of the transmission.

 **Name** *string*
Default: "rfc1767.edi"

[Name](#GISBData_f_Name) is the final name to be associated with the contents of either the [Data](#GISBData_f_Data) or [FileName](#GISBData_f_FileName) fields. This corresponds to the *filename* attribute of the *Content-Disposition* header for the EDI payload.

When constructing EDI data to be sent, [Name](#GISBData_f_Name) will be set to the same value as [FileName](#GISBData_f_FileName), but can be overridden after setting [FileName](#GISBData_f_FileName) to indicate that another name should be used in the outbound request's Content-Disposition MIME header.

When receiving EDI data, [Name](#GISBData_f_Name) will be read out of the "filename" attribute of the inbound request's Content-Disposition MIME header.

 **OutputStream** *System.IO.Stream*
Default: ""

In a receiver, if this field is set, the EDI payload will be written to this stream if ParseRequest finishes without an error. The specified stream will contain the full decrypted text of the EDI message.

## Constructors

```text
public GISBData();
```

```text
public GISBData(byte[] data, string EDIType);
```

```text
public GISBData(string fileName, string 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.

The following fields are available:

- [Name](#GISBElement_f_Name)

- [Value](#GISBElement_f_Value)

## Fields

 **Name** *string*
Default: ""

The name of the current data element.

 **Value** *string*
Default: ""

The value of the current data element.

## Constructors

```text
public GISBElement();
```

```text
public GISBElement(string name, string value);
```

# Config Settings ([GISBReceiver](#gisbreceiver-component) Component)

 The component 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 component, access to these *internal properties* is provided through the [Config](#config-method-gisbreceiver-component) method.

### GISBReceiver Config Settings

**LogFilename**: The base name of the log file.If set, this will be used as for the filename of the log file.

Note that only the base name should be specified as the component will append the appropriate file extension.

**LogLevel**: Specifies the level of detail that is logged.This setting controls the level of detail that is logged through the Status event. Possible values are:

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

**RequireEncryption**: Whether an error should be thrown if an unencrypted message is received.By default, the component will silently accept unencrypted messages. To instead throw an error when an unencrypted message is received, set this to True.

The default value is False.

**RequireSignature**: Whether an error should be thrown if an unsigned message is received.By default, the component will silently accept unsigned messages. To instead throw an error when an unsigned message is received, set this to True.

The default value is False.

**TimeCFormat**: The format of the Time-C data element.Setting this configuration option allows you to control the format of the Time-C data element in the gisb-acknowledgement-receipt.

Default: yyyyMMddhhmmss

**TimeCQualifier**: The UTC off-set of the server.If the Time-C-Qualifier data element is to be sent in the gisb-acknowledgement-receipt then its value should be set here.

### Base Config Settings

**BuildInfo**: Information about the product's build.When queried, this setting will return a string containing information about the product's build.

**GUIAvailable**: Whether or not a message loop is available for processing events.In a GUI-based application, long-running blocking operations may cause the application to stop responding to input until the operation returns. The component will attempt to discover whether or not the application has a message loop and, if one is discovered, it will process events in that message loop during any such blocking operation.

In some non-GUI applications, an invalid message loop may be discovered that will result in errant behavior. In these cases, setting [GUIAvailable](#GUIAvailable) to *false* will ensure that the component does not attempt to process external events.

**LicenseInfo**: Information about the current license.When queried, this setting will return a string containing information about the license this instance of a component is using. It will return the following information:

- Product: The product the license is for.
- Product Key: The key the license was generated from.
- License Source: Where the license was found (e.g., RuntimeLicense, License File).
- License Type: The type of license installed (e.g., Royalty Free, Single Server).
- Last Valid Build: The last valid build number for which the license will work.

**MaskSensitiveData**: Whether sensitive data is masked in log messages.In certain circumstances it may be beneficial to mask sensitive data, like passwords, in log messages. Set this to *true* to mask sensitive data. The default is *true*.

**UseFIPSCompliantAPI**: Tells the component whether or not to use FIPS certified APIs.When set to *true*, the component will utilize the underlying operating system's certified APIs. Java editions, regardless of OS, utilize Bouncy Castle Federal Information Processing Standards (FIPS), while all other Windows editions make use of Microsoft security libraries.

FIPS mode can be enabled by setting the *UseFIPSCompliantAPI* configuration setting to *true*. This is a static setting that applies to all instances of all components of the toolkit within the process. It is recommended to enable or disable this setting once before the component has been used to establish a connection. Enabling FIPS while an instance of the component is active and connected may result in unexpected behavior.

For more details, please see the [FIPS 140-2 Compliance](https://www.nsoftware.com/kb/articles/fips.rst) article.

NOTE: This setting is applicable only on Windows.

NOTE: Enabling FIPS compliance requires a special license; please contact [sales@nsoftware.com](mailto:sales@nsoftware.com) for details.

**UseInternalSecurityAPI**: Whether or not to use the system security libraries or an internal implementation. When set to *false*, the component will use the system security libraries by default to perform cryptographic functions where applicable. In this case, calls to unmanaged code will be made. In certain environments, this is not desirable. To use a completely managed security implementation, set this setting to *true*.

Setting this configuration setting to *true* tells the component to use the internal implementation instead of using the system security libraries.

 On Windows, this setting is set to *false* by default. On Linux/macOS, this setting is set to *true* by default.

NOTE: This setting is static. The value set is applicable to all components used in the application.

When this value is set, the product's system dynamic link library (DLL) is no longer required as a reference, as all unmanaged code is stored in that file.

# Trappable Errors ([GISBReceiver](#gisbreceiver-component) Component)

### GISBReceiver Errors

|  |  |
| --- | --- |
| 651 | Required field unspecified. |
| 661 | Array index out of bounds. |
| 663 | Invalid receipt-security-selection requested by client. |
| 664 | Data was not processed by PGP. |
| 701 | Unable to write log file. |
| 702 | Invalid request headers. |
| 704 | Invalid request. |
| 705 | There is no response to send. |
| 771 | Unable to send the response. |
| 721 | There is no current HTTP environment. |
| 732 | Unable to verify the signature. |
| 733 | The receipt was signed with an unsupported protocol. |

### 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 component 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. |