UPSShip Configuration

This returns the complete request as sent to the server. Used for debugging purposes.

This returns the complete response as received from the server. Used for debugging purposes.

XPath implements a subset of the XML XPath specification, allowing you to point to specific elements in the XML-formatted RawResponse.

The path is a series of one or more element accessors separated by '/'. The path can be absolute (starting with '/') or relative to the current XPath location.

The following are possible values for an element accessor:

When XPath is set to a valid path, the text contained at that element (if any) is returned. If there is no value present, or the xpath is invalid, and empty string ("") will be returned.

This might be returned by the server even upon successful response. These warnings are usually informational.

When set to True (default) the component will construct the request for UPS' SOAP web service, otherwise the request will be constructed for UPS' XML service.

This indicates the account-based rates. It is applicable and returned in the ship response only if shipper account/user id combinations qualifies for Negotiated rates.

If True, then the reference number's value (first value of the ShipmentReference in the UPSShipIntl component, or first value of the Reference in the UPSShip component) will be bar coded on the shipping label.

Only one shipment-level (applicable to international shipments) or package-level reference number (applicable to domestic shipments throughout US or PR) can be bar coded per shipment.

In order to barcode a reference number, its value must be no longer than 14 alphanumeric characters or 24 numeric characters and cannot contain spaces.

To be used in Label Certification process only.

If this config is set to a valid value, all files needed for certification process (html, gif and xml files) are written to disk in this specified location.

Note: When this is set, all shipping label filenames will be overwritten with the format required by UPS for the Certification process. For example, if the PackageShippingLabelFileHTML[i]; is set to 'MyShippingLabel.html' and the ShippingLabelFile is set to and the Tracking Number for that package is '1Z0715X10194877288', then the PackageShippingLabelFileHTML[i]; will automatically be changed to 'label1Z0715X10194877288.html', and the corresponding image file name to 'label1Z0715X10194877288.gif'.

If both ShippingLabelHTMLDirectory and CertifyDirectory have been set, then the CertifyDirectory will take precedence over the ShippingLabelHTMLDirectory.

This is required to be provided if monetary values are specified in the request (such as COD amount, insured value, customs value, etc.). This must conform to ISO standards.

Maximum length: 3.

Here is a list of currency names and their codes used by UPS services.

Filename and location to save the HighValueReport to. When the total insured value in a forward shipment is between $999 and $50,000 USD, the High Value Report is returned in the response and stored in HighValueReport.

The shipper is required to print 2 copies of this report, give them to a UPS driver or UPS Customer Center representative to ensure he signs one copy of the receipt and returns it to the shipper. This is your proof that UPS has accepted the package(s), and will be required for submitting a claim.

When the HighValueReportFileName is set to a valid path and filename, the contents of the HighValueReport are written to disk upon successful response.

This filename should have a html, EPL2, ZPL, STARPL or SPL extension (depending on the printer used).

If the filename exists, you can choose to overwrite it or not by setting the Overwrite config setting (which defaults to True).

Image of the High Value Report (as decoded binary image file). When the total insured value in a forward shipment is between $999 and $50,000 USD, the High Value Report is returned in the response and stored in HighValueReport.

The shipper is required to print 2 copies of this report, give them to a UPS driver or UPS Customer Center representative to ensure he signs one copy of the receipt and returns it to the shipper. This is your proof that UPS has accepted the package(s), and will be required for submitting a claim.

When the HighValueReportFileName is set to a valid path and filename, the contents of the HighValueReport are written to this location in disk.

When Machineable is set to false, this should be set to one of the following values:

This contains the size of the label. The valid values are:

When set to true (default), this indicates wheter or not the package is machineable, in other words, if it is a standard sized package.

This only applies when using a Mail Innovations or SurePost ServiceType

This is a customer defined identifier that can later be used to get the report and billing summarization displays to the right of the Cost Center title. This should be an alpha-numeric string that is between 1 and 30 characters.

This is required when using a Mail Innovations ServiceType (ie. stUPSFirstClass, stUPSPriorityMail, stUPSExpeditedMailInnovations, stUPSPriorityMailInnovations, or stUPSEconomyMailInnovations).

This is a customer defined identifier to identify the individual package that can be used to later get the visibility events for the package. This should be an alpha-numeric string that is between 1 and 30 characters.

This is required when using a Mail Innovations ServiceType (ie. stUPSFirstClass, stUPSPriorityMail, stUPSExpeditedMailInnovations, stUPSPriorityMailInnovations, or stUPSEconomyMailInnovations).

If True (default value) the label files are overwritten. Otherwise, an error is returned if the file exist.

