ShipRequest Class

Properties   Methods   Events   Config Settings   Errors  

Allows you to create, send, and parse a custom request.

Syntax

dshippingsdk.Shiprequest

Remarks

The ShipRequest class allows you to easily create a custom request for any operation. This is useful if you wish to support a service not currently implement by the existing classs. Requests created by this class can be used with FedEx, USPS, USPS using Endicia, and UPS.

To use this class first form the body of the request. The request body must then be passed to the component. This is done in one of two ways. For USPS with Endicia, FedEx, and UPS set PostData to the body of the request. For USPS use AddParameter.

After specifying the request data to send to the server, call SubmitTo and pass the URL of the server. This will send the request to the server and the response will be returned.

Once the call to SubmitTo returns, the XPath property may be set to a valid path within the XML returned, and XText will hold the value of the element at the given path. A full list of XPath related properties that will help you parse the response is found below:

• XAttributes
• XChildren
• XElement
• XErrorPath
• XNamespace
• XParent
• XPath
• XPrefix
• XSubTree
• XText

Following are examples of using the class to create a request for different services. Note that these examples show how to implement functionality existing in other classs. To use any of the functionality demonstrated here, you may use the corresponding class instead.

FedEx Component.PostData = @"<?xml version="1.0" encoding="UTF-8" ?>" + @"<ProcessShipmentRequest xmlns="http://fedex.com/ws/ship/v9" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">" + "<WebAuthenticationDetail>" + "<UserCredential>" + "<Key>MyKey</Key>" + "<Password>MyPassword</Password>" + "</UserCredential>" + "</WebAuthenticationDetail>" + "<ClientDetail>" + "<AccountNumber>000000000</AccountNumber>" + "<Localization>" + "<LanguageCode>en</LanguageCode>" + "<LocaleCode>en</LocaleCode>" + "</Localization>" + "</ClientDetail>" + ... Component.SubmitTo("https://gatewaybeta.fedex.com:443/xml"); Component.XPath = "/ProcessShipmentReply/Notifications/Severity"; if(Component.XText == "SUCCESS") //The request was successful

USPS With Endicia Component.PostData = "postageRateRequestXML=<PostageRateRequest>" + "<RequesterID>test</RequesterID>" + "<CertifiedIntermediary>" + "<AccountID>123456</AccountID>" + "<PassPhrase>test</PassPhrase>" + "</CertifiedIntermediary>" + "<MailClass>ExpressMailInternational</MailClass>" + "<WeightOz>1</WeightOz>" + "<MailpieceShape>FlatRateEnvelope</MailpieceShape>" + "<AutomationRate>FALSE</AutomationRate>" + "<Machinable>TRUE</Machinable>" + "<Services>" + "<InsuredMail>OFF</InsuredMail>" + "</Services>" + "<FromPostalCode>10022</FromPostalCode>" + "<ToCountry>Algeria</ToCountry>" + "</PostageRateRequest>"; Component.ContentType = "application/x-www-form-urlencoded"; Component.SubmitTo("https://www.envmgr.com/LabelService/EwsLabelService.asmx/CalculatePostageRateXML"); Component.XPath = "/PostageRateResponse/Status"; if(Component.XText == "0") //The request was successful

USPS Component.AddParameter("XML",@"<CarrierPickupCancelRequest USERID="User" PASSWORD="Pass"><FirmName>ABC Corp.</FirmName>" + "<SuiteOrApt>Suite 777</SuiteOrApt>" + "<Address2>1390 Market Street</Address2>" + "<Urbanization></Urbanization>" + "<City>Houston</City>" + "<State>TX</State>" + "<ZIP5>77058</ZIP5>" + "<ZIP4>1234</ZIP4>" + "<ConfirmationNumber>WTC123456789</ConfirmationNumber>" + "</CarrierPickupCancelRequest>"); Component.AddParameter("API", "CarrierPickupCancel"); Component.ContentType = "application/x-www-form-urlencoded"; Component.SubmitTo("https://secure.shippingapis.com/ShippingAPITest.dll"); Component.XPath = "/CarrierPickupCancelResponse/Status"; Console.WriteLine(Component.XText);

Property List

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

Method List

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

Event List

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

Config Settings

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

BuildDOM Property (ShipRequest Class)

When True, an internal object model of the XML document is created.

