4D Shipping SDK 2020 .NET Edition
4D Shipping SDK 2020 .NET Edition
Questions / Feedback?

UPSShip Configuration

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

UPSShip Configuration Settings

RawRequest:   Contains the complete request sent to the Server.

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

RawResponse:   Contains the complete response returned by the Server.

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

XPath:   Used to set the XPath within the response from the server.

XPath implements a subset of the XML XPath specification, allowing you to point to specific elements in the RawResponse. XPath is 1-indexed. 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:

'name' A particular element name
name[i] The i-th subelement of the current element with the given name
[i] The i-th subelement of the current element
[last()] The last subelement of the current element
[last()-i] The subelement located at the last location minus i in the current element
name[@attrname="attrvalue"] The subelement containing a particular value for a given attribute (supports single AND double quotes)
.. The parent of the current element

When XPath is set to a valid path...

HasXPath:   Determines whether a specific element exists in the document.

This method determines whether a particular XPath exists within the document. This may be used to check if a path exists before setting it via XPath. This method returns True if the XPath exists, False if not.

XParent:   The parent of the current element.

The current element is specified via the XPath.

XElement:   The name of the current element.

The current element is specified via the XPath.

XText:   The text of the current element.

The current element is specified via the XPath.

XChildCount:   The number of records in the XChild arrays.

This property controls the size of the following arrays:

XChildElement[i]:   The name of the indexed child element.

The size of the array is controlled by XChildCount.

XChildText[i]:   The text of the indexed child element.

The size of the array is controlled by XChildCount.

XAttrCount:   The number of records in the XAttr arrays.

This property controls the size of the following arrays:

XAttrName[i]:   The name of the indexed attribute.

The size of the array is controlled by XAttrCount.

XAttrValue[i]:   The value of the indexed attribute.

The size of the array is controlled by XAttrCount.

Warning:   Warning message returned by the server.

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

AlternateDeliveryAddress:   Used to specify an XML or SOAP aggregate for Hold for Pickup or Delivery at UPS Access Points.

The specified aggregate will be contained within the "AlternateDeliveryAddress" element of the request.

Sample SOAP aggregate when UseSOAP configuration setting is set to True:

<Name>THE UPS STORE</Name>
<AttentionName>THE UPS STORE</AttentionName>
<UPSAccessPointID></UPSAccessPointID>
<Address>
  <AddressLine>1289 FORDHAM BLVD</AddressLine>
  <City>Chapel Hill</City>
  <StateProvinceCode>NC</StateProvinceCode>
  <PostalCode>27514-6110</PostalCode>
  <CountryCode>US</CountryCode>
  <POBoxIndicator></POBoxIndicator>
</Address>

Sample XML aggregate when UseSOAP configuration setting is set to False:

<Name>THE UPS STORE</Name>
<AttentionName>THE UPS STORE</AttentionName>
<UPSAccessPointID></UPSAccessPointID>
<Address>
  <AddressLine1>1289 FORDHAM BLVD</AddressLine1>
  <AddressLine2></AddressLine2>
  <AddressLine3></AddressLine3>
  <City>Chapel Hill</City>
  <StateProvinceCode>NC</StateProvinceCode>
  <PostalCode>27514-6110</PostalCode>
  <CountryCode>US</CountryCode>
  <POBoxIndicator></POBoxIndicator>
</Address>

IncludeNegotiatedRates:   Whether to include the NegotiatedRatesIndicator in the request.

This controls whether the NegotiatedRatesIndicator is sent in the request. When sent UPS will return the negotiated rates for the shipper account. When not sent UPS will return the standard, list rates. The default value is True.

ShipmentIndicationType:   Whether shipment is Hold For Pickup or Delivery at UPS Access Points.

Required to indicate whether shipment is Hold For Pickup at UPS Access Point for use by approved shippers to identify a UPS Access Point location as an alternate delivery option during shipment preparation or UPS Access Point Delivery, to ship parcels directly to a UPS Access Point location for collection by the receiver.

This configuration setting is required when sending an alternate delivery address via the AlternateDeliveryAddress configuration setting.

Possible values:

Value Description
1 Hold for Pickup at UPS Access Point
2 UPS Access Point Delivery

NotificationLanguage:   Used to specify the language for Alternate Delivery Location notifications and UAP Shipper notifications.

Used to specify the language for Alternate Delivery Location notifications and UAP Shipper notifications. The default value is ENG

Refer to NotificationDialect configuration setting for possible Language / Dialect combinations.

NotificationDialect:   Used to specify the dialect for Alternate Delivery Location notifications and UAP Shipper notifications.

Used to specify the dialect for Alternate Delivery Location notifications and UAP Shipper notifications. The default value is US

Possible Language / Dialect combinations:

Language Dialect
CES 97
DAN 97
DEU 97
ELL 97
ENG GB
ENG US
ENG CA
FIN 97
FRA 97
FRA CA
HEB 97
HUN 97
ITA 97
NLD 97
NOR 97
POL 97
POR 97
RON RO
RUS 97
SLK 97
SPA 97
SPA PR
SWE 97
TUR 97
VIE 97
ZHO TW

ItemizedChargesCount:   The count of itemized charges.

The count of itemized charges in the response.

These charges can come back at both the shipment and package level. By default they return the shipment level charges. To access the charges for each package, set PackageServiceIndex first. Below is an example:

rates.GetRates();
for (int i = 0; i < rates.Services.Count; i++)
{
  rates.PackageServiceIndex = i;
  int chargesCount = Int32.Parse(rates.Config("ItemizedChargesCount"));
  for (int x = 0; x < chargesCount; x++)
  {
    Console.WriteLine(i + "-" + x + " " + rates.Config("ItemizedChargesCode[" + x + "]"));
    Console.WriteLine(i + "-" + x + " " + rates.Config("ItemizedChargesCurrencyCode[" + x + "]"));
    Console.WriteLine(i + "-" + x + " " + rates.Config("ItemizedChargesMonetaryValue[" + x + "]"));
  }
}

These charges may only come back if SubVersion is 1607 or greater.

ItemizedChargesCode[i]:   The Accesorial/Surcharge code of the itemized charge.

The Accesorial/Surcharge code of the itemized charge.

These charges can come back at both the shipment and package level. By default they return the shipment level charges. To access the charges for each package, set PackageServiceIndex first.

These charges may only come back if SubVersion is 1607 or greater.

ItemizedChargesCurrencyCode[i]:   The currency used for the charge.

The currency used for the charge.

These charges can come back at both the shipment and package level. By default they return the shipment level charges. To access the charges for each package, set PackageServiceIndex first.

These charges may only come back if SubVersion is 1607 or greater.

ItemizedChargesMonetaryValue[i]:   The amount being charged.

The amount of the Accesorial/Surcharge.

These charges can come back at both the shipment and package level. By default they return the shipment level charges. To access the charges for each package, set PackageServiceIndex first.