This determines the type of declared value for a package.

Valid array indices are from 0 to PackageCount - 1.

HTML image of the package shipping label (as decoded binary image file). This is used during the Label Certification process with UPS.

When the PackageShippingLabelFileHTML is set to a valid path and filename, the contents of the PackageShippingLabelHTML are written to this location in disk.

Valid array indices are from 0 to PackageCount - 1.

Filename to save the PackageShippingLabelHTML to.

When the user is going through the Label Certification process with UPS, the CertifyDirectory should be set (this is the location where all required files by UPS for Label Certification will be written and then sent to UPS) and the PackageShippingLabelFileHTML will be automatically set to 'labelTrackingNumber.html'. This file is required to be sent to UPS for each of the five test shipments along with the: image file (gif) of that shipment's shipping label (ShippingLabel), ShipmentConfirmRequest, ShipmentConfirmResponse, ShipmentAcceptRequest, and ShipmentAcceptResponse of that shipment.

If you are no longer in certification process, the location where this file will be saved to disk can be specified by the ShippingLabelHTMLDirectory. If this config is not set, then the html file will be written to your default directory.

If the filename exists, you can choose to overwrite it or not by setting the Overwrite config setting (which defaults to True).

Valid array indices are from 0 to PackageCount - 1.

Note: When choosing to save to disk the html file for the shipping label, the image file should be written to disk as well (at the same directory as html file) and the corresponding ShippingLabelFile should be set to 'labelTrackingNumber.gif'. Otherwise, the html file will show just the UPS shipping instructions and the label itself will not appear on it.

This setting specifies the floor number of the pickup location. It is applicable when calling SchedulePickup

This setting specifies the room number of the pickup location. It is applicable when calling SchedulePickup

If set to true, Returns Flexible Access service will be used. Note that to use this service you will need to enter into a contract with UPS.

Indicates that the ship request is made for UPS Print and Mail (PNM). This is applicable to return shipments only. In the server response, you will receive only a Tracking number for the shipment to be returned, but not a return label and/or return receipt. The label will be emailed to your customer by UPS.

If this is set, either SenderContactEmail or AccountContactEmail, as well as RecipientContactEmail should be set.

For return shipments, one of the following conditions must be met on CountryCode, CountryCode and CountryCode: At least two of these country codes are the same; None of these country codes are the same and are a member of the EU; None of these country codes are the same and at least one of them is not a member of the EU, and the shipper must have third country contract service. Following is a list of restrictions that are applicable when using return label types. This cannot be combined with COD, Saturday Delivery, Saturday Pickup, and/or Delivery Confirmation service options. For international shipments with return service, the Invoice flag is the only valid value for FormTypes. The availability of return service depends on the origin and destination country code, and on the selected ServiceType. The Description is required to be provided in the request for each package contained in the shipment. The PackagingType should be set to a value other than: 4 (ptUPS25kgBox), 5 (ptUPS10kgBox), and 6 (ptPallet). Return shipments cannot be voided at the package level. Return shipments can be voided within 24 hours only. This is false by default.

Indicates that the ship request is made for UPS Print and Mail (PNM). This is applicable to return shipments only. In the server response, you will receive only a Tracking number for the shipment to be returned, but not a return label and/or return receipt. The label will be printed and mailed to your customer by UPS.

For return shipments, one of the following conditions must be met on CountryCode, CountryCode and CountryCode: At least two of these country codes are the same; None of these country codes are the same and are a member of the EU; None of these country codes are the same and at least one of them is not a member of the EU, and the shipper must have third country contract service. Following is a list of restrictions that are applicable when using return label types. This cannot be combined with COD, Saturday Delivery, Saturday Pickup, and/or Delivery Confirmation service options. For international shipments with return service, the Invoice flag is the only valid value for FormTypes. The availability of return service depends on the origin and destination country code, and on the selected ServiceType. The Description is required to be provided in the request for each package contained in the shipment. The PackagingType should be set to a value other than: 4 (ptUPS25kgBox), 5 (ptUPS10kgBox), and 6 (ptPallet). Return shipments cannot be voided at the package level. Return shipments can be voided within 24 hours only. This is false by default.

Indicates that the ship request is made for UPS Return Service 1-Attempt (RS1). This is applicable to return shipments only. UPS will make only one attempt to pick up your package. If the package cannot be collected, UPS will leave the return label at the pickup location. Note that the service charge will still apply. In the server response, you will receive only a Tracking number for the shipment to be returned, but not a return label and/or return receipt.