Syntax

public boolean isBuildDOM();


public void setBuildDOM(boolean buildDOM);

Default Value

True

Remarks

Set BuildDOM to True when you need to browse the current document through XPath.

Validate is automatically set to True when BuildDOM is set to True.

Connected Property (ShipRequest Class)

This shows whether the class is connected.

Syntax

public boolean isConnected();


public void setConnected(boolean connected);

Default Value

False

Remarks

This property is used to determine whether or not the class is connected to the remote host.

Note: It is recommended to use the Connect or Disconnect method instead of setting this property.

This property is not available at design time.

ContentType Property (ShipRequest Class)

This property includes the content type for posts and puts.

Syntax

public String getContentType();


public void setContentType(String contentType);

Default Value

""

Remarks

If this property contains a nonempty string, a Content-Type HTTP request header is added to the request. The purpose of the header is to show the contents of the data during a Post or Put to the server.

The most common example is posting of HTML form input data. In that case, this property must be set to "application/x-www-form-urlencoded".

This property is not available at design time.

Firewall Property (ShipRequest Class)

A set of properties related to firewall access.

Syntax

public Firewall getFirewall();


public void setFirewall(Firewall firewall);

Remarks

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

FollowRedirects Property (ShipRequest Class)

This property determines what happens when the server issues a redirect.

Syntax

public int getFollowRedirects();


public void setFollowRedirects(int followRedirects);


Enumerated values:
  public final static int frNever = 0;
  public final static int frAlways = 1;
  public final static int frSameScheme = 2;

Default Value

0

Remarks

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

If this property is set to frSameScheme (2), the new URL is retrieved automatically only if the URLScheme is the same; otherwise, the class throws an exception.

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

Furthermore, if either the new URL server or port are different from the existing one, User and Password are also reset to empty. If, however, this property is set to frAlways (1), 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 frNever (0). In this case, redirects are never followed, and the class throws an exception instead.

HTTPMethod Property (ShipRequest Class)

This property includes the HTTP method used for the request.

Syntax

public String getHTTPMethod();


public void setHTTPMethod(String HTTPMethod);

Default Value

""

Remarks

This property contains the HTTP method used for the request. If an empty string is provided, the HTTPMethod is determined automatically by the method being called. You may change it to a custom value if you require an HTTP method other than what is provided by the class. When providing a custom value, make the request by calling the Post method.

This property is not available at design time.

Idle Property (ShipRequest Class)

The current status of the class.

Syntax

public boolean isIdle();

Default Value

True

Remarks

Idle will be False if the component is currently busy (communicating and/or waiting for an answer), and True at all other times.

This property is read-only.

LocalFile Property (ShipRequest Class)

This property includes the path to a local file for downloading. If the file exists, it is overwritten.

Syntax

public String getLocalFile();


public void setLocalFile(String localFile);

Default Value

""

Remarks

This property is used when getting a document.

If this property is empty, then the received data are provided through TransferredData and the Transfer event.

LocalHost Property (ShipRequest Class)

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

Syntax

public String getLocalHost();


public void setLocalHost(String localHost);

Default Value

""

Remarks

The LocalHost property contains the name of the local host as obtained by the gethostname() system call, or if the user has assigned an IP address, the value of that address.

In multi-homed hosts (machines with more than one IP interface) setting LocalHost to the value of an interface will make the class initiate connections (or accept in the case of server classs) only through that interface.

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

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

Namespaces Property (ShipRequest Class)

This property includes a collection of namespaces in the current stack.

Syntax

public XMLNamespaceList getNamespaces();

Remarks

This property contains a collection of XML namespaces, which are standards for providing uniquely named elements and attributes in an XML instance.

The default namespace is found at index 0.

This property is not valid for JSON data.

This collection is indexed from 0 to size -1.

This property is read-only and not available at design time.

OtherHeaders Property (ShipRequest Class)

This property includes other headers as determined by the user (optional).

Syntax

public String getOtherHeaders();


public void setOtherHeaders(String otherHeaders);

Default Value

""

Remarks

This property can be set to a string of headers to be appended to the HTTP request headers created from other properties like ContentType and From.

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

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

This property is useful for extending the functionality of the class beyond what is provided.

This property is not available at design time.

Parameters Property (ShipRequest Class)