These charges may only come back if SubVersion is 1607 or greater.

ItemizedChargesSubType[i]:   The subtype of the itemized charge.

The subtype of the Accesorial/Surcharge.

These charges can come back at both the shipment and package level. By default they return the shipment level charges. To access the charges for each package, set PackageServiceIndex first.

These charges may only come back if SubVersion is 1607 or greater.

SubVersion:   UPS SubVersion.

UPS uses sub version strategy to give back new elements in the response when there is no functionality change in the request or to enhance the existing functionality. Valid values are 1601, 1607, 1701, 1707.

This setting is only applicable when using UPS.

TaxInformationIndicator:   Controls whether to send a TaxInformationIndicator.

This configuration setting controls whether to send a TaxInformationIndicator in the request or not. The default value is "false".

UseSOAP:   Whether or not to use UPS' webservices.

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.

EPRAReleaseCode:   Package Release code that allows the consignee or claimant to pick-up a package at a UPS Access Point.

The shipper must proivde the Package Release Code to the consignee so that they can provide the code to the UPS Access Point personnel as another item for authentication before the package is released to them. It must be between 4-6 characters.

This configuration setting is only valid when ShipmentIndicationType is set to 1.

AccountTotalNetCharge:   Net sum of negotiated rates applied to the whole shipment (if applicable).

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.

BarCodeReference:   Determines whether the reference number's value will be bar coded on the shipping label.

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.

CertifyDirectory:   The name of the directory where the files needed for Label Certification are written.

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.

CurrencyCode:   The currency code associated with the monetary values present in the request.

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.

Currency Name Currency Code
AFGHANI AFA
AFGHANI AFG
ALGERIA DZD
ALGERIAN DINAR ALD
ARGENTINE PESO ARN
ARGENTINE PESO ARP
ARUBIAN CUR. CD NAF
ARUBIAN GUILDER AWG
AUSTRALIAN DOLLAR AUD
AUSTRIAN EURO EUR
BAHAMIAN DOLLAR BSD
BAHRAINI DINAR BHD
BAHT BHT
BAHT THB
BALBOA BAL
BALBOA PAB
BARBADOS DOLLAR BBD
BARBADOS DOLLAR BDD
BELGIUM EURO EUR
BELIZE DOLLAR BZD
BERMUDA DOLLAR BMD
BERMUDAN DOLLAR BED
BOLIVAR VBO
BOLIVAR VEB
BOLIVIAN PESO BOP
BOSNIA DINAR BAD
BRITISH POUND UKL
BRUNEI DOLLAR BND
BRUNEI DOLLAR BRD
BURUNDI FRANC BIF
BURUNDI FRANC FRB
CANADIAN DOLLAR CAD
CAYMAN DOLLAR CID
CAYMAN DOLLAR KYD
CEDI GHC
CFA FRANC AFR
CFA FRANC XAF
CFA FRANC XOF
CFP FRANC PFR
CFP FRANC XPF
CHILEAN PESO CHP
CHILEAN PESO CLP
COLOMBIAN PESO COP
COMOROS FRANC KMF
CONGO, DEMOCRATIC REPUBLIC OF CDF
CORDOBA COR
CORDOBA NIC
COSTA RIC COLON CRC
COSTA RICAN COLON CFC
CP VERDE ESCUDO CVE
CRUZEIRO BRC
CRUZEIRO CRU
CUBAN PESO CUP
CYPRUS POUND CYL
CYPRUS POUND CYP
DALASI GAD
DALASI GMD
DANISH KRONE DKK
DANISH KRONE DKR
DEUTSCHE MARK DMK
DJIBOUTI FRANC DFR
DJIBOUTI FRANC DJF
DOBRA STD
DOMINICAN REP DOP
DONG VDD
DONG VND
E.CARI.DOLLAR ECD
EAST CARRIBEAN DOLLAR XCD
EGYPTIAN POUND EGL
EGYPTIAN POUND EGP
EKWELE GQE
EL SAL. COLON SAC
EL SALVADOR COLON SVC
ESTLAND KROWN EKR
ESTONIA KRONERS EEK
ETHIOPIAN BIRR ETB
EURO EUR
EUROP. CUR. UNT XEU
FIJI DOLLAR FID
FIJI DOLLAR FJD
FINNISH EURO EUR
FORINT FOR
FORINT HUF
FRANC CFA CFA
FRENCH EURO EUR
FRF FFR HRK
GERMAN EUR EUR
GIBRALTAR POUND GBL
GIBRALTAR POUND GIP
GOURDE GOU
GOURDE HTG
GREEK EURO EUR
GUARANI GUA
GUARANI PYG
GUINEA-BISSAU PESO GWP
GUINE-BS.PESO GWE
GUYANA DOLLAR GYD
HONG KONG DOLLAR HKD
ICELAND KRONA IKR
ICELAND KRONA ISK
INDIAN RUPEE RPS
INDIAN RUPES INR
IRANIAN RIAL IRI
IRANIAN RIAL IRR
IRAQI DINAR IQD
IRAQI DINAR IRD
IRISH EURO EUR
ITALIAN EURO EUR
JAMAICAN DOLLAR JAD
JAMAICAN DOLLAR JMD
JAPANESE YEN JPY
JAPANESE YEN JYE
JORDANIAN DINAR JOD
KENYA SCHILLING KES
KINA NGK
KINA PGK
KIP KIP
KIP LAK
KORUNA CKR
KORUNA CSK
KORUNA CZK
KORUNA SKK
KUWAITI DINAR KUD
KUWAITI DINAR KWD
KWACHA MWK
KWACHA ZMK
KWANZA AKZ
KWANZA AOK
KYAT BUK
KYAT BUR
LEBANESE POUND LBP
LEBANESE POUND LEL
LEK ALL
LEK LEK
LEMPIRA HNL
LEMPIRA LEM
LEONE SLE
LEONE SLL
LEU LEI
LEU ROL
LEV BGL
LEV LEV
LIBERIAN DOLLAR LID
LIBERIAN DOLLAR LRD
LIBYAN DOLLAR LBD
LIBYAN DOLLAR LYD
LILANGENI SZL
LITAS UAH
LITHUANIA LITAS LTL
LITHUANIA RUBLE LTR
LUXEMBOURG FRANC LFR
LUXEMBOURG FRANC LUF
MALAGASY FRANC FMG
MALAGASY FRANC MGF
MALAYSIAN RINGGIT MYR
MALDIVE RUPEE MVR
MALETESE MAL
MALI FRANC MLF
MALOTI LSM
MALTESE POUND MTP
MARK DER DDR MRK
MAURITIUS RUPEE MAR
MAURITIUS RUPEE MUR
MAYLASIAN RINGGIT RGT
METICAL ESM
METICAL MZM
MEXICAN PESO MEP
MEXICAN PESO MXN
MEXICAN PESO MXP
MOROCCAN DIRHAM MAD
MOROCCAN DIRHAM MDH
NAIRA NGN
NAMIBIA DOLLARS NAD
NEPALESE RUPEE NER
NEPALESE RUPEE NPR
NETH. AN GUILDER AFL
NETHERLANDS ANTILLIAN GUILDER ANG
NETHERLANDS EURO EUR
NEW TAIWAN DOLLAR NTD
NEW TAIWAN DOLLAR TWD
NEW YUGOSLAVIAN DINAR CTD
NEW YUGOSLAVIAN DINAR YUD
NEW ZEALAND DOLLAR NZD
NORWEGIAN KRONE NKR
NORWEGIAN KRONE NOK
OMANI RIAL OMR
OMANI RIAL RIO
OUGUIYA MOG
OUGUIYA MRO
PAANGA TOP
PAKISTAN RUPEE PKR
PAKSTAN RUPEE PAR
PATACA MOP
PHILLIPINE PESO PHP
POLISH ZLOTY PLN
PORTUGESE EURO EUR
POUND STERLING GBP
PULA BTP
PULA BWP
QATARI RIAL QAR
QATARI RIAL QRI
QUETZAL GTO
QUETZAL QUE
REPUBLIC OF CONGO (ZAIRE) ZRN
RIEL KHR
RIEL RLS
ROUBLE ROU
ROUBLE SUR
RUPIAH IDR
RUPIAH RPA
RUSSIAN FEDERATION RUB
RUSSIAN ROUBLE RUR
RWANDA FRANC FRR
RWANDA FRANC RWF
S KOREAN WON KRW
S KOREAN WON WON
SAUDI RIAL ARI
SCHEKEL ISL
SEYCHELL.RUPEE SCR
SEYCHELL.RUPEE SER
SHEKEL ILS
SINGAPORE DOLLAR SGD
SINGAPORE DOLLAR SID
SLOVENIA SIT
SOL PES
SOL SOL
SOLOMON ISLANDS DOLLAR SBD
SOMALI SHILLING SOS
SOMALI SHILLING SOM
SOUTH AFRICAN RAND SAR
SOUTH AFRICAN RAND ZAR
SPANISH EURO EUR
SRI LANKA RUPEE CER
SRI LANKA RUPEE LKR
SRNME.GUILDER SFL
SRNME.GUILDER SRG
ST HELENA POUND SHP
SUCRE ECS
SUCRE SUC
SUDANESE POUND SDP
SUDANESE POUND SUL
SWEDISH KRONA SEK
SWEDISH KRONA SKR
SWISS FRANC SFR
SWISS FRANK CHF
SYLI GNS
SYLI GSI
SYRIAN POUND SYL
SYRIAN POUND SYP
TAKA BDT
TALA SAT
TALA WST
TIMOR ESCUDO TPE
TNZN.SHILLING TAS
TNZN.SHILLING TZS
TRINIDAD AND TOBAGO DOLLAR TTD
TUGRIK MNT
TUGRUG TUG
TUNISIAN DINAR TND
TUNISIAN DINAR TUD
TURKISH LIRA TRL
TURKISH LIRA TUL
UAE DIRHAM ADH
UAE DIRHAM AED
UGANDA SHILLING UGS
URUGUAYAN PESO NUP
URUGUAYAN PESO UYP
US DOLLAR USD
VATU VUV
YEMENI DINAR DYD
YEMENI DINAR YDD
YEMENI RIAL YEM
YEMENI RIAL YER
YUAN RENMINBI RMB
YUAN RENMINIBI CNY
ZAIRE ZAI
ZAIRE ZRZ
ZIMBABWE DOLLAR ZWD