For return shipments, one of the following conditions must be met on CountryCode, CountryCode and CountryCode: At least two of these country codes are the same; None of these country codes are the same and are a member of the EU; None of these country codes are the same and at least one of them is not a member of the EU, and the shipper must have third country contract service. Following is a list of restrictions that are applicable when using return label types. This cannot be combined with COD, Saturday Delivery, Saturday Pickup, and/or Delivery Confirmation service options. For international shipments with return service, the Invoice flag is the only valid value for FormTypes. The availability of return service depends on the origin and destination country code, and on the selected ServiceType. The Description is required to be provided in the request for each package contained in the shipment. The PackagingType should be set to a value other than: 4 (ptUPS25kgBox), 5 (ptUPS10kgBox), and 6 (ptPallet). Return shipments cannot be voided at the package level. Return shipments can be voided within 24 hours only. This is false by default.

Indicates that the ship request is made for UPS Return Service 3-Attempt (RS3). This is applicable to return shipments only. UPS will attempt to pick up your package for three consecutive business days. After the third attempt, the return label will be returned to UPS. Note that the service charge will still apply. In the server response, you will receive only a Tracking number for the shipment to be returned, but not a return label and/or return receipt.

For return shipments, one of the following conditions must be met on CountryCode, CountryCode and CountryCode: At least two of these country codes are the same; None of these country codes are the same and are a member of the EU; None of these country codes are the same and at least one of them is not a member of the EU, and the shipper must have third country contract service. Following is a list of restrictions that are applicable when using return label types. This cannot be combined with COD, Saturday Delivery, Saturday Pickup, and/or Delivery Confirmation service options. For international shipments with return service, the Invoice flag is the only valid value for FormTypes. The availability of return service depends on the origin and destination country code, and on the selected ServiceType. The Description is required to be provided in the request for each package contained in the shipment. The PackagingType should be set to a value other than: 4 (ptUPS25kgBox), 5 (ptUPS10kgBox), and 6 (ptPallet). Return shipments cannot be voided at the package level. Return shipments can be voided within 24 hours only. This is false by default.

Used in Label Certification process.

This is required to be sent to UPS for each of the five test shipments along with the: .gif image of that shipment's shipping label (ShippingLabel), the html document (PackageShippingLabelHTML[i];), ShipmentConfirmRequest, ShipmentConfirmResponse, and ShipmentAcceptResponse of that shipment.

If the CertifyDirectory has been set, then the ShipmentAcceptRequest will be automatically written to disk in xml format under this file name: 'ShipAcceptRequest_LabelTrackingNumber.xml'.

Used in Label Certification process.

This is required to be sent to UPS for each of the five test shipments along with the: .gif image of that shipment's shipping label (ShippingLabel), the html document (PackageShippingLabelHTML[i];), ShipmentConfirmRequest, ShipmentConfirmResponse, and ShipmentAcceptRequest of that shipment.

If the CertifyDirectory has been set, then the ShipmentAcceptResponse will be automatically written to disk in xml format under this file name: 'ShipAcceptResponse_LabelTrackingNumber.xml'.

Used in Label Certification process.

This is required to be sent to UPS for each of the five test shipments along with the: .gif image of that shipment's shipping label (ShippingLabel), the html document (PackageShippingLabelHTML[i];), ShipmentConfirmResponse, ShipmentAcceptRequest, and ShipmentAcceptResponse of that shipment.

If the CertifyDirectory has been set, then the ShipmentConfirmRequest will be automatically written to disk in xml format under this file name: 'ShipConfirmRequest_LabelTrackingNumber.xml'.

Used in Label Certification process.

This is required to be sent to UPS for each of the five test shipments along with the: .gif image of that shipment's shipping label (ShippingLabel), the html document (PackageShippingLabelHTML[i];), ShipmentConfirmRequest, ShipmentAcceptRequest, and ShipmentAcceptResponse of that shipment.

If the CertifyDirectory has been set, then the ShipmentConfirmResponse will be automatically written to disk in xml format under this file name: 'ShipConfirmResponse_LabelTrackingNumber.xml'.

This is used when the html files of shipping labels are needed.

If this config is set to a valid value, then all shipping labels files (html and gif) are automatically written to disk in this specified location.

Note: When this is set, then the image file (gif) will automatically be written to disk (even if the ShippingLabelFile has not been set) along with the html file of the corresponding shipping label (html file serves as a wrapper for the image file). In this case, the name for the image file will automatically be set to 'labelTrackingNumber.gif'. This will overwrite any values already being set to this config by the user.

If the corresponding PackageShippingLabelFileHTML[i]; is not set, then the component will name the html file(s) for you in this format: 'labelTrackingNumber.html'. Otherwise, the name chosen by the user will be used.