Parameters to be sent in the request.

Syntax

public ShipParamList getParameters();


public void setParameters(ShipParamList parameters);

Remarks

This collection holds name value pairs to be sent in the request. Add required parameters using the AddParameter method before calling SubmitTo.

This property is not available at design time.

ParsedHeaders Property (ShipRequest Class)

This property includes a collection of headers returned from the last request.

Syntax

public HeaderList getParsedHeaders();

Remarks

This property contains a collection of headers returned from the last request. Whenever headers are returned from the server, the headers are parsed into a collection of headers. Each Header in this collection contains information describing that header.

MaxHeaders can be used to control the maximum number of headers saved.

This collection is indexed from 0 to size -1.

This property is read-only and not available at design time.

PostData Property (ShipRequest Class)

This property includes the data to post with the URL if the POST method is used.

Syntax

public byte[] getPostData();


public void setPostData(byte[] postData);

Default Value

""

Remarks

This property contains the data to post with the URL if the POST method is used. If this property contains a nonempty string, then if the HTTP POST method is used (Post method), the contents of this property are appended to the HTTP request after the HTTP headers.

An HTTP Content-Length header is also added to the request. Its value is the length of the string in PostData.

The most common example is posting of HTML form input data. In that case, the ContentType property must be set to application/x-www-form-urlencoded.

Example. Performing a Post:

HTTPControl.ContentType = "application/x-www-form-urlencoded" HTTPControl.PostData = "firstname=Tom&lastname=Thompson&country=US" HTTPControl.Post(myurl)

This property is not available at design time.

Proxy Property (ShipRequest Class)

A set of properties related to proxy access.

Syntax

public Proxy getProxy();


public void setProxy(Proxy proxy);

Remarks

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

SSLAcceptServerCert Property (ShipRequest Class)

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

Syntax

public Certificate getSSLAcceptServerCert();


public void setSSLAcceptServerCert(Certificate SSLAcceptServerCert);

Remarks

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

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

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

SSLCert Property (ShipRequest Class)

The certificate to be used during SSL negotiation.

Syntax

public Certificate getSSLCert();


public void setSSLCert(Certificate SSLCert);

Remarks

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

SSLProvider Property (ShipRequest Class)

This specifies the SSL/TLS implementation to use.

Syntax

public int getSSLProvider();


public void setSSLProvider(int SSLProvider);


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

Default Value

0

Remarks

This property specifies the SSL/TLS implementation to use. In most cases the default value of 0 (Automatic) is recommended and should not be changed. When set to 0 (Automatic) the class will select whether to use the platform implementation or the internal implementation depending on the operating system as well as the TLS version being used.

Possible values are:

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

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

SSLServerCert Property (ShipRequest Class)

The server certificate for the last established connection.

Syntax

public Certificate getSSLServerCert();

Remarks

SSLServerCert contains the server certificate for the last established connection.

SSLServerCert is reset every time a new connection is attempted.

This property is read-only.

StatusLine Property (ShipRequest Class)

This property is the first line of the last server response.

Syntax

public String getStatusLine();

Default Value

""

Remarks

This property contains the first line of the last server response. This value can be used for diagnostic purposes. If an HTTP error is returned when calling a method of the class, the error string is the same as the StatusLine property.

The HTTP protocol specifies the structure of the StatusLine as follows: [HTTP version] [Result Code] [Description].

This property is read-only and not available at design time.

Timeout Property (ShipRequest Class)

A timeout for the class.

Syntax

public int getTimeout();


public void setTimeout(int timeout);

Default Value

60

Remarks

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

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

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

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

Please note that by default, all timeouts are inactivity timeouts, i.e. the timeout period is extended by Timeout seconds when any amount of data is successfully sent or received.

The default value for the Timeout property is 60 seconds.

TransferredData Property (ShipRequest Class)

This property includes the content of the last response from the server.

Syntax

public byte[] getTransferredData();

Default Value

""

Remarks

This property contains the content of the last response from the server. If the LocalFile is empty, data are accumulated in TransferredData, and also can be received in the Transfer event. Otherwise, this property returns an empty string.

TransferredDataLimit controls the maximum amount of data accumulated in this property (by default, there is no limit).

This property is read-only and not available at design time.

TransferredDataLimit Property (ShipRequest Class)

This property includes the maximum number of bytes of data to be transferred.

Syntax

public long getTransferredDataLimit();


public void setTransferredDataLimit(long transferredDataLimit);

Default Value

0

Remarks

This property defines the maximum number of bytes of data to be transferred. The default value is zero, which means there is no limit to the amount of data the class will accumulate and parse. If this value is set to a number n that is greater than zero, the class will receive only the first n bytes of data from the server.

TransferredHeaders Property (ShipRequest Class)

This property includes the full set of headers as received from the server.

Syntax

public String getTransferredHeaders();

Default Value

""

Remarks

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

The Header event shows the individual headers as parsed by the class.

This property is read-only and not available at design time.

Validate Property (ShipRequest Class)

This property controls whether documents are validated during parsing.

Syntax

public boolean isValidate();


public void setValidate(boolean validate);

Default Value

True

Remarks

When true (default) the document will be validated during parsing. To disable validation set Validate to false. Disabling validation may be useful in cases where data can still be parsed even if the document is not well-formed.

XAttributes Property (ShipRequest Class)

A collection of attributes of the current element.

Syntax

public XMLAttributeList getXAttributes();


public void setXAttributes(XMLAttributeList XAttributes);

Remarks

This collection consists of all attributes of the current XML element. The component parses each attribute into a collection of XMLAttribute types.

This collection is indexed from 0 to size -1.

This property is not available at design time.

XChildren Property (ShipRequest Class)

Collection of child elements of the currently selected XML element.

Syntax

public XMLElementList getXChildren();


public void setXChildren(XMLElementList XChildren);

Remarks

This property contains a collection of child elements of the currently selected XML element. The elements are provided in the collection in the same order they are found in the XML document.

This collection is indexed from 0 to size -1.

This property is not available at design time.

XElement Property (ShipRequest Class)

The name of the current element.

Syntax

public String getXElement();


public void setXElement(String XElement);

Default Value

""

Remarks

The current element is specified via the XPath property.

XErrorPath Property (ShipRequest Class)

This property includes the XPath to check the server response for errors.

Syntax

public String getXErrorPath();


public void setXErrorPath(String XErrorPath);

Default Value

""

Remarks

This property contains an XPath to check the server response for errors. If the XPath exists, an exception will be thrown containing the value of the element at the path.

XNamespace Property (ShipRequest Class)

The namespace of the current element.

Syntax

public String getXNamespace();


public void setXNamespace(String XNamespace);

Default Value

""

Remarks

The current element is specified via the XPath property.

XParent Property (ShipRequest Class)

The parent of the current element.

Syntax

public String getXParent();

Default Value

""

Remarks

The current element is specified via the XPath property.

This property is read-only.

XPath Property (ShipRequest Class)

Provides a way to point to a specific element in the response.

Syntax

public String getXPath();


public void setXPath(String XPath);

Default Value

""

Remarks

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

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:

BuildDOM must be set to True prior to parsing the document for the XPath functionality to be available.

Example (Setting XPath)

XPrefix Property (ShipRequest Class)

The prefix of the current element.

Syntax

public String getXPrefix();


public void setXPrefix(String XPrefix);

Default Value

""

Remarks

The current element is specified via the XPath property.

XSubTree Property (ShipRequest Class)

A snapshot of the current element in the document.

Syntax

public String getXSubTree();

Default Value

""

Remarks

The current element is specified via the XPath property. In order for this property to work you must have the CacheContent set to true.

This property is read-only.

XText Property (ShipRequest Class)

The text of the current element.

Syntax

public String getXText();


public void setXText(String XText);

Default Value

""

Remarks

The current element is specified via the XPath property.

AddParameter Method (Shiprequest Class)

Adds a parameter to the query string.

Syntax

public void addParameter(String paramName, String paramValue);

Remarks

This method is used to add a parameter name and value to the query string to be sent to the server. Note that any parameters added with this method will be URL encoded automatically.

If ContentType is set to "application/x-www-form-urlencoded", any parameters added with this method will be sent to the server as form data in the body of the request, instead of as query string parameters.

Attr Method (Shiprequest Class)

Returns the value of the specified attribute.

Syntax

public String attr(String attrName);

Remarks

If the attribute does not exist, an empty string is returned if ErrorOnEmptyAttr is set to false, otherwise an exception is thrown.

Please refer to the XAttributes collection for more information.

Base64Decode Method (Shiprequest Class)

Decode base64 encoded string.

Syntax

public byte[] base64Decode(String encodedData);

Remarks

This method decodes the provided base64 encoded string. Some operations may result in base64 encoded data (such as a label image) being returned by the server. Use this method to decode such data. The decoded data is returned as a byte array.

Config Method (Shiprequest Class)

Sets or retrieves a configuration setting.

Syntax

public String config(String configurationString);

Remarks

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

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

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

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

DoEvents Method (Shiprequest Class)

Processes events from the internal message queue.

Syntax

public void doEvents();

Remarks

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

Get Method (Shiprequest Class)

This method fetches the document using the HTTP GET method.

Syntax

public void get(String URL);

Remarks

This method fetches the document using the HTTP GET method. The document contents are delivered to the component and parsed. The XPath, XElement, and XText or the TransferredData property then can be used to traverse the data. The HTTP response headers are returned through the Header event. If LocalFile is not empty, the data (not the headers) are written there as well.

Interrupt Method (Shiprequest Class)

Interrupt the current method.

Syntax

public void interrupt();

Remarks

If there is no method in progress, Interrupt simply returns, doing nothing.

Reset Method (Shiprequest Class)

This method resets the class.

Syntax

public void reset();

Remarks

This method resets all HTTP headers to default values and resets the XML parser.

SubmitTo Method (Shiprequest Class)

Post current parameters to the URL specified by the 'URL' parameter.

Syntax

public void submitTo(String URL);

Remarks

A post request is sent to the URL with the specified parameters and values. The response is given via the TransferredData property.

Following are examples of using the class to create a request for different services. Note that these examples show how to implement functionality existing in other classs. To use any of the functionality demonstrated here, you may use the corresponding class instead.

FedEx Component.PostData = @"<?xml version="1.0" encoding="UTF-8" ?>" + @"<ProcessShipmentRequest xmlns="http://fedex.com/ws/ship/v9" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">" + "<WebAuthenticationDetail>" + "<UserCredential>" + "<Key>MyKey</Key>" + "<Password>MyPassword</Password>" + "</UserCredential>" + "</WebAuthenticationDetail>" + "<ClientDetail>" + "<AccountNumber>000000000</AccountNumber>" + "<Localization>" + "<LanguageCode>en</LanguageCode>" + "<LocaleCode>en</LocaleCode>" + "</Localization>" + "</ClientDetail>" + ... Component.SubmitTo("https://gatewaybeta.fedex.com:443/xml"); Component.XPath = "/ProcessShipmentReply/Notifications/Severity"; if(Component.XText == "SUCCESS") //The request was successful

USPS With Endicia Component.PostData = "postageRateRequestXML=<PostageRateRequest>" + "<RequesterID>test</RequesterID>" + "<CertifiedIntermediary>" + "<AccountID>123456</AccountID>" + "<PassPhrase>test</PassPhrase>" + "</CertifiedIntermediary>" + "<MailClass>ExpressMailInternational</MailClass>" + "<WeightOz>1</WeightOz>" + "<MailpieceShape>FlatRateEnvelope</MailpieceShape>" + "<AutomationRate>FALSE</AutomationRate>" + "<Machinable>TRUE</Machinable>" + "<Services>" + "<InsuredMail>OFF</InsuredMail>" + "</Services>" + "<FromPostalCode>10022</FromPostalCode>" + "<ToCountry>Algeria</ToCountry>" + "</PostageRateRequest>"; Component.ContentType = "application/x-www-form-urlencoded"; Component.SubmitTo("https://www.envmgr.com/LabelService/EwsLabelService.asmx/CalculatePostageRateXML"); Component.XPath = "/PostageRateResponse/Status"; if(Component.XText == "0") //The request was successful

USPS Component.AddParameter("XML",@"<CarrierPickupCancelRequest USERID="User" PASSWORD="Pass"><FirmName>ABC Corp.</FirmName>" + "<SuiteOrApt>Suite 777</SuiteOrApt>" + "<Address2>1390 Market Street</Address2>" + "<Urbanization></Urbanization>" + "<City>Houston</City>" + "<State>TX</State>" + "<ZIP5>77058</ZIP5>" + "<ZIP4>1234</ZIP4>" + "<ConfirmationNumber>WTC123456789</ConfirmationNumber>" + "</CarrierPickupCancelRequest>"); Component.AddParameter("API", "CarrierPickupCancel"); Component.ContentType = "application/x-www-form-urlencoded"; Component.SubmitTo("https://secure.shippingapis.com/ShippingAPITest.dll"); Component.XPath = "/CarrierPickupCancelResponse/Status"; Console.WriteLine(Component.XText);

Characters Event (Shiprequest Class)

Fired for plain text segments of the input stream.

Syntax

public class DefaultShiprequestEventListener implements ShiprequestEventListener {
  ...
  public void characters(ShiprequestCharactersEvent e) {}
  ...
}

public class ShiprequestCharactersEvent {
  public String text;
}

Remarks

The Characters event provides the plain text content of the XML document (i.e. the text inside the tags). The text is provided through the Text parameter.

The text includes white space as well as end of line characters, except for ignorable whitespace which is fired through the IgnorableWhitespace event.

Comment Event (Shiprequest Class)

Fired when a comment section is encountered.

Syntax

public class DefaultShiprequestEventListener implements ShiprequestEventListener {
  ...
  public void comment(ShiprequestCommentEvent e) {}
  ...
}

public class ShiprequestCommentEvent {
  public String text;
}

Remarks

The Comment event is fired whenever a comment section (<!-- ..text... -->) is found in the document.

The full text of the comment is provided by the Text parameter.

Connected Event (Shiprequest Class)

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

Syntax

public class DefaultShiprequestEventListener implements ShiprequestEventListener {
  ...
  public void connected(ShiprequestConnectedEvent e) {}
  ...
}

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

Remarks

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

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

Please refer to the Error Codes section for more information.

ConnectionStatus Event (Shiprequest Class)

This event is fired to indicate changes in the connection state.

Syntax

public class DefaultShiprequestEventListener implements ShiprequestEventListener {
  ...
  public void connectionStatus(ShiprequestConnectionStatusEvent e) {}
  ...
}

public class ShiprequestConnectionStatusEvent {
  public String connectionEvent;
  public int statusCode;
  public String description;
}

Remarks

The ConnectionStatus event is fired when the connection state changes: for example, completion of a firewall or proxy connection or completion of a security handshake.

The ConnectionEvent parameter indicates the type of connection event. Values may include the following:

Disconnected Event (Shiprequest Class)

This event is fired when a connection is closed.

Syntax

public class DefaultShiprequestEventListener implements ShiprequestEventListener {
  ...
  public void disconnected(ShiprequestDisconnectedEvent e) {}
  ...
}

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

Remarks

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

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

Please refer to the Error Codes section for more information.

EndElement Event (Shiprequest Class)

Fired when an end-element tag is encountered.

Syntax

public class DefaultShiprequestEventListener implements ShiprequestEventListener {
  ...
  public void endElement(ShiprequestEndElementEvent e) {}
  ...
}

public class ShiprequestEndElementEvent {
  public String namespace;
  public String element;
  public String QName;
  public boolean isEmpty;
}

Remarks

The EndElement event is fired when an end-element tag is found in the document.

The element name is provided by the Element parameter.

The IsEmpty parameter is true when the event corresponds with an empty element declaration.

EndPrefixMapping Event (Shiprequest Class)

Fired when leaving the scope of a namespace declaration.

Syntax

public class DefaultShiprequestEventListener implements ShiprequestEventListener {
  ...
  public void endPrefixMapping(ShiprequestEndPrefixMappingEvent e) {}
  ...
}

public class ShiprequestEndPrefixMappingEvent {
  public String prefix;
}

Remarks

The StartPrefixMapping event is fired when entering the scope of a namespace declaration.

Error Event (Shiprequest Class)

Fired when information is available about errors during data delivery.

Syntax

public class DefaultShiprequestEventListener implements ShiprequestEventListener {
  ...
  public void error(ShiprequestErrorEvent e) {}
  ...
}

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

Remarks

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

The ErrorCode parameter contains an error code, and the Description parameter contains a textual description of the error. For a list of valid error codes and their descriptions, please refer to the Error Codes section.

EvalEntity Event (Shiprequest Class)

Fired every time an entity needs to be evaluated.

Syntax

public class DefaultShiprequestEventListener implements ShiprequestEventListener {
  ...
  public void evalEntity(ShiprequestEvalEntityEvent e) {}
  ...
}

public class ShiprequestEvalEntityEvent {
  public String entity;
  public String value;
}

Remarks

The Value parameter contains a suggested value for the entity (normally the entity name itself). You may set Value to a value of your choice, which will be later passed into the text stream.

Header Event (Shiprequest Class)

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

Syntax

public class DefaultShiprequestEventListener implements ShiprequestEventListener {
  ...
  public void header(ShiprequestHeaderEvent e) {}
  ...
}

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

Remarks

The Field parameter contains the name of the HTTP header (which is the same as it is delivered). The Value parameter contains the header contents.

If the header line being retrieved is a continuation header line, then the Field parameter contains "" (empty string).

IgnorableWhitespace Event (Shiprequest Class)

Fired when a section of ignorable whitespace is encountered.

Syntax

public class DefaultShiprequestEventListener implements ShiprequestEventListener {
  ...
  public void ignorableWhitespace(ShiprequestIgnorableWhitespaceEvent e) {}
  ...
}

public class ShiprequestIgnorableWhitespaceEvent {
  public String text;
}

Remarks

The ignorable whitespace section is provided by the Text parameter.

Meta Event (Shiprequest Class)

Fired when a meta section is encountered.

Syntax

public class DefaultShiprequestEventListener implements ShiprequestEventListener {
  ...
  public void meta(ShiprequestMetaEvent e) {}
  ...
}

public class ShiprequestMetaEvent {
  public String text;
}

Remarks

The Meta event is fired whenever a meta information section (<! ..text... >) is found in the document.

The full text of the meta section is provided by the Text parameter.

PI Event (Shiprequest Class)

Fired when a processing instruction section is encountered.

Syntax

public class DefaultShiprequestEventListener implements ShiprequestEventListener {
  ...
  public void PI(ShiprequestPIEvent e) {}
  ...
}

public class ShiprequestPIEvent {
  public String text;
}

Remarks

The PI event is fired whenever a processing instruction section (<? ..text... ?>) is found in the document.

The full text of the processing instruction is provided by the Text parameter.

Redirect Event (Shiprequest Class)

This event is fired when a redirection is received from the server.

Syntax

public class DefaultShiprequestEventListener implements ShiprequestEventListener {
  ...
  public void redirect(ShiprequestRedirectEvent e) {}
  ...
}

public class ShiprequestRedirectEvent {
  public String location;
  public boolean accept;
}

Remarks

This event is fired in cases in which the client can decide whether or not to continue with the redirection process. The Accept parameter is always True by default, but if you do not want to follow the redirection, Accept may be set to False, in which case the class throws an exception. Location is the location to which the client is being redirected. Further control over redirection is provided in the FollowRedirects property.

SetCookie Event (Shiprequest Class)

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

Syntax

public class DefaultShiprequestEventListener implements ShiprequestEventListener {
  ...
  public void setCookie(ShiprequestSetCookieEvent e) {}
  ...
}

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

Remarks

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

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

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

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

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

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

SpecialSection Event (Shiprequest Class)

Fired when a special section is encountered.

Syntax

public class DefaultShiprequestEventListener implements ShiprequestEventListener {
  ...
  public void specialSection(ShiprequestSpecialSectionEvent e) {}
  ...
}

public class ShiprequestSpecialSectionEvent {
  public String sectionId;
  public String text;
}

Remarks

The SpecialSection event is fired whenever a special section (such as <![ CDATA [ ..text... ]]>) is found in the document.

The full text of the special section is provided by the Text parameter, while the SectionId parameter provides the section identifier (e.g. "CDATA").

SSLServerAuthentication Event (Shiprequest Class)

Fired after the server presents its certificate to the client.

Syntax

public class DefaultShiprequestEventListener implements ShiprequestEventListener {
  ...
  public void SSLServerAuthentication(ShiprequestSSLServerAuthenticationEvent e) {}
  ...
}

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

Remarks

During this event, the client can decide whether or not to continue with the connection process. The Accept parameter is a recommendation on whether to continue or close the connection. This is just a suggestion: application software must use its own logic to determine whether or not to continue.

When Accept is False, Status shows why the verification failed (otherwise, Status contains the string OK). If it is decided to continue, you can override and accept the certificate by setting the Accept parameter to True.

SSLStatus Event (Shiprequest Class)

Fired when secure connection progress messages are available.

Syntax

public class DefaultShiprequestEventListener implements ShiprequestEventListener {
  ...
  public void SSLStatus(ShiprequestSSLStatusEvent e) {}
  ...
}

public class ShiprequestSSLStatusEvent {
  public String message;
}

Remarks

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

StartElement Event (Shiprequest Class)

Fired when a begin-element tag is encountered in the document.

Syntax

public class DefaultShiprequestEventListener implements ShiprequestEventListener {
  ...
  public void startElement(ShiprequestStartElementEvent e) {}
  ...
}

public class ShiprequestStartElementEvent {
  public String namespace;
  public String element;
  public String QName;
  public boolean isEmpty;
}

Remarks

The StartElement event is fired when a begin-element tag is found in the document.

The element name is provided through the Element parameter. The attribute names and values (if any) are provided through the XAttributes collection.

The IsEmpty parameter is true when the event corresponds with an empty element declaration.

StartPrefixMapping Event (Shiprequest Class)

Fired when entering the scope of a namespace declaration.

Syntax

public class DefaultShiprequestEventListener implements ShiprequestEventListener {
  ...
  public void startPrefixMapping(ShiprequestStartPrefixMappingEvent e) {}
  ...
}

public class ShiprequestStartPrefixMappingEvent {
  public String prefix;
  public String URI;
}

Remarks

The EndPrefixMapping event is fired when leaving the scope of a namespace declaration.

Status Event (Shiprequest Class)

This event is fired when the HTTP status line is received from the server.

Syntax

public class DefaultShiprequestEventListener implements ShiprequestEventListener {
  ...
  public void status(ShiprequestStatusEvent e) {}
  ...
}

public class ShiprequestStatusEvent {
  public String HTTPVersion;
  public int statusCode;
  public String description;
}

Remarks

HTTPVersion is a string containing the HTTP version string as returned from the server (e.g., "1.1").

StatusCode contains the HTTP status code (e.g., 200), and Description the associated message returned by the server (e.g., "OK").

Certificate Type

This is the digital certificate being used.

Remarks

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

Fields

Constructors

public Certificate();

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

public Certificate( certificateFile);

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

public Certificate( certificateData);

Parses CertificateData as an X.509 public key.

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

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

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

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

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

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

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

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

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

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

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

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

Firewall Type

The firewall the class will connect through.

Remarks

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

Fields

Constructors

public Firewall();

Header Type

This is an HTTP header as it is received from the server.

Remarks

When a header is received through a Header event, it is parsed into a Header type. This type contains a Field, and its corresponding Value.

Fields

Constructors

public Header();

public Header( field,  value);

Proxy Type

The proxy the class will connect to.

Remarks

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

Fields

Constructors

public Proxy();

public Proxy( server,  port);

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

ShipParam Type

An object representing a single Ship Parameter.

Remarks

An object representing a single Ship Parameter.

Fields

Constructors

public ShipParam();

XMLAttribute Type

An XML attribute from the current XML element.

Remarks

This type describes an XML attribute from the current element. It includes fields to denote information about the attribute being defined.

Fields

Constructors

public XMLAttribute();

XMLElement Type

An element contained within the XML document.

Remarks

This type describes an XML element. The fields for this type describe the element Name, Prefix, and Namespace of the given element.

The elements are inserted into the array in the same order they are found in the document.

Fields

Constructors

public XMLElement();

XMLNamespace Type

An XML namespace from the current namespace stack.

Remarks

This type describes an XML namespace from the current stack. It includes fields to denote the Prefix and the URI of the namespace being defined.

The default namespace exists at index 0. The Prefix field at index 0 is "xmlns", and the Name field contains the default namespace.

Fields

Constructors

public XMLNamespace();

public XMLNamespace( name,  prefix);

Config Settings (Shiprequest Class)

ShipRequest Config Settings

HTTP Config Settings

TCPClient Config Settings

SSL Config Settings

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

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

Socket Config Settings

Base Config Settings

Trappable Errors (Shiprequest Class)

HTTP Errors

TCPClient Errors

SSL Errors

TCP/IP Errors