ElectronicReturnLabel:   Indicates that you are arranging for UPS to email a return label to your customer.

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.

HazMatPackagingTypeQuantity[i]:   The number of pieces of the specific commodity.

The number of pieces of the specific commodity. Valid values are 1 to 999.

This setting is only applicable when using UPS. Valid array indices are from 0 to Packages.Count - 1

SubVersion must be set to a value equal or greater than 1701 for shipping Dangerous Goods with UPS.

HazMatSubRiskClass[i]:   Secondary hazardous characteristics of a package.

Secondary hazardous characteristics of a package. (There can be more than one - separate each with a comma). Recommended if HazMatCommodityRegulatedLevelCode = LQ or FR and if the field applies to the material by regulation.

This setting is only applicable when using UPS. Valid array indices are from 0 to Packages.Count - 1

SubVersion must be set to a value equal or greater than 1701 for shipping Dangerous Goods with UPS.

HazMataDRItemNumber[i]:   The type of regulated goods for an ADR package where ADR is for Europe to Europe ground movement.

The type of regulated goods for an ADR package where ADR is for Europe to Europe ground movement.

This setting is only applicable when using UPS. Valid array indices are from 0 to Packages.Count - 1

SubVersion must be set to a value equal or greater than 1701 for shipping Dangerous Goods with UPS.

HazMataDRPackingGroupLetter[i]:   Required if the field applies to the material by regulation. Must be shown in Roman Numerals.

Required if the field applies to the material by regulation. Must be shown in Roman Numerals. Valid values: 1 - I, 2 = II, 3 = III, and blank.

This setting is only applicable when using UPS. Valid array indices are from 0 to Packages.Count - 1

SubVersion must be set to a value equal or greater than 1701 for shipping Dangerous Goods with UPS.

HazMatTechnicalName[i]:   The technical name (when required) for the specified commodity.

The technical name (when required) for the specified commodity. Required if HazMatCommodityRegulatedLevelCode = LQ or FR and if the field applies to the material by regulation.

This setting is only applicable when using UPS. Valid array indices are from 0 to Packages.Count - 1

SubVersion must be set to a value equal or greater than 1701 for shipping Dangerous Goods with UPS.

HazMatHazardLabelRequired[i]:   Defines the type of label that is required on the package for the commodity.

Defines the type of label that is required on the package for the commodity. Not applicable if HazMatCommodityRegulatedLevelCode = LR or EQ.

This setting is only applicable when using UPS. Valid array indices are from 0 to Packages.Count - 1

SubVersion must be set to a value equal or greater than 1701 for shipping Dangerous Goods with UPS.

HazMatClassDivisionNumber[i]:   This is the hazard class associated to the specified commodity.

This is the hazard class associated to the specified commodity. Required if HazMatCommodityRegulatedLevelCode is 'EQ', 'LQ' or 'FR'

This setting is only applicable when using UPS. Valid array indices are from 0 to Packages.Count - 1

SubVersion must be set to a value equal or greater than 1701 for shipping Dangerous Goods with UPS.

HazMatReferenceNumber[i]:   Optional reference number. Will be displayed only on label.

Optional reference number. Will be displayed only on label.

This setting is only applicable when using UPS. Valid array indices are from 0 to Packages.Count - 1

SubVersion must be set to a value equal or greater than 1701 for shipping Dangerous Goods with UPS.

HazMatQuantity[i]:   .

Required if HazMatCommodityRegulatedLevelCode = EQ, LQ or FR. The numerical value of the mass capacity of the regulated good.

This setting is only applicable when using UPS. Valid array indices are from 0 to Packages.Count - 1

SubVersion must be set to a value equal or greater than 1701 for shipping Dangerous Goods with UPS.

HazMatUOM[i]:   .

Required if HazMatCommodityRegulatedLevelCode = LQ, EQ or FR. The unit of measure used for the mass capacity of the regulated good. For Example: ml, L, g, mg, kg, cylinder, pound, pint, quart, gallon, ounce etc.

This setting is only applicable when using UPS. Valid array indices are from 0 to Packages.Count - 1

SubVersion must be set to a value equal or greater than 1701 for shipping Dangerous Goods with UPS.

HazMatPackagingType[i]:   The type of package used to contain the regulated good.

The type of package used to contain the regulated good. (Ex: Fiberboard Box). Required if HazMatCommodityRegulatedLevelCode = LQ or FR.

This setting is only applicable when using UPS. Valid array indices are from 0 to Packages.Count - 1

SubVersion must be set to a value equal or greater than 1701 for shipping Dangerous Goods with UPS.

HazMatIDNumber[i]:   This is the ID number (UN/NA/ID) for the specified commodity.

This is the ID number (UN/NA/ID) for the specified commodity. Required if HazMatCommodityRegulatedLevelCode = LR, LQ or FR and if the field applies to the material by regulation. UN/NA/ID Identification Number assigned to the specified regulated good. (Include the UN/NA/ID as part of the entry).

This setting is only applicable when using UPS. Valid array indices are from 0 to Packages.Count - 1

SubVersion must be set to a value equal or greater than 1701 for shipping Dangerous Goods with UPS.

HazMatProperShippingName[i]:   The Proper Shipping Name assigned by ADR, CFR or IATA.

The Proper Shipping Name assigned by ADR, CFR or IATA.

This setting is only applicable when using UPS. Valid array indices are from 0 to Packages.Count - 1

SubVersion must be set to a value equal or greater than 1701 for shipping Dangerous Goods with UPS.

HazMatAdditionalDescription[i]:   Additional remarks or special provision information.

Additional remarks or special provision information. Required if HazMatCommodityRegulatedLevelCode = LQ or FR and if the field applies to the material by regulation. Additional information that may be required by regulation about a hazardous material, such as, "Limited Quantity", DOT-SP numbers, EX numbers.

This setting is only applicable when using UPS. Valid array indices are from 0 to Packages.Count - 1

SubVersion must be set to a value equal or greater than 1701 for shipping Dangerous Goods with UPS.

HazMatPackagingGroupType[i]:   This is the packing group category associated to the specified commodity.

This is the packing group category associated to the specified commodity. Required if HazMatCommodityRegulatedLevelCode = LQ or FR and if the field applies to the material by regulation. Must be shown in Roman Numerals. Valid values: I, II, III, blank.

This setting is only applicable when using UPS. Valid array indices are from 0 to Packages.Count - 1

SubVersion must be set to a value equal or greater than 1701 for shipping Dangerous Goods with UPS.

HazMatPackagingInstructionCode[i]:   The packing instructions related to the chemical record.

The packing instructions related to the chemical record. Required if HazMatCommodityRegulatedLevelCode = LQ or FR and if the field applies to the material by regulation.

This setting is only applicable when using UPS. Valid array indices are from 0 to Packages.Count - 1

SubVersion must be set to a value equal or greater than 1701 for shipping Dangerous Goods with UPS.

HazMatEmergencyPhone[i]:   24 Hour Emergency Phone Number of the shipper.

24 Hour Emergency Phone Number of the shipper. Valid values for this field are (0) through (9) with trailing blanks. For numbers within the U.S., the layout is '1', area code, 7-digit number. For all other countries the layout is country code, area code, number.

This setting is only applicable when using UPS. Valid array indices are from 0 to Packages.Count - 1

SubVersion must be set to a value equal or greater than 1701 for shipping Dangerous Goods with UPS.

HazMatEmergencyContact[i]:   The emergency information, contact name and/or contract number.

The emergency information, contact name and/or contract number, required to be communicated when a call is placed to the HazMatEmergencyPhone. The information is required if there is a value in the HazMatEmergencyPhone field above and the shipment is with a US50 or PR origin and/or destination and the HazMatRegulationSet is IATA.

This setting is only applicable when using UPS. Valid array indices are from 0 to Packages.Count - 1

SubVersion must be set to a value equal or greater than 1701 for shipping Dangerous Goods with UPS.

HazMatReportableQuantity[i]:   .

Recommonded if HazMatCommodityRegulatedLevelCode = LQ or FR and if the field applies to the material by regulation. If reportable quantity is met, 'RQ' should be entered.

This setting is only applicable when using UPS. Valid array indices are from 0 to Packages.Count - 1

SubVersion must be set to a value equal or greater than 1701 for shipping Dangerous Goods with UPS.

HazMatRegulationSet[i]:   The Regulatory set associated with every regulated shipment.

The Regulatory Set associated with every regulated shipment. It must be the same across the shipment. Valid values are: ADR = Europe to Europe Ground Movement, CFR = HazMat regulated by US Dept of Transportation within the U.S. or ground shipments to Canada, IATA= Worldwide Air movement, TDG= Canada to Canada ground movement or Canada to U.S. standard movement.

For multiple ChemicalRecords per package or multiple packages containing different RegulationSet, RegulationSet of first ChemicalRecord would be considered for validating and rating the entire shipment.

This setting is only applicable when using UPS. Valid array indices are from 0 to Packages.Count - 1

SubVersion must be set to a value equal or greater than 1701 for shipping Dangerous Goods with UPS.

HazMatTransportationMode[i]:   Declares that a package was prepared according to ground, passenger aircraft, or cargo aircraft only.

Not applicable for ADR regulation set. Required for any other regulation set. Declares that a package was prepared according to ground, passenger aircraft, or cargo aircraft only.

ValueMeaning
Highway Highway Ground
PAX Passenger Aircraft
Passenger Aircraft Passenger Aircraft
CAO Cargo Aircraft Only
Cargo Aircraft Only Cargo Aircraft Only

This setting is only applicable when using UPS. Valid array indices are from 0 to Packages.Count - 1

SubVersion must be set to a value equal or greater than 1701 for shipping Dangerous Goods with UPS.

HazMatCommodityRegulatedLevelCode[i]:   Indicates the type of commodity.

Indicates the type of commodity. Required for subversion 1701 or greater.

ValueMeaning
FR Fully Regulated
LQ Limited Quantity
EQ Excepted Quantity
LR Lightly Regulated

This setting is only applicable when using UPS. Valid array indices are from 0 to Packages.Count - 1

SubVersion must be set to a value equal or greater than 1701 for shipping Dangerous Goods with UPS.

HazMatTransportCategory[i]:   Transport Category.

This setting is only applicable when using UPS. Valid array indices are from 0 to Packages.Count - 1

SubVersion must be set to a value equal or greater than 1701 for shipping Dangerous Goods with UPS.

HazMatTunnelRestrictionCode[i]:   .

Defines what is restricted to pass through a tunnel.

This setting is only applicable when using UPS. Valid array indices are from 0 to Packages.Count - 1

SubVersion must be set to a value equal or greater than 1701 for shipping Dangerous Goods with UPS.

HazMatChemicalRecordIdentifier[i]:   Identifies the Chemcial Record.

Required if SubVersion is greater than or equal to 1701.

This setting is only applicable when using UPS. Valid array indices are from 0 to Packages.Count - 1

SubVersion must be set to a value equal or greater than 1701 for shipping Dangerous Goods with UPS.

HazMatPackageIdentifier[i]:   Identifies the package containing Dangerous Goods.

Required for Hazmat shipment if SubVersion is greater than or equal to 1701.

This setting is only applicable when using UPS. Valid array indices are from 0 to Packages.Count - 1

SubVersion must be set to a value equal or greater than 1701 for shipping Dangerous Goods with UPS.

HazMatAllPackedInOneIndicator[i]:   Presence/Absence Indicator.

Presence/Absence Indicator. When set to true, indicates if multiple, different hazmat/chemicals are contained within one box in a package. When number of Hazmat containers in a package is more than one either HazMatAllPackedInOneIndicator or HazMatOverPackedIndicator is needed. The default value for this setting is false.

This setting is only applicable when using UPS. Valid array indices are from 0 to Packages.Count - 1

SubVersion must be set to a value equal or greater than 1701 for shipping Dangerous Goods with UPS.

HazMatOverPackedIndicator[i]:   Presence/Absence Indicator.

Presence/Absence Indicator. When set to true, indicates that one or more hazmat/chemicals are in separate boxes in a package. When number of Hazmat containers in a package is more than one either HazMatAllPackedInOneIndicator or HazMatOverPackedIndicator is needed. The default value for this setting is false.

This setting is only applicable when using UPS. Valid array indices are from 0 to Packages.Count - 1

SubVersion must be set to a value equal or greater than 1701 for shipping Dangerous Goods with UPS.

HazMatQValue[i]:   .

When a HazMat shipment specifies AllPackedInOneIndicator and the regulation set for that shipment is IATA, Ship API must require the shipment to specify a Q-Value with exactly one of the following values: 0.1; 0.2; 0.3; 0.4; 0.5; 0.6; 0.7; 0.8; 0.9; 1.0

This setting is only applicable when using UPS. Valid array indices are from 0 to Packages.Count - 1

SubVersion must be set to a value equal or greater than 1701 for shipping Dangerous Goods with UPS.

HighValueReportFileName:   Name of High Value Report (if applicable).

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

HighValueReport:   High Value Report (if applicable).

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.

IrregularIndicator:   The mail classification defined by UPS.

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

ValueMeaning
0 Not Applicable
1 Balloon
2 Oversized

LabelSize:   The size of the label.

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

Value Meaning
0 4x6
1 4x8

Machineable:   Determines whether the package is machineable or not.

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

MICostCenter:   Customer assigned identifier for report and billing summarization displays to the right of the Cost Center title.

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

MIPackageID:   Customer assigned unique piece identifier that returns visibility events.

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

Overwrite:   Determines whether label files will be overwritten.

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

PackageDeclaredValueType[i]:   The type of declared value (corresponding to the package at index i).

This determines the type of declared value for a package.

Value Meaning
0 (default) Declared Value
1 Shipper Declared Value

Valid array indices are from 0 to PackageCount - 1.

PackageShippingLabelHTML[i]:   HTML version of the shipping label (corresponding to the package at index i).

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.

PackageShippingLabelFileHTML[i]:   Name of the file where the HTML image of the shipping label (corresponding to the package at index i) is saved to disk.

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.

PickupEarliestTime:   The earliest time a shipment is ready to be picked up.

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.

PickupLatestTime:   The latest time a shipment can be picked up.

PickupFloorNumber:   The floor number of the pickup location.

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

PickupRoomNumber:   The room number of the pickup location.

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

RequestOption:   Defines if the address should be validated or not.

Value Meaning
0 Validate
1 Nonvalidate

ReturnsFlexibleAccessIndicator:   Defines if the Returns Flexible Access service should be used.

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.

ReturnPrintAndMail:   Indicates that you are arranging for UPS to print and mail a return label to your customer.

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.

ReturnServiceFirstAttempt:   Indicates that you are arranging for UPS to make one attempt to pick up the package to be returned.

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.

ReturnServiceThirdAttempt:   Indicates that you are arranging for UPS to make three attempts to pick up the package to be returned.

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.

RequestDeliveryConfirmation:   Whether or not to request delivery confirmation for the package/shipment.

When set to false, no delivery confirmation will be requested. However, this will not stop the driver from getting delivery confirmation if they feel they must.

ShipmentSignatureType:   Shipment signature type at the shipment level.

Specifies one of the Delivery Signature Options requested for this shipment. Possible values are:

ValueMeaning
0 None
1 Signature Required
2 Adult Signature Required

Note for package level signature types the SignatureType field must be set. The default value for this configuration setting is 0.

Indicates that a shipment requires a signature.

Set this property to require a signature for the entire shipment. Note that this is different from signatures required for individual packages, which is set via the Package properties.

Value Meaning
0 No signature
1 Signature required
2 Adult signature required

The default value is 0.

ShipmentAcceptRequest:   Contains the Shipment Accept Request sent to UPS.

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

ShipmentAcceptResponse:   Contains the Shipment Accept Response returned by UPS.

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

ShipmentConfirmRequest:   Contains the Shipment Confirm Request sent to UPS.

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

ShipmentConfirmResponse:   Contains the Shipment Confirm Response returned by UPS.

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

ShipmentSignatureType:   Shipment signature type at the shipment level.

Specifies one of the Delivery Signature Options requested for this shipment. Possible values are:

ValueMeaning
0 None
1 Signature Required
2 Adult Signature Required

Note for package level signature types the SignatureType field must be set. The default value for this configuration setting is 0.

Indicates that a shipment requires a signature.

Set this property to require a signature for the entire shipment. Note that this is different from signatures required for individual packages, which is set via the Package properties.

Value Meaning
0 No signature
1 Signature required
2 Adult signature required

The default value is 0.

ShippingLabelHTMLDirectory:   The name of the directory where the shipping label files are written.

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). It can be also referred as the Closing Time for a pickup time window.

This should be entered in this format: HHmm.

AccountAddress3:   Contains line three details for the Account Address.

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

RecipientAddress3:   Contains line three details for the Recipient Address.

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

SenderAddress3:   Contains line three details for the Sender Address.

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

USPSEndorsement:   The USPS endorsement type for Mail Innovations and SurePost shipments.

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

ValueMeaning
0 No Service Selected
1 Return Service Selected
2 Forwarding Service Requested
3 Address Service Requested
4 Change Service Requested

TotalCustomsValue:   Invoice Line Total Monetary Value when shipping to Puerto Rico or Canada using Mail Innovations domestic shipments.

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.

ShipmentDescription:   A textual description of goods for the whole shipment when shipping to Puerto Rico or Canada using Mail Innovations domestic 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..

USPSPICNumber[i]:   USPS Tracking Number (corresponding to the package at index i).

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.

VerbalConfirmationName:   The contact name for verbal confirmation.

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

VerbalConfirmationPhone:   The contact phone number for verbal confirmation.

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

WeightUnit:   Weight unit.

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

ReturnFreightPrices:   When true, UPS will use applicable freight pricing for shipments.

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.

FRSCommodityCount:   Number of commodities in the shipment.

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.

FRSCommodityFreightClass[i]:   The freight class of the commodity at the index.

This configuration property indicates the freight class of the commodity.

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

Freight Class
50
55
60
65
70
77.5
85
92.5
100
110
125
150
175
200
250
300
400
500

Valid indices are from 0 to FRSCommodityCount - 1.

This configuration option is only valid when ReturnFreightPrices is true.

FRSCommodityFreightNMFC[i]:   The National Motor Freight Classification numbers for the commodity at the index.

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.

FRSCommodityFreightNMFCSub[i]:   The sub-code of National Motor Freight Classification numbers for the commodity at the index.

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.

FRSPaymentType:   Method of payment for the shipment.

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

Option Payment Type
0 Prepaid
1 Freight Collect
2 Prepaid (Third Party)

This configuration option is only valid when ReturnFreightPrices is true.

FRSPaymentDescription:   Description for the Ground Freight Pricing payment type.

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.

FRSPaymentAccountNumber:   The UPS account number for the payor.

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.

FRSPaymentPostalCode:   The postal code of the payor for the Ground Freight Pricing shipment.

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.

FRSPaymentCountryCode:   The country code of the payor for the Ground Freight Pricing shipment.

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.

HTTP Configuration Settings

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

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.

AllowHTTPCompression:   This property enables HTTP compression for receiving data.

This setting enables HTTP compression for receiving data. When set to true, the component will accept compressed data. It will then uncompress the data it has received. The component will handle data compressed by both GZIP and Deflate compression algorithms.

When true, the component adds an "Accept-Encoding" header to the outgoing request. The value for this header can be controlled by the AcceptEncoding config. The default value for this header is "gzip, deflate".

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

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

If set to True (default) the component will automatically use HTTP/1.1 if the server does not support HTTP/2. If set to False the component throws an exception if the server does not support HTTP/2.

The default value is True.

AllowNTLMFallback:   Whether to allow fallback from Negotiate to NTLM when authenticating.

This setting only applies when AuthScheme is set to Negotiate. If set to True the component will automatically use NTLM if the server does not support Negotiate authentication. Note that the server must indicate it supports NTLM authentication via the WWW-Authenticate header for the fallback from Negotiate to NTLM to take place. The default value is False.

Append:   Whether to append data to LocalFile.

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.

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

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

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

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.

EncodeURL:   If set to true the URL will be encoded by the component.

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

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

This option determines what happens when the server issues a redirect. Normally, the 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

GetOn302Redirect:   If set to true the component will perform a GET on the new location.

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.

HTTPVersion:   The version of HTTP used by the component.

This property specifies the HTTP version used by the component. Possible values are:

  • "1.0"
  • "1.1" (default)
  • "2.0"

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

HTTP/2 Notes

When using HTTP/2 only secure (TLS/SSL) connections are currently supported. Attempting to use a plaintext URL with HTTP/2 will result in an error.

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

HTTP/2 is supported on all versions of Windows. If the Windows version is prior to Windows 8.1/Windows Server 2012 R2 the internal security implementation will be used. If the Windows version is Window 8.1/Windows Server 2012 R2 or later the system security libraries will be used by default.

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

HTTP/2 servers maintain a dynamic table of headers and values seen over the course of a connection. Typically these headers are inserted into the table via incremental indexing. To tell the component not to use incremental indexing for certain headers, and thus not update the dynamic table, set this configuration option to a comma-delimited list of the header names.

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

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

The format of the date value for IfModifiedSince is detailed in the HTTP specs. An example is:

Sat, 29 Oct 2017 19:43:31 GMT.

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

If true, the component will not send the 'Connection: Close' header. The absence of the Connection header indicates to the server that HTTP persistent connections should be used if supported. Note 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.

LogLevel:   The level of detail that is logged.

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

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

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

The value 2 (Verbose) additionally logs the content of the request and response including the headers and body for both the request and response.

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

MaxHeaders:   Instructs component to save the amount of headers specified that are returned by the server after a Header event has been fired.

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 .

MaxHTTPCookies:   Instructs component to save the amount of cookies specified that are returned by the server when a SetCookie event is fired.

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 .

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

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.

NegotiatedHTTPVersion:   The negotiated HTTP version.

This setting may be queried after the request is complete to indicate the HTTP version used. When HTTPVersion is set to "2.0" if the server does not support "2.0" the component will fallback to using "1.1" automatically. This setting will indicate which was used.

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

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.

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

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.

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

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

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

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

ProxyPort:   Port for the proxy server (default 80).

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

ProxyServer:   Name or IP address of a proxy server (optional).

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

ProxyUser:   A user name if authentication is to be used for the proxy.

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

TransferredData:   The contents of the last response from the server.

This setting contains the contents of the last response from the server.

TransferredDataLimit:   The maximum number of incoming bytes to be stored by the component.

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.

TransferredHeaders:   The full set of headers as received from the server.

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

UseChunkedEncoding:   Enables or Disables HTTP chunked encoding for transfers.

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.

ChunkSize:   Specifies the chunk size in bytes when using 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.

UsePlatformHTTPClient:   Whether or not to use the platform HTTP client.

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

UserAgent:   Information about the user agent (browser).

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

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

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

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

IPPort Configuration Settings

ConnectionTimeout:   Sets a separate timeout value for establishing a connection.

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.

FirewallAutoDetect:   Tells the component whether or not to automatically detect and use firewall system settings, if available.

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

FirewallHost:   Name or IP address of firewall (optional).

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.

FirewallListener:   If true, the component binds to a SOCKS firewall as a server (IPPort only).

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.

FirewallPassword:   Password to be used if authentication is to be used when connecting through the firewall.

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.

FirewallPort:   The TCP port for the FirewallHost;.

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.

FirewallType:   Determines the type of firewall to connect through.

The appropriate values are as follows:

0No firewall (default setting).
1Connect through a tunneling proxy. FirewallPort is set to 80.
2Connect through a SOCKS4 Proxy. FirewallPort is set to 1080.
3Connect through a SOCKS5 Proxy. FirewallPort is set to 1080.

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

FirewallUser:   A user name if authentication is to be used connecting through a firewall.

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.

KeepAliveTime:   The inactivity time in milliseconds before a TCP keep-alive packet is sent.

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.

KeepAliveInterval:   The retry interval, in milliseconds, to be used when a TCP keep-alive packet is sent and no response is received.

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.

Linger:   When set to True, connections are terminated gracefully.

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:   Time in seconds to have the connection linger.

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.

LocalHost:   The name of the local host through which connections are initiated or accepted.

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

LocalPort:   The port in the local host where the component binds.

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:   The maximum amount of data to accumulate when no EOL is found.

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.

MaxTransferRate:   The transfer rate limit in bytes per second.

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.

ProxyExceptionsList:   A semicolon separated list of hosts and IPs to bypass when using a proxy.

This setting optionally specifies a semicolon separated list of hostnames or IP addresses to bypass when a proxy is in use. When requests are made to hosts specified in this property the proxy will not be used. For instance:

www.google.com;www.nsoftware.com

TCPKeepAlive:   Determines whether or not the keep alive socket option is enabled.

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.

UseIPv6:   Whether to use IPv6.

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:

0 IPv4 Only
1 IPv6 Only
2 IPv6 with IPv4 fallback

UseNTLMv2:   Whether to use NTLM V2.

When authenticating with NTLM this setting specifies whether NTLM V2 is used. By default this value is False and NTLM V1 will be used. Set this to True to use NTLM V2.

CloseStreamAfterTransfer:   If true, the component will close the upload or download stream after the transfer.

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.

TcpNoDelay:   Whether or not to delay when sending packets.

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.

SSL Configuration Settings

CACertFilePaths:   The paths to CA certificate files when using Mono on Unix/Linux.

This setting specifies the paths on disk to CA certificate files when using Mono on Unix/Linux. It is not applicable in any other circumstances.

The value is formatted as a list of paths separated by semicolons. The component will check for the existence of each file in the order specified. When a file is found the CA certificates within the file will be loaded and used to determine the validity of server certificates.

The default value is:

/etc/ssl/ca-bundle.pem;/etc/pki/tls/certs/ca-bundle.crt;/etc/ssl/certs/ca-certificates.crt;/etc/pki/tls/cacert.pem

LogSSLPackets:   Controls whether SSL packets are logged when using the internal security API.

When the UseInternalSecurityAPI configuration setting is True, this setting controls whether SSL packets should be logged. By default, this setting is False, as it is only useful for debugging purposes.

When enabled, SSL packet logs are output using the SSLStatus event, which will fire each time an SSL packet is sent or received.

Enabling this setting has no effect if UseInternalSecurityAPI is False.

ReuseSSLSession:   Determines if the SSL session is reused.

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.

SSLCipherStrength:   The minimum cipher strength used for bulk encryption.

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.

SSLEnabledProtocols:   Used to enable/disable the supported security protocols.

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:

TLS1.312288 (Hex 3000)
TLS1.23072 (Hex C00) (Default)
TLS1.1768 (Hex 300) (Default)
TLS1 192 (Hex C0) (Default)
SSL3 48 (Hex 30)
SSL2 12 (Hex 0C)

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

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

Note: Enabling TLS 1.3 will automatically set UseInternalSecurityAPI to True.

SSLIncludeCertChain:   Whether the entire certificate chain is included in the SSLServerAuthentication event.

This setting specifies whether the Encoded parameter of the SSLServerAuthentication event contains the full certificate chain. By default this value is False and only the leaf certificate will be present in the Encoded parameter of the SSLServerAuthentication event.

If set to True all certificates returned by the server will be present in the Encoded parameter of the SSLServerAuthentication event. This includes the leaf certificate, any intermediate certificate, and the root certificate.

Note: When UseInternalSecurityAPI is set to True this value is automatically set to True. This is needed for proper validation when using the internal provider.

SSLProvider:   The name of the security provider to use.

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.

The special value "Internal" picks the internal SSL implementation. This does not rely on any system libraries. This is equivalent to setting UseInternalSecurityAPI to True.

Note: On Windows systems, the default SSL Provider is "Microsoft Unified Security Protocol Provider" and cannot be changed except to a value of "Internal".

SSLSecurityFlags:   Flags that control certificate verification.

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

0x00000001Ignore time validity status of certificate.
0x00000002Ignore time validity status of CTL.
0x00000004Ignore non-nested certificate times.
0x00000010Allow unknown Certificate Authority.
0x00000020Ignore wrong certificate usage.
0x00000100Ignore unknown certificate revocation status.
0x00000200Ignore unknown CTL signer revocation status.
0x00000400Ignore unknown Certificate Authority revocation status.
0x00000800Ignore unknown Root revocation status.
0x00008000Allow test Root certificate.
0x00004000Trust test Root certificate.
0x80000000Ignore non-matching CN (certificate CN not-matching server name).

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

SSLCACerts:   A newline separated list of CA certificate to use during SSL client authentication.

This setting specifies one or more CA certificates to be included in the request when performing SSL client authentication. Some servers require the entire chain, including CA certificates, to be presented when performing SSL client authentication. The value of this setting is a newline (CrLf) separated list of certificates. For instance:


-----BEGIN CERTIFICATE-----
MIIEKzCCAxOgAwIBAgIRANTET4LIkxdH6P+CFIiHvTowDQYJKoZIhvcNAQELBQAw
...
eWHV5OW1K53o/atv59sOiW5K3crjFhsBOd5Q+cJJnU+SWinPKtANXMht+EDvYY2w
F0I1XhM+pKj7FjDr+XNj
-----END CERTIFICATE-----
\r \n
-----BEGIN CERTIFICATE-----
MIIEFjCCAv6gAwIBAgIQetu1SMxpnENAnnOz1P+PtTANBgkqhkiG9w0BAQUFADBp
..
d8q23djXZbVYiIfE9ebr4g3152BlVCHZ2GyPdjhIuLeH21VbT/dyEHHA
-----END CERTIFICATE-----

SSLEnabledCipherSuites:   The cipher suite to be used in an SSL negotiation.

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 UseInternalSecurityAPI is False (default):

obj.config("SSLEnabledCipherSuites=*");
obj.config("SSLEnabledCipherSuites=CALG_AES_256");
obj.config("SSLEnabledCipherSuites=CALG_AES_256;CALG_3DES");
Possible values when UseInternalSecurityAPI is False (default) include:
  • 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
Example values when UseInternalSecurityAPI is True:
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");
Possible values when UseInternalSecurityAPI is True include:
  • TLS_DHE_DSS_WITH_AES_128_GCM_SHA256
  • TLS_DHE_DSS_WITH_AES_256_GCM_SHA384
  • 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_WITH_AES_128_GCM_SHA256
  • TLS_DHE_RSA_WITH_AES_256_GCM_SHA384
  • 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_WITH_AES_256_GCM_SHA384
  • TLS_RSA_WITH_AES_128_GCM_SHA256
  • 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
  • TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA
  • TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA
  • TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA
  • TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256
  • TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA384
  • TLS_ECDH_ECDSA_WITH_AES_256_GCM_SHA384
  • TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256
  • TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA
  • TLS_ECDH_RSA_WITH_AES_128_CBC_SHA
  • TLS_ECDH_RSA_WITH_AES_256_CBC_SHA
  • TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256
  • TLS_ECDH_RSA_WITH_AES_256_CBC_SHA384
  • TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256
  • TLS_ECDH_RSA_WITH_AES_256_GCM_SHA384
  • TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA
  • TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
  • TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
  • TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
  • TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384
  • TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
  • TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
  • TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA
  • TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
  • TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
  • TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
  • TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
  • TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
  • TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384

When TLS 1.3 is negotiated (see SSLEnabledProtocols) only the following cipher suites are supported:

  • TLS_AES_128_GCM_SHA256
  • TLS_AES_256_GCM_SHA384
  • TLS_CHACHA20_POLY1305_SHA256

SSLEnabledCipherSuites is used together with SSLCipherStrength.

TLS12SignatureAlgorithms:   Defines the allowed TLS 1.2 signature algorithms when UseInternalSecurityAPI is True.

This setting specifies the allowed server certificate signature algorithms when UseInternalSecurityAPI 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("UseInternalSecurityAPI=true");
IPPort.Config("SSLEnabledProtocols=3072"); //TLS 1.2
IPPort.Config("TLS12SignatureAlgorithms=sha1-rsa,sha1-dsa,sha256-rsa,sha256-dsa");
The default value for this setting is "sha1-rsa,sha1-dsa,sha224-rsa,sha224-dsa,sha256-rsa,sha256-dsa,sha384-rsa,sha384-dsa,sha512-rsa,sha512-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.

TLS12SupportedGroups:   The supported groups for ECC.

This setting specifies a comma separated list of named groups used in TLS 1.2 for ECC.

The default value is ecdhe_secp256r1,ecdhe_secp384r1,ecdhe_secp521r1.

When using TLS 1.2 and UseInternalSecurityAPI is set to True, the values refer to the supported groups for ECC. The following values are supported:

  • "ecdhe_secp256r1" (default)
  • "ecdhe_secp384r1" (default)
  • "ecdhe_secp521r1" (default)

TLS13KeyShareGroups:   The groups for which to pregenerate key shares.

This setting specifies a comma separated list of named groups used in TLS 1.3 for key exchange. The groups specified here will have key share data pregenerated locally before establishing a connection. This can prevent an additional round trip during the handshake if the group is supported by the server.

The default value is set to balance common supported groups and the computational resources required to generate key shares. As a result only some groups are included by default in this setting.

Note: All supported groups can always be used during the handshake even if not listed here, but if a group is used which is not present in this list it will incur an additional round trip and time to generate the key share for that group.

In most cases this setting does not need to be modified. This should only be modified if there is a specific reason to do so.

The default value is ecdhe_secp256r1,ecdhe_secp384r1,ffdhe_2048,ffdhe_3072

The values are ordered from most preferred to least preferred. The following values are supported:

  • "ecdhe_secp256r1" (default)
  • "ecdhe_secp384r1" (default)
  • "ecdhe_secp521r1"
  • "ffdhe_2048" (default)
  • "ffdhe_3072" (default)
  • "ffdhe_4096"
  • "ffdhe_6144"
  • "ffdhe_8192"

TLS13SupportedGroups:   The supported groups for (EC)DHE key exchange.

This setting specifies a comma separated list of named groups used in TLS 1.3 for key exchange. This setting should only be modified if there is a specific reason to do so.

The default value is ecdhe_secp256r1,ecdhe_secp384r1,ecdhe_secp521r1,ffdhe_2048,ffdhe_3072,ffdhe_4096,ffdhe_6144,ffdhe_8192

The values are ordered from most preferred to least preferred. The following values are supported:

  • "ecdhe_secp256r1" (default)
  • "ecdhe_secp384r1" (default)
  • "ecdhe_secp521r1" (default)
  • "ffdhe_2048" (default)
  • "ffdhe_3072" (default)
  • "ffdhe_4096" (default)
  • "ffdhe_6144" (default)
  • "ffdhe_8192" (default)

TLS13SignatureAlgorithms:   The allowed certificate signature algorithms.

This setting holds a comma separated list of allowed signature algorithms. Possible values are:

  • "ecdsa_secp256r1_sha256" (default)
  • "ecdsa_secp384r1_sha384" (default)
  • "ecdsa_secp521r1_sha512" (default)
  • "rsa_pkcs1_sha256" (default)
  • "rsa_pkcs1_sha384" (default)
  • "rsa_pkcs1_sha512" (default)
  • "rsa_pss_sha256" (default)
  • "rsa_pss_sha384" (default)
  • "rsa_pss_sha512" (default)
The default value is rsa_pss_sha256,rsa_pss_sha384,rsa_pss_sha512,rsa_pkcs1_sha256,rsa_pkcs1_sha384,rsa_pkcs1_sha512,ecdsa_secp256r1_sha256,ecdsa_secp384r1_sha384,ecdsa_secp521r1_sha512. This setting is only applicable when SSLEnabledProtocols includes TLS 1.3.

Socket Configuration Settings

AbsoluteTimeout:   Determines whether timeouts are inactivity timeouts or absolute timeouts.

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.

FirewallData:   Used to send extra data to the firewall.

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

InBufferSize:   The size in bytes of the incoming queue of the socket.

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.

OutBufferSize:   The size in bytes of the outgoing queue of the socket.

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.

Base Configuration Settings

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

UseBackgroundThread:   Whether threads created by the component are background threads.

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.

UseInternalSecurityAPI:   Tells the component whether or not to use the system security libraries or an internal implementation.

By default the component will use the system security libraries to perform cryptographic functions. When set to False 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 implementation instead of using the system's security API.

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 DLL is no longer required as a reference, as all unmanaged code is stored in that file.

 
 
Copyright (c) 2019 4D Payments Inc. - All rights reserved.
4D Shipping SDK 2020 .NET Edition - Version 20.0 [Build 7233]