If the ShippingLabelHTMLDirectory is empty and the PackageShippingLabelFileHTML[i]; is set, then the html file will be written to your default directory. Please note that when using html file for the shipping label, the image file should be written to disk as well (at the same directory as html file) and it should be named in this format 'labelTrackingNumber.gif'. Otherwise, the html file will show just the UPS shipping instructions and the label itself will not appear on it.

If both ShippingLabelHTMLDirectory and CertifyDirectory have been set, then the CertifyDirectory will take precedence over the ShippingLabelHTMLDirectory.

This is required to be provided in a ship request only if UPS On-Call Pickup service is requested (i.e., when the corresponding flag for On-Call Pickup (0x01000000) is present in ShipmentSpecialServices).

This should be entered in this format: HHmm.

This is required to be provided in a ship request only if UPS On-Call Pickup service is requested (i.e., when the corresponding flag for On-Call Pickup (0x01000000) is present in ShipmentSpecialServices). It can be also referred as the Closing Time for a pickup time window.

This should be entered in this format: HHmm.

This property is used to set specific details which will appear in line three of the Account Address. This is usually department information.

This property is used to set specific details which will appear in line three of the Recipient Address. This is usually department information.

This property is used to set specific details which will appear in line three of the Sender Address. This is usually department information.

This contains the USPS endorsement type and is required when using a Mail Innovations or SurePost ServiceType. The Valid values are as follows:

Required for forward shipments whose origin is the US and destination is Puerto Rico or Canada when using Mail Innovation service. Not available for any other shipments.

This is applicable and required when shipping to Puerto Rico or Canada using Mail Innovations domestic shipments. Provide a detailed description of items being shipped for documents and non-documents, such as 'annual reports', '9 mm steel screws', etc..

When creating a shipment using UPS Mail Innovations, a USPS tracking number will be returned in the USPSPICNumber field in the response. This number should be used when tracking packages.

Valid array indices are from 0 to PackageCount - 1.

This sets the contact name for when verbal confirmation is requested.

If this is set, verbal confirmation will be requested and VerbalConfirmationPhone must also be set

This sets the contact phone number for when verbal confirmation is requested.

If this is set, verbal confirmation will be requested and VerbalConfirmationName must also be set

It declares the type of weight unit to be used in calculating the weight of the shipment and each package contained in it.

Valid weight types are: LBS and KGS. Defaults to LBS if a value is not passed in the transaction. Depending on the selected country, the following measurement systems are valid: KGS/CM or LBS/IN (on domestic shipments, only the later combination is applicable). So, if the WeightUnit is set to KGS, its unit of measurements is set automatically to CM. Otherwise, it is set to IN (LBS/IN).

When this configuration setting is set to "true", UPS will use freight pricing for any generated labels. The user must have an existing agreement with UPS for freight pricing, such as "UPS Ground with Freight Pricing", in order to use this functionality. When set to "true", FRSCommodityCount, FRSCommodityFreightClass[i];, FRSCommodityFreightNMFC[i];, FRSPaymentType, FRSPaymentDescription, FRSPaymentAccountNumber, FRSPaymentPostalCode, and FRSPaymentCountryCode must be set.

This configuration property is used to specify the number of commodities for the freight rated shipment.

This configuration option is only valid when ReturnFreightPrices is true.

This configuration property indicates the freight class of the commodity.

The following table lists freight classes available from UPS freight services.

Valid indices are from 0 to FRSCommodityCount - 1.

This configuration option is only valid when ReturnFreightPrices is true.

This configuration property identifies the National Motor Freight Classification numbers.

Valid indices are from 0 to FRSCommodityCount - 1.

This configuration option is only valid when ReturnFreightPrices is true.

This configuration property identifies the sub code of National Motor Freight Classification numbers.

Valid indices are from 0 to FRSCommodityCount - 1.

This configuration option is only valid when ReturnFreightPrices is true.

This configuration property is used to specify the method of payment for the freight rated shipment. Valid options are:

This configuration option is only valid when ReturnFreightPrices is true.

This configuration option is used to specify a description for the Ground Freight Pricing payment type, for example the paying party's name.

This configuration option is only valid when ReturnFreightPrices is true.

This configuration options should be set to the UPS Account Number of the payor for Ground Freight Pricing. This account number is validated to ensure that Ground Freight Pricing is enabled for the account.

This configuration option is only valid when ReturnFreightPrices is true.

If FRSPaymentType is set to "2" for "Prepaid (Third Party) then the postal code for the third party payor must be specified.

This configuration option is only valid when ReturnFreightPrices is true.

If FRSPaymentType is set to "2" for "Prepaid (Third Party) then the country code for the third party payor must be specified.

This configuration option is only valid when ReturnFreightPrices is true.

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

This is the same as the AllowHTTPCompression property. This setting is exposed here for use by components that inherit from HTTP.

By default the component does not allow redirects to the same URL to avoid redirect loops. In some cases the server may intentionally redirect the client back to the same URL. In that case this setting may be set to True to allow the redirect to be followed. The default value is False.

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

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

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

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

Returns the raw number of bytes from the HTTP response data, prior to the component processing the data, whether it is chunked and/or compressed. This returns the same value as the Transfer event, by BytesTransferred.

The default value is false. If set to true the URL passed to the component will be URL encoded.

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

If this property is set to 2 (Same Scheme), the new URL is retrieved automatically only if the URL Scheme is the same, otherwise the component throws an exception.

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

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

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

The default value is 0 (Never). In this case, redirects are never followed, and the component throws an exception instead.

Valid options are:

• 0 - Never
• 1 - Always
• 2 - Same Scheme

The default value is false. If set to true the component will perform a GET on the new location. Otherwise it will use the same HTTP method again.

Possible values include "1.0", and "1.1". The default is "1.1".

This is the same as the IfModifiedSince property. This setting is exposed here for use by components that inherit from HTTP.

If true, the component will not send the 'Connection: Close' header. The absence of the Connection header indicates to the server that HTTP persistent connections should be used if supported. Note that not all server support persistent connections. You may also explicitly add the Keep-Alive header to the request headers by setting OtherHeaders to 'Connection: Keep-Alive'. If false, the connection will be closed immediately after the server response is received.

The default value for KeepAlive is false.

This config should be set when the TransferredHeaders collection is to be populated when a Header event has been fired. This value represents the number of headers that are to be saved in the collection.

To save all items to the collection , set this config to -1. If no items are wanted, set this to 0, which will not save any to the collection . The default for this config is -1, so all items will be included in the collection .

NOTE: This functionality is only available in Java and .NET.

This config should be set when populating the Cookies collection as a result of an HTTP request. This value represents the number of cookies that are to be saved in the collection .

To save all items to the collection , set this config to -1. If no items are wanted, set this to 0, which will not save any to the collection . The default for this config is -1, so all items will be included in the collection .

NOTE: This functionality is only available in Java and .NET.

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

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

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

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

This configuration option is useful for extending the functionality of the component beyond what is provided.

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

This is the same as AuthScheme. This setting is provided for use by components that do not directly expose Proxy properties.

This is the same as Password. This setting is provided for use by components that do not directly expose Proxy properties.

This is the same as Port. This setting is provided for use by components that do not directly expose Proxy properties.

This is the same as Server. This setting is provided for use by components that do not directly expose Proxy properties.

This is the same as User. This setting is provided for use by components that do not directly expose Proxy properties.

If TransferredDataLimit is set to 0 (default), no limits are imposed. Otherwise this reflects the maximum number of incoming bytes that can be stored by the component.

This configuration setting returns the complete set of raw headers as received from the server.

If UseChunkedEncoding is set to true, the component will use HTTP chunked encoding when posting if possible. HTTP chunked encoding allows large files to be sent in chunks instead of all at once. If set to false, the component will not use HTTP chunked encoding. The default value is false.

Note: Some servers (such as the ASP.NET Development Server) may not support chunked encoding.

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

If True, the component will use the default HTTP client for the platform (URLConnection in Java, WebRequest in .NET, or CFHTTPMessage in Mac/iOS) instead of the internal HTTP implementation. This is important for environments where direct access to sockets is limited or not allowed (as in the Google AppEngine for instance).

This is the value supplied in the HTTP User-Agent header. The default setting is "/n software IPWorks HTTP/S Component - www.nsoftware.com".

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

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

When set, this configuration setting allows you to specify a different timeout value for establishing a connection. Otherwise, the component will use Timeout for establishing a connection and transmitting/receiving data.

This is the same as AutoDetect. This setting is provided for use by components that do not directly expose Firewall properties.

If a FirewallHost is given, requested connections will be authenticated through the specified firewall when connecting.

If the FirewallHost setting is set to a Domain Name, a DNS request is initiated. Upon successful termination of the request, the FirewallHost setting is set to the corresponding address. If the search is not successful, an error is returned.

NOTE: This is the same as Host. This setting is provided for use by components that do not directly expose Firewall properties.

This entry is for IPPort only and does not work for other components that descend from IPPort.

If this entry is set, the component acts as a server. RemoteHost and RemotePort are used to tell the SOCKS firewall in which address and port to listen to. The firewall rules may ignore RemoteHost, and it is recommended that RemoteHost be set to empty string in this case.

RemotePort is the port in which the firewall will listen to. If set to 0, the firewall will select a random port. The binding (address and port) is provided through the ConnectionStatus event.

The connection to the firewall is made by calling the Connect method.

If FirewallHost is specified, the FirewallUser and FirewallPassword settings are used to connect and authenticate to the given firewall. If the authentication fails, the component throws an exception.

NOTE: This is the same as Password. This setting is provided for use by components that do not directly expose Firewall properties.

Note that the FirewallPort is set automatically when FirewallType is set to a valid value.

NOTE: This is the same as Port. This setting is provided for use by components that do not directly expose Firewall properties.

The appropriate values are as follows:

NOTE: This is the same as FirewallType. This setting is provided for use by components that do not directly expose Firewall properties.

If the FirewallHost is specified, the FirewallUser and FirewallPassword settings are used to connect and authenticate to the Firewall. If the authentication fails, the component throws an exception.

NOTE: This is the same as User. This setting is provided for use by components that do not directly expose Firewall properties.

When set, TCPKeepAlive will automatically be set to true. By default the operating system will determine the time a connection is idle before a TCP keep-alive packet is sent. This system default if this value is not specified here is 2 hours. In many cases a shorter interval is more useful. Set this value to the desired interval in milliseconds.

Note: This value is not applicable in Java.

When set, TCPKeepAlive will automatically be set to true. A TCP keep-alive packet will be sent after a period of inactivity as defined by KeepAliveTime. If no acknowledgement is received from the remote host the keep-alive packet will be re-sent. This setting specifies the interval at which the successive keep-alive packets are sent in milliseconds. This system default if this value is not specified here is 1 second.

Note: This value is not applicable in Java or MAC.

This property controls how a connection is closed. The default is True.

In the case that Linger is True (default), there are two scenarios for determining how long the connection will linger. The first, if LingerTime is 0 (default), the system will attempt to send pending data for a connection until the default IP protocol timeout expires.

In the second scenario, LingerTime is a positive value, the system will attempt to send pending data until the specified LingerTime is reached. If this attempt fails, then the system will reset the connection.

The default behavior (which is also the default mode for stream sockets) might result in a long delay in closing the connection. Although the component returns control immediately, the system could hold system resources until all pending data is sent (even after your application closes).

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

LingerTime is the time, in seconds, to leave the socket connection linger. This value is 0 by default, which means it will use the default IP protocol timeout.

The LocalHost setting 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 component initiate connections (or accept in the case of server components) only through that interface.

If the component is connected, the LocalHost setting 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).

This must be set before a connection is attempted. It instructs the component to bind to a specific port (or communication endpoint) in the local machine.

Setting this to 0 (default) enables the system to choose a port at random. The chosen port will be shown by LocalPort after the connection is established.

LocalPort cannot be changed once a connection is made. Any attempt to set this when a connection is active will generate an error.

This; setting is useful when trying to connect to services that require a trusted port in the client side. An example is the remote shell (rsh) service in UNIX systems.

MaxLineLength is the size of an internal buffer, which holds received data while waiting for an EOL string.

If an EOL string is found in the input stream before MaxLineLength bytes are received, the DataIn event is fired with the EOL parameter set to True, and the buffer is reset.

If no EOL is found, and MaxLineLength bytes are accumulated in the buffer, the DataIn event is fired with the EOL parameter set to False, and the buffer is reset.

The minimum value for MaxLineLength is 256 bytes. The default value is 2048 bytes. The maximum value is 65536 bytes.

This setting can be used to throttle outbound TCP traffic. Set this to the number of bytes to be sent per second. By default this is not set and there is no limit.

If set to a positive value, this setting defines the length of data records to be received. The component will accumulate data until RecordLength is reached and only then fire the DataIn event with data of length RecordLength. This allows data to be received as records of known length. This value can be changed at any time, including within the DataIn event.

The default value is 0, meaning this setting is not used.

If set to true, the socket's keep-alive option is enabled and keep-alive packets will be sent periodically to maintain the connection. Set KeepAliveTime and KeepAliveInterval to configure the timing of the keep-alive packets.

Note: This value is not applicable in Java.

When set to 0 (default), the component will use IPv4 exclusively. When set to 1, the component will use IPv6 exclusively. To instruct the component to prefer IPv6 addresses, but use IPv4 if IPv6 is not supported on the system, this setting should be set to 2. The default value is 0. Possible values are:

This setting determines whether the input or output stream is closed after the transfer completes. When set to True (default), all streams will be closed after a transfer is completed. In order to keep streams open after the transfer of data, set this to False. the default value is True.

When true, the socket will send all data that is ready to send at once. When false, the socket will send smaller buffered packets of data at small intervals. This is known as the Nagle algorithm.

By default, this config is set to false.

This setting specifies the allowed server certificate signature algorithms when UseManagedSecurityAPI is True and SSLEnabledProtocols is set to allow TLS 1.2.

When specified the component will verify that the server certificate signature algorithm is among the values specified in this setting. If the server certificate signature algorithm is unsupported the component throws an exception.

The format of this value is a comma separated list of hash-signature combinations. For instance:

IPPort.Config("UseManagedSecurityAPI=true");
IPPort.Config("SSLEnabledProtocols=3072"); //TLS 1.2
IPPort.Config("TLS12SignatureAlgorithms=sha1-rsa,sha1-dsa,sha256-rsa,sha256-dsa");

In order to not restrict the server's certificate signature algorithm, specify an empty string as the value for this setting, which will cause the signature_algorithms TLS 1.2 extension to not be sent.

If set to true, the component will reuse the context if and only if the following criteria are met:

• The target host name is the same.
• The system cache entry has not expired (default timeout is 10 hours).
• The application process that calls the function is the same.
• The logon session is the same.
• The instance of the component is the same.

This minimum cipher strength largely dependent on the security modules installed on the system. If the cipher strength specified is not supported, an error will be returned when connections are initiated.

Please note that this setting contains the minimum cipher strength requested from the security library. The actual cipher strength used for the connection is shown by the SSLStatus event.

Use this setting with caution. Requesting a lower cipher strength than necessary could potentially cause serious security vulnerabilities in your application.

When the provider is OpenSSL, SSLCipherStrength is currently not supported. This functionality is instead made available through the OpenSSLCipherList config setting.

Used to enable/disable the supported security protocols.

Not all supported protocols are enabled by default (the value of this setting is 4032). If you want more granular control over the enabled protocols, you can set this property to the binary 'OR' of one or more of the following values:

When the provider is OpenSSL, SSLCipherStrength is currently not supported. This functionality is instead made available through the OpenSSLCipherList config setting.

TLS 1.1 and TLS1.2 support are only available starting with Windows 7.

Change this setting to use security providers other than the system default.

Use this setting with caution. Disabling SSL security or pointing to the wrong provider could potentially cause serious security vulnerabilities in your application.

The special value "*" (default) picks the default SSL provider defined in the system.

Note: On Windows systems, the default SSL Provider is "Microsoft Unified Security Protocol Provider" and cannot be changed.

The following flags are defined (specified in hexadecimal notation). They can be or-ed together to exclude multiple conditions:

This functionality is currently not available in Java or when the provider is OpenSSL.

The enabled cipher suites to be used in SSL negotiation.

By default, the enabled cipher suites will include all available ciphers ("*").

The special value "*" means that the component will pick all of the supported cipher suites. If SSLEnabledCipherSuites is set to any other value, only the specified cipher suites will be considered.

Multiple cipher suites are separated by semicolons.

Example values when UseManagedSecurityAPI is False (default):

obj.config("SSLEnabledCipherSuites=*");
obj.config("SSLEnabledCipherSuites=CALG_AES_256");
obj.config("SSLEnabledCipherSuites=CALG_AES_256;CALG_3DES");

• CALG_3DES
• CALG_3DES_112
• CALG_AES
• CALG_AES_128
• CALG_AES_192
• CALG_AES_256
• CALG_AGREEDKEY_ANY
• CALG_CYLINK_MEK
• CALG_DES
• CALG_DESX
• CALG_DH_EPHEM
• CALG_DH_SF
• CALG_DSS_SIGN
• CALG_ECDH
• CALG_ECDH_EPHEM
• CALG_ECDSA
• CALG_ECMQV
• CALG_HASH_REPLACE_OWF
• CALG_HUGHES_MD5
• CALG_HMAC
• CALG_KEA_KEYX
• CALG_MAC
• CALG_MD2
• CALG_MD4
• CALG_MD5
• CALG_NO_SIGN
• CALG_OID_INFO_CNG_ONLY
• CALG_OID_INFO_PARAMETERS
• CALG_PCT1_MASTER
• CALG_RC2
• CALG_RC4
• CALG_RC5
• CALG_RSA_KEYX
• CALG_RSA_SIGN
• CALG_SCHANNEL_ENC_KEY
• CALG_SCHANNEL_MAC_KEY
• CALG_SCHANNEL_MASTER_HASH
• CALG_SEAL
• CALG_SHA
• CALG_SHA1
• CALG_SHA_256
• CALG_SHA_384
• CALG_SHA_512
• CALG_SKIPJACK
• CALG_SSL2_MASTER
• CALG_SSL3_MASTER
• CALG_SSL3_SHAMD5
• CALG_TEK
• CALG_TLS1_MASTER
• CALG_TLS1PRF

obj.config("SSLEnabledCipherSuites=*");
obj.config("SSLEnabledCipherSuites=TLS_DHE_DSS_WITH_AES_128_CBC_SHA");
obj.config("SSLEnabledCipherSuites=TLS_DHE_DSS_WITH_AES_128_CBC_SHA;TLS_DH_ANON_WITH_AES_128_CBC_SHA");

• TLS_DH_ANON_EXPORT_WITH_DES40_CBC_SHA
• TLS_DH_ANON_WITH_3DES_EDE_CBC_SHA
• TLS_DH_ANON_WITH_AES_128_CBC_SHA
• TLS_DH_ANON_WITH_AES_128_CBC_SHA256
• TLS_DH_ANON_WITH_AES_256_CBC_SHA
• TLS_DH_ANON_WITH_AES_256_CBC_SHA256
• TLS_DH_ANON_WITH_DES_CBC_SHA
• TLS_DH_ANON_WITH_RC4_128_MD5
• TLS_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA
• TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA
• TLS_DHE_DSS_WITH_AES_128_CBC_SHA
• TLS_DHE_DSS_WITH_AES_128_CBC_SHA256
• TLS_DHE_DSS_WITH_AES_256_CBC_SHA
• TLS_DHE_DSS_WITH_AES_256_CBC_SHA256
• TLS_DHE_DSS_WITH_DES_CBC_SHA
• TLS_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA
• TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA
• TLS_DHE_RSA_WITH_AES_128_CBC_SHA
• TLS_DHE_RSA_WITH_AES_128_CBC_SHA256
• TLS_DHE_RSA_WITH_AES_256_CBC_SHA
• TLS_DHE_RSA_WITH_AES_256_CBC_SHA256
• TLS_DHE_RSA_WITH_DES_CBC_SHA
• TLS_RSA_EXPORT_WITH_DES40_CBC_SHA
• TLS_RSA_WITH_3DES_EDE_CBC_SHA
• TLS_RSA_WITH_AES_128_CBC_SHA
• TLS_RSA_WITH_AES_128_CBC_SHA256
• TLS_RSA_WITH_AES_256_CBC_SHA
• TLS_RSA_WITH_AES_256_CBC_SHA256
• TLS_RSA_WITH_DES_CBC_SHA
• TLS_RSA_WITH_RC4_128_MD5
• TLS_RSA_WITH_RC4_128_SHA

SSLEnabledCipherSuites is used together with SSLCipherStrength.

Note: This configuration setting is available only in .NET and Java.

If AbsoluteTimeout is set to True, any method which does not complete within Timeout seconds will be aborted. By default, AbsoluteTimeout is False, and the timeout is an inactivity timeout.

Note: This option is not valid for UDP ports.

When the firewall is a tunneling proxy, use this property to send custom (additional) headers to the firewall (e.g. headers for custom authentication schemes).

This is the size of an internal queue in the TCP/IP stack. You can increase or decrease its size depending on the amount of data that you will be receiving. Increasing the value of the InBufferSize setting can provide significant improvements in performance in some cases.

Some TCP/IP implementations do not support variable buffer sizes. If that is the case, when the component is activated the InBufferSize reverts to its defined size. The same happens if you attempt to make it too large or too small.

This is the size of an internal queue in the TCP/IP stack. You can increase or decrease its size depending on the amount of data that you will be sending. Increasing the value of the OutBufferSize setting can provide significant improvements in performance in some cases.

Some TCP/IP implementations do not support variable buffer sizes. If that is the case, when the component is activated the OutBufferSize reverts to its defined size. The same happens if you attempt to make it too large or too small.

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 to false will ensure that the component does not attempt to process external events.

If set to True, when the component creates a thread the thread's IsBackground property will be explicitly set to True. By default this setting is False.

By default the component will use the system security libraries to perform cryptographic functions. This means 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 to True tells the component to use the internal managed implementation instead of using the system's security API.

Note that when this value is set the product's system dll is no longer required as a reference, as all unmanaged code is stored in this file.