Overview

webftCOM is a free COM component that provides easy-to-use, standards-based file transfer methods. Use it to add online file transfer capabilities to your Windows Scripting Host programs, HTML Applications (HTAs), or anywhere else you use COM objects.

webftCOM is a mature, robust component that has been in use in commercial systems since 2002. It has recently been updated for compatibility with Microsoft Visual Studio 2005.

Secure File Transfers

FTP has been used for decades, and its main shortcoming is well-known: It is fundamentally insecure. There have been various attempts to address this, but none has gained industry-wide support. On the other hand, there is a standard file transfer protocol that is cross-platform, universally supported, and highly secure: HTTPS. Many people are unaware that HTTPS can be used for bidirectional file transfer, but file upload (and deletion) is part of the HTTP 1.1 standard. Every current web server supports this, usually by enabling write access to a web folder. With HTTPS handling the encryption, and username/password protection supplied by web authentication (Basic or Windows), you get a complete end-to-end security solution for your file transfers, without using a proprietary security product.

webftCOM leverages the HTTPS support built into the WinINET API, so you can count on the same security that protects millions of web browser transactions every day. At one customer site, webftCOM has been used for several years to securely transmit millions of batch transactions to and from various financial institutions.

Since some applications require FTP support for compatibility with existing systems, webftCOM also provides FTP file transfer methods. Because of the limitations of FTP, these methods do not provide encryption of usernames, passwords, or transmitted data. If you do decide to use FTP, be sure to use a third-party encryption solution for the files being transmitted.

(Please note: The upload and delete features included in the HTTP 1.1 standard should not be confused with similar capabilities provided by the Microsoft technology known as FrontPage Server Extensions. webftCOM does not support file transfers via FrontPage Server Extensions.)

License

webftCOM is distributed under the GNU Lesser General Public License (LGPL), so you can use it freely in both commercial and open-source projects.

Download

Version 1.1, Updated 9/18/2007:

webftCOM.zip (126K) Runtime Binary
webftCOM-Source.zip (38K) Source Code and Samples

Download webftCOM.zip and copy its contents to a folder on your system. Go to a Windows command prompt, change to the folder where you copied the files, and run the Windows command to register COM components: regsvr32 webftCOM.dll

You should see a message box saying "DllRegisterServer in webftCOM.dll succeeded." Now you're ready to use webftCOM in your programs.

Revision History

Version 1.1, September 2007:

  • First release for public distribution; incorporated GNU LGPL license.
  • Changed name to webftCOM to avoid confusion with RadView's WebFT functional testing product.
  • Updated for compatibility with Visual Studio 2005.
  • Removed unused return value from FTP methods.

Version 1.0.2, September 2003:

  • Added FTP methods (thanks to Farrell McGoohan for his assistance).

Version 1.0, July 2002:

  • Inital release.

API Documentation

webftCOM.WebFileTransfer Object

The WebFileTransfer object has the CLSID {20C9D4FD-C368-476B-8A37-87169C525417} and the ProgID webftCOM.WebFileTransfer. Depending on your host programming language, you will use one of these IDs to instantiate the class.

For example, from JavaScript running in the Windows Scripting Host, you can instantiate the WebFileTransfer object in either of the following two ways:

var oWFT = new ActiveXObject("webftCOM.WebFileTransfer");
var oWFT = WScript.CreateObject("webftCOM.WebFileTransfer");

Note: For backward compatibility with clients of Version 1.0, the old ProgID WebFT.WebFileTransfer is still supported, though deprecated for new applications.

Methods

DownloadFile

Downloads a file from a web server to the local file system.

nHTTPStatus = oWFT.DownloadFile(sUrl, sLocalPathname, [sUserName, [sPassword]])

Arguments

oWFT
webftCOM.WebFileTransfer object.
sUrl
The URL of the file to download from the web server.
sLocalPathname
The full path where the file should be stored in the local file system.
sUserName
Optional. The user name to authenticate, for web sites that use Basic or Windows authentication.
sPassword
Optional. The password to authenticate, for web sites that use Basic or Windows authentication.

Return Value

nHTTPStatus
The HTTP status code indicating the result of the download. See HttpStatusCodes.

Remarks

If the specified local file already exists, it will be overwritten.

This method fires the OnProgress event.

Example

var oWFT = new ActiveXObject("webftCOM.WebFileTransfer");
WScript.Echo(oWFT.DownloadFile("http://localhost/webftCOM.txt", "C:\\webftCOM.txt"));

UploadFile

Uploads a file from the local file system to a web server.

nHTTPStatus = oWFT.UploadFile(sUrl, sLocalPathname, [sUserName, [sPassword]])

Arguments

oWFT
webftCOM.WebFileTransfer object.
sUrl
The URL where the file should be stored on the web server.
sLocalPathname
The full path of the local file to upload.
sUserName
Optional. The user name to authenticate, for web sites that use Basic or Windows authentication.
sPassword
Optional. The password to authenticate, for web sites that use Basic or Windows authentication.

Return Value

nHTTPStatus
The HTTP status code indicating the result of the upload. See HttpStatusCodes.

Remarks

The web server must be configured to allow uploads via the HTTP PUT method.

If the specified file already exists on the server, it will be overwritten.

This method fires the OnProgress event.

Example

var oWFT = new ActiveXObject("webftCOM.WebFileTransfer");
WScript.Echo(oWFT.UploadFile("http://localhost/webftCOM.txt", "C:\\webftCOM.txt"));

Delete

Deletes a file or folder from a web server.

nHTTPStatus = oWFT.Delete(sUrl, [sUserName, [sPassword]])

Arguments

oWFT
webftCOM.WebFileTransfer object.
sUrl
The URL of the file or folder to be deleted from the web server.
sUserName
Optional. The user name to authenticate, for web sites that use Basic or Windows authentication.
sPassword
Optional. The password to authenticate, for web sites that use Basic or Windows authentication.

Return Value

nHTTPStatus
The HTTP status code indicating the result of the deletion. See HttpStatusCodes.

Remarks

The web server must be configured to allow deletions via the HTTP DELETE method.

Example

var oWFT = new ActiveXObject("webftCOM.WebFileTransfer");
WScript.Echo(oWFT.Delete("http://localhost/webftCOM.txt"));

CreateFolder

Creates a new folder on a web server.

nHTTPStatus = oWFT.CreateFolder(sUrl, [sUserName, [sPassword]])

Arguments

oWFT
webftCOM.WebFileTransfer object.
sUrl
The URL of the folder to be created on the web server.
sUserName
Optional. The user name to authenticate, for web sites that use Basic or Windows authentication.
sPassword
Optional. The password to authenticate, for web sites that use Basic or Windows authentication.

Return Value

nHTTPStatus
The HTTP status code indicating the result of the creation. See HttpStatusCodes.

Remarks

The web server must be configured to allow folder creation via the HTTP-DAV MKCOL method. This is part of the HTTP-DAV extension to the HTTP 1.1 protocol, and is supported by many web servers, including Microsoft IIS.

Example

var oWFT = new ActiveXObject("webftCOM.WebFileTransfer");
WScript.Echo(oWFT.CreateFolder("http://localhost/NewFolder"));

FTPGetFile

Downloads a file from an FTP server to the local file system.

oWFT.FTPGetFile(sUrl, sLocalPathname, [sUserName, [sPassword]])

Arguments

oWFT
webftCOM.WebFileTransfer object.
sUrl
The URL of the file to download from the FTP server.
sLocalPathname
The full path where the file should be stored in the local file system.
sUserName
Optional. The user name to authenticate. If not specified, anonymous authentication will be used.
sPassword
Optional. The password to authenticate. If not specified, anonymous authentication will be used.

Remarks

If the specified local file already exists, it will be overwritten.

This method fires the OnProgress event, but does not fire the wftTransferring status.

Example

var oWFT = new ActiveXObject("webftCOM.WebFileTransfer");
oWFT.FTPGetFile("ftp://localhost/webftCOM.txt", "C:\\webftCOM.txt"));

FTPPutFile

Uploads a file from the local file system to an FTP server.

oWFT.FTPPutFile(sUrl, sLocalPathname, [sUserName, [sPassword]])

Arguments

oWFT
webftCOM.WebFileTransfer object.
sUrl
The URL where the file should be stored on the FTP server.
sLocalPathname
The full path of the local file to upload.
sUserName
Optional. The user name to authenticate. If not specified, anonymous authentication will be used.
sPassword
Optional. The password to authenticate. If not specified, anonymous authentication will be used.

Remarks

If the specified file already exists on the server, it will be overwritten.

This method fires the OnProgress event, but does not fire the wftTransferring status.

Example

var oWFT = new ActiveXObject("webftCOM.WebFileTransfer");
oWFT.FTPPutFile("ftp://localhost/webftCOM.txt", "C:\\webftCOM.txt"));

FTPDeleteFile

Deletes a file from an FTP server.

oWFT.FTPDeleteFile(sUrl, [sUserName, [sPassword]])

Arguments

oWFT
webftCOM.WebFileTransfer object.
sUrl
The URL of the file to be deleted from the FTP server.
sUserName
Optional. The user name to authenticate. If not specified, anonymous authentication will be used.
sPassword
Optional. The password to authenticate. If not specified, anonymous authentication will be used.

Example

var oWFT = new ActiveXObject("webftCOM.WebFileTransfer");
oWFT.FTPDeleteFile("ftp://localhost/webftCOM.txt");

StorePassword

Given a server, a user name, and a password, StorePassword stores all three pieces of information in an encrypted section of the Windows registry.

oWFT.StorePassword(sUrl, sUserName, sPassword)

Arguments

oWFT
webftCOM.WebFileTransfer object.
sUrl
URL for which the password should be stored. Only the server (hostname) portion of the URL is used. Not case-sensitive.
sUserName
The user name for which the password should be stored. Not case-sensitive.
sPassword
The password to store. Case-sensitive.

Remarks

When writing scripts that need to access password-protected web or FTP sites, especially scripts that can't prompt for input, using StorePassword and RetrievePassword is preferable to hard-coding passwords or implementing your own encryption.

The protection level for passwords stored via this method is equivalent to the protection for passwords stored by Internet Explorer. According to Microsoft's documentation, "the data stored by the this method is not absolutely protected. However, the data is encrypted before being stored, and the key has a DACL that allows only the creator and administrators to read the data." Please see the documentation on LsaStorePrivateData for more information.

The stored information is private to the Windows account calling this method. If multiple accounts share the same machine, each will have its own set of stored passwords.

Each combination of server and user name can have a single stored password.

Example

var oWFT = new ActiveXObject("webftCOM.WebFileTransfer");
oWFT.StorePassword("http://www.google.com", "JoeUser", "SecretPassword");

RetrievePassword

Retrieves a password previously stored by StorePassword.

sPassword = oWFT.RetrievePassword(sUrl, sUserName)

Arguments

oWFT
webftCOM.WebFileTransfer object.
sUrl
URL for which the password was stored. Only the server (hostname) portion of the URL is used. Not case-sensitive.
sUserName
The user name for which the password was stored. Not case-sensitive.

Return Value

sPassword
The password retrieved from the registry.

Remarks

An exception is thrown if no password has been stored for the specified server and user name.

See StorePassword for more information on how passwords are stored and retrieved.

Example

var oWFT = new ActiveXObject("webftCOM.WebFileTransfer");
WScript.Echo(oWFT.RetrievePassword("http://www.google.com", "JoeUser"));

Events

OnProgress

Fired by the file transfer methods to indicate the progress of the operation.

webftCOM_OnProgress(nProgressCode, nTotalBytes, nBytesSoFar)

Arguments

webftCOM
Prefix designated by WScript.ConnectObject (or equivalent in other hosts).
nProgressCode
Code indicating the stage of the operation. See ProgressCodes.
nTotalBytes
The total size in bytes of the file being transferred. This will be zero if the size is not available.
nBytesSoFar
The number of bytes transferred at this point. This will be zero except when nProgressCode is wftTransferring.

Remarks

nTotalBytes will be zero for all FTP transfers and for any web download where the server does not supply the Content-Length HTTP header.

Example

var oWFT = new ActiveXObject("webftCOM.WebFileTransfer");
WScript.ConnectObject(oWFT, "webftCOM_");
oWFT.DownloadFile("http://localhost/webftCOM.txt", "C:\\webftCOM.txt");

function webftCOM_OnProgress(
   nProgressCode,
   nTotalBytes,
   nBytesSoFar)
{
   WScript.Echo("nProgressCode = " + nProgressCode + " nTotalBytes = " + nTotalBytes
      + " nBytesSoFar = " + nBytesSoFar);
   if(nTotalBytes > 0)
      WScript.Echo("% complete: " + Math.round(nBytesSoFar / nTotalBytes * 100.0));
}

Enumerations

HttpStatusCodes

These codes are returned by the web-based methods to indicate the result of the operation.

httpStatusContinue = 100 // OK to continue with request httpStatusSwitchProtocols = 101 // server has switched protocols in upgrade header httpStatusOk = 200 // request completed httpStatusCreated = 201 // object created, reason = new URI httpStatusAccepted = 202 // async completion (TBS) httpStatusPartial = 203 // partial completion httpStatusNoContent = 204 // no info to return httpStatusResetContent = 205 // request completed, but clear form httpStatusPartialContent = 206 // partial GET fulfilled httpStatusAmbiguous = 300 // server couldn't decide what to return httpStatusMoved = 301 // object permanently moved httpStatusRedirect = 302 // object temporarily moved httpStatusRedirectMethod = 303 // redirection w/ new access method httpStatusNotModified = 304 // if-modified-since was not modified httpStatusUseProxy = 305 // redirection to proxy httpStatusRedirectKeepVerb = 307 // HTTP/1.1: keep same verb httpStatusBadRequest = 400 // invalid syntax httpStatusDenied = 401 // access denied httpStatusPaymentReq = 402 // payment required httpStatusForbidden = 403 // request forbidden httpStatusNotFound = 404 // object not found httpStatusBadMethod = 405 // method is not allowed httpStatusNoneAcceptable = 406 // no response acceptable to client found httpStatusProxyAuthReq = 407 // proxy authentication required httpStatusRequestTimeout = 408 // server timed out waiting for request httpStatusConflict = 409 // user should resubmit with more info httpStatusGone = 410 // the resource is no longer available httpStatusLengthRequired = 411 // the server refused to accept request w/o a length httpStatusPrecondFailed = 412 // precondition given in request failed httpStatusRequestTooLarge = 413 // request entity was too large httpStatusUriTooLong = 414 // request URI too long httpStatusUnsupportedMedia = 415 // unsupported media type httpStatusServerError = 500 // internal server error httpStatusNotSupported = 501 // required not supported httpStatusBadGateway = 502 // error response received from gateway httpStatusServiceUnavail = 503 // temporarily overloaded httpStatusGatewayTimeout = 504 // timed out waiting for gateway httpStatusVersionNotSup = 505 // HTTP version not supported

ProgressCodes

These codes are passed to the OnProgress event to indicate the stage of the operation in progress.

wftConnecting = 1 wftSendingRequest = 2 wftTransferring = 3 wftComplete = 4