United States Postal Service Web Tool Kit User s Guide A Technical Guide to HTTP Connection DLL (Revised 2/22/00)
To HTTP Connection DLL Customers This release of the Web Tool Kit User s Guide for HTTP Connection DLL provides documentation and sample code created specifically for the USPS API implementation. It provides e-tailers with a thread-safe sockets interface to submit XML reuests and receive XML responses from the API server in a Windows NT environment. USPS Customer Commitment The United States Postal Service fully understands the importance of your need to provide information and service anytime day or night to your Internet and e-commerce customers. For that reason, the USPS is committed to providing 7 x 24 service from our API servers, 365 days a year. Technical Support. If you reuire technical support, contact the USPS Internet Customer Care Center (ICCC). This office is manned from 7:00AM to 11:00PM EST. E-mail: icustomercare@usps.com Telephone: 1-800-344-7779 (7:00AM to 11:00PM EST) Thank you for helping the U.S. Postal Service provide new Internet services to our shipping customers. Internet Shipping Solutions Team U.S. Postal Service 475 L Enfant Plaza, SW Washington, DC 20260-2464 Copyright 2000 by the United States Postal Service. All rights reserved. USPS Web Tool Kit User s Guide for HTTP Connection DLL i
Important Notice Regarding User ID and Password The user ID and password that you have received is only for the use of you or your company in accordance with the Terms and Conditions of Use to which you agreed during the registration process. This user ID and password is not to be shared with others outside your organization, nor is it to be packaged, distributed, or sold to any other person or entity. Please refer to the Terms and Conditions of Use Agreement for additional restrictions on the use of your user ID and password, as well as this document and the APIs contained herein. Warning: If the U.S. Postal Service discovers use of the same user ID and password from more than one web site, all users will be subject to immediate loss of access to the USPS server and termination of the licenses granted under the Terms and Conditions of Use. Attention Software Developers and Distributors The HTP Connection DLL documentation and sample code contained herein may not be reused and/or distributed to any other entity. Refer to your Licensing Agreement for the terms and conditions of use of this software. For more information regarding the USPS Web Tool Kit password and user ID policy, or for uestions regarding the distribution of documentation, send e-mail to icustomercare@usps.com. Trademarks Microsoft, Visual Basic, Windows NT, 95, 98, and 2000 are registered trademarks of Microsoft Corporation. USPS Web Tool Kit User s Guide for HTTP Connection DLL ii
Table of Contents Introduction...4 Getting Started...4 Sample Active Server Page (ASP) Application...5 Prereuisites... 5 Running the Application... 5 Sample ASP Visual Basic (VB) Script Code... 5 httpgetresponse Routine...7 Parameters... 7 Return Values... 8 Remarks... 8 USPS Web Tool Kit User s Guide for HTTP Connection DLL iii
Introduction To make the Internet connection from an NT system, you have the option of using software from the USPS called the HTTP Connection DLL. This software, created specifically for the USPS API implementation, provides e-tailers with a thread-safe sockets interface to submit XML reuests and receive XML responses from the USPS Shipping API server. This document describes the USPS HTTP Connection DLL interface, which implements the http calls using a routine called httpgetresponse. This document provides a sample application using Active Server Page, but you can implement the function in a variety of other ways, including a Visual Basic program, a C program, your own COM wrapper, or others. This software is intended only for Microsoft Windows NT environments. It is not intended for Microsoft Windows 95, 98, or 2000 environments. A ZIP file has been provided that contains the following: httpclient.dll (HTTP client dynamic link library) a sample web implementation of the Tracking API that includes the following files: tracking.htm track_xml.asp glob_logo.gif ship_hd8.gif ship_submit_butt.gif httpcom.dll (This file is a Visual Basic COM wrapper dll. A Runtime library for VB v.6 is reuired for this dll.) The httpclient.dll contains a single routine, httpgetresponse, which provides a simple one-call interface to send an http GET or POST reuest and receive the response. See the httpgetresponse Routine section on page 7. Getting Started To install these components: 1. create a new folder on your disk to store the contents 2. unzip the contents into the newly created folder 3. put httpclient.dll and httpcom.dll in the system folder (c:\winnt\system32\) 4. register httpcom.dll with the following command: regsvr32 c:\winnt\system32\httpcom.dll USPS Web Tool Kit User s Guide for HTTP Connection DLL 4
Sample Active Server Page (ASP) Application The sample application presented in this section implements only the Tracking API using an ASP. When implementing other APIs with this sample code, substitute appropriate code (shown in bold in the sample below). Prereuisites Development is to take place in a Microsoft Windows NT 4.0 environment. IIS is already installed. Your web site is up and running. Microsoft s XML parser is installed. You have already read the appropriate USPS Web Tool Kit User s Guide for the API(s) you are implementing. You already know how to build XML reuests and how to process XML responses. You will implement calls to GetResponse from an ASP page. Running the Application In order to run the sample application: 1. Copy the following files to your web site home directory: tracking.htm track_xml.asp glob_logo.gif ship_hd8.gif ship_submit_butt.gif 2. Modify track_xml.asp and enter your Shipping API-supplied username and password, as well as the appropriate proxy server and port information for your web site. 3. From a browser, enter webservername/tracking.htm. 4. You should see a Track or Confirm Delivery page displayed. Enter a tracking number and click on the Submit button. You should see tracking summary and detail information displayed for that package ID. Sample ASP Visual Basic (VB) Script Code This sample code shows how to use the USPS HTTP Connection DLL to make the Internet connection. The sample code calls a COM wrapper function GetResponse (supplied in httpcom.dll). GetResponse calls the http client function httpgetresponse (supplied in httpclient.dll). USPS Web Tool Kit User s Guide for HTTP Connection DLL 5
Refer to the appropriate USPS Web Tool Kit User s Guide for the API(s) you are implementing for instructions on how to construct XML reuests and unpack XML responses. The following sample code is a replacement for the sample code described in the sections titled Make the Internet Connection and Send the XML Reuest for each API in the user s guide. To implement additional APIs, add the following lines to your ASP VB script to provide the WinSock connection to the Internet. You can include the URL_Encode function from the demo source code. set httpconn = server.createobject("httpcom.chttpcom") srvr = "XXXXX" You must modify the Server name port = 80 path = "/XXXXX" You must modify the Path name uery = "" msg = "API=Track&XML=" & URL_Encode(xmldoc.xml) You must modify the API name to use other APIs contenttype = "application/x-www-form-urlencoded" proxyserver = "your proxy server here" You must modify proxy server or leave blank if no proxy proxyport = 8080 Modify the proxy port, if necessary. Leave blank if no proxy. dim resp resp="" on error resume next respcode = httpconn.getresponse(srvr, port, path, uery, msg, contenttype, proxyserver, proxyport, resp) if err.number <> 0 then Response.Write("Error:<br><table cols=2 border=1><tr><td>err.number</td><td>" & _ err.number & "</td></tr><td>err.source</td><td>" & _ err.source & "</td></tr><td>err.description</td><td>" & _ err.description & "</td></tr></table>") Response.Write("</body></html>") Response.Write("HTML Error:<br>" & resp) response.end set xmldoc= nothing set httpconn = nothing end if set xmldoc= nothing set httpconn = nothing USPS Web Tool Kit User s Guide for HTTP Connection DLL 6
httpgetresponse Routine The httpgetresponse routine provides a simple one-call interface to send an http GET or POST reuest and receive the response. It implements a conditionally compliant http V1.1 client. Because all data is represented in memory, this routine is only suitable for relatively small transfers. int APIENTRY httpgetresponse ( LPCSTR server, // server portion of URL int port, // http port on server; default: 80 LPCSTR path, // path portion of URL; default: / LPCSTR uery, // uery portion of URL; optional LPCSTR msg, // body for http reuest; optional LPCSTR contenttype, // Content-Type of msg; optional LPCSTR proxyserver, // name of http proxy server; optional int proxyport, // port to use on proxy server; default: 80 BSTR *pcontent // receives body of response ) Parameters server: The host name of the http server where the desired resource is located. port: (optional) TCP port to use for http connection to the server. If 0, the default http port 80 is used. path: (optional) Path specification for the resource on the server. If null or empty, the default path string / is used. uery: (optional) Query portion of the URL (part after the? ). If supplied, the uery string will be escaped (encoded) by httpgetresponse according to RFC 2396 (Uniform Resource Identifiers). Therefore, the string as passed to httpgetresponse must be unescaped. msg: (optional) The body of the http message, if any. If supplied, the POST method is used for the http reuest. If null or empty, the GET method is used. The caller is responsible for any encoding or escaping reuired. The caller should specify an appropriate contenttype if needed to insure the body can be understood and decoded by the server. contenttype: (optional) http Content-Type of the body. Used only if msg is supplied. If msg is supplied but contenttype is not, then a default Content-Type of text/plain is used. proxyserver: (optional) Host name of the http proxy server to use, if any. If proxyserver is not supplied, the http connection is made directly to server. proxyport: (optional) TCP port to use for http connection to the proxyserver. If 0, the default http port 80 is used. pcontent: Pointer to a BSTR to receive the response to the reuest. The BSTR is allocated by httpgetresponse using the system routine SysAllocStringByteLen(). The caller must free the space later by calling SysFreeString(). This should be done even if httpgetresponse returns an error--the pcontent string may still contain useful information from an http error response. USPS Web Tool Kit User s Guide for HTTP Connection DLL 7
Return Values 0: Success. pcontent contains the body of the response, if any. Nnn. An http error response was received. The return value is the three-digit (decimal) http Status Code. 901: Local Error. The http response could not be parsed. 902: Local Error. The http response contained an invalid length indication. (Content-Length header differed from actual length of response body.) nnnnn. A WinSock error occurred. The return value is the five-digit (decimal) WinSock error code. Remarks httpgetresponse does not handle automatic redirection (3xx http Status Codes). Nor does it handle Successful codes (2xx) other than 200 OK and 203 Non-Authoritative Information. In these cases, an error is returned. However, the pcontent string still contains the body of the response message, if any. This information may indicate how to find the desired information in another location. USPS Web Tool Kit User s Guide for HTTP Connection DLL 8