Web Publishing Overview


		Contents Index Topic Contents
	Previous Topic: Microsoft Web Publishing SDK Next Topic: Web Publishing Programmer's Reference

Web Publishing Overview

This section describes the Microsoft® Web Publishing Software Development Kit (SDK), including a description of the command-line options for the Web Publishing Wizard, Wpwiz.exe. Use this SDK to access Web Publishing functionality through your application.
For detailed descriptions of the interface methods and for code examples, see the Web Publishing Programmer's Reference. Note that the examples in the Web Publishing Programmer's Reference are not complete samples and often omit most error processing.
What's in the SDK

Web Publishing Sites

The Posting Information File

The Web Publishing API

The Web Publishing SPI

The File Upload Control

Web Publishing Wizard

What's in the SDK

The Web Publishing SDK includes the following:

The application programming interface (API). The API is designed for use by applications that want to include Web Publishing functionality. The API manages multiple publishing destinations (called sites) and calls the service provider interface (SPI) to do the work of transferring the files over the network. The API can support multiple service providers (implementations of the SPI), and provides mechanisms for selecting from among installed providers when setting up a new site.
The service provider interface (SPI). The SPI consists of a COM interface and several helper functions; the latter must be callable entry points in the DLL that services the COM interface.
The File Upload Control. This control packages the Web Publishing API's functionality in an ActiveX(tm) control, which can easily be included on HTML pages.

Web Publishing Sites

A site is a destination to which files can be published. Typically this is a computer connected to the Internet and running an HTTP server. The concept of a site in the Web Publishing API encompasses all information required in order to get files from the user's local computer onto the destination computer. The API handles management of the core set of information common to all varieties of sites, namely:
A friendly name.
The URL from which the files will be retrievable once they have been published (called the destination URL).
The service provider installed on the user's local computer that is used to transfer files to the destination computer.
A local base directory that corresponds to the destination URL. This is an optional feature of a site; if it is set it indicates how much of the path of a local file should be preserved when publishing to the destination computer. For example, if a site "MySite" has its local base directory set to C:\MYSITE and its destination URL set to http://www.mysite.com, then these example files would be posted as follows.

Local file Posted to

c:\mysite\file.html http://www.mysite.com/file.html

c:\mysite\images\gifs\me.gif http://www.mysite.com/images/gifs/me.gif

If a file is posted to a site with a local base directory specified, and the file is not under the local base directory tree, it is posted directly to the destination URL.

Local file Posted to

c:\site2\images\icons\redball.gif http://www.mysite.com/redball.gif

When the preceding information is gathered and stored for a given destination computer, a site is said to be "created." WpCreateSite collects these four pieces of information, either from the parameters passed to it or possibly, in the case of the service provider, by querying the service providers installed on the system to see whether they can publish to the specified destination URL. The information is then stored in a registry key under HKCU\Software\Microsoft\WebPost\Sites named with the friendly name of the site.
It is likely that most service providers will require more than this minimal set of information in order to get files onto the destination computer. For instance, the Microsoft® FTP service provider requires the name of the FTP server, the subfolder on the server, and possibly a user name and password in order to upload files. Service providers are encouraged to store this extra information on the same site key used by the API. Aside from simple centralization, the advantage of keeping information there is that any parameter values specified in the posting information file on the destination computer (see The Posting Information File) are automatically saved under this key when the site is first configured, making those parameters easily available to the service provider and possibly eliminating the need to obtain technical information from the user.
The Posting Information File

Because of variations among Internet servers, Microsoft requests that Internet service providers (ISPs) include a posting information file on their Internet servers. This file contains details about the posting protocol and policy. The Web Publishing API uses the information in the file to help with the detection of the Web Publishing protocol.
The version 1.5 release supports a new mechanism that meets with the approval of the W3C, in addition to the old postinfo.htm from version 1.1. The new mechanism allows the ISP to place a <META NAME="POSTINFO" CONTENT="URL"> tag in the default page on their server. This tag specifies a URL to the posting information file. The URL can be any path (even another machine) with any name but must be enclosed in quotation marks.
The file is simply a text file with sections and keys. The version statement must be the first statement in the file, followed by section(s) defining the transfer types. Multiple protocols can be supported on the server. Each new protocol section must start with the transfer type in brackets and include keys required by that provider. The transfer types must appear in priority order. When the Web Publishing client binds to a site it will attempt to use the first protocol listed; if that is not available, then it will try the next, and so on The transfer type can be specified as either a program ID or a GUID, enclosed in brackets. The convention for a program ID is Webpost.ProviderDll, where ProviderDll is the actual file name of the provider. A GUID must include the standard braces within the brackets. The GUIDs for the installed providers can be found in the registry under HKLM\System\CurrentControlSet\Services\Webpost\Providers.
All blank lines will be ignored and the fields are not case sensitive. Case will be preserved on all quoted string values. The keys can appear in any order within a section. There is one supported parameter and that is the $USERNAME variable. The Web Publishing client will substitute the local user name for that value when read from the server. The following is a sample posting information file that could appear on a server:
Version=1.5

[WebPost.FTPWPP]
ServerName="Server"
Subfolder="ftpupl/$USERNAME"
DefaultPage="default.html"

[WebPost.CRSWPP]
ServerName="Server"
For a complete list of parameters for different service providers, including CRS, FTP, and HTTP, see Appendix C, Parameters, in the Web Publishing Programmer's Reference.
The Web Publishing API

The Web Publishing application programming interface (API) makes it possible for authoring tools to post Web pages to an Internet site with just one call to the WpPost function. In a typical scenario, an authoring tool's File menu would include a "Post to Web" command that, when clicked, causes the tool to call the WpPost function. This function starts a wizard that asks the user for a friendly name for the Internet site and the Uniform Resource Locator (URL) for the site. Next, the function connects to the Internet server at the given URL, determines the protocol to use for posting the Web pages, and then posts the requested files. For subsequent posting to the same site, this function remembers the details of how to connect to the site, and posts the files with little user intervention. Thus, the Web Publishing API maintains a friendly site name, remembers all the details involved in posting to that site, and allows the applications to easily post Web pages to a site or to the URL associated with that site.
As an alternative to the wizard, an authoring tool can let the user choose the Web site before calling WpPost by displaying a list of sites (plus a "New Site" item) obtained by a call to the WpListSites function. The list of sites could be in a nested menu that appears when the user clicks the "Post to Web" command.
Interface Definition

The Web Publishing API consists of the following methods.

Method Description

WpBindToSite Obtains a pointer to a service provider object supporting either the IWPSite interface or the IWPProvider interface.

WpCreateSite Creates a new site entry in the registry.

WpCreateSiteEx Creates a new site entry in the registry, using a user name and password.

WpDeleteSite Deletes the information for a site from the registry.

WpDoesSiteExist Determines whether or not the specified site exists.

WpEnumProviders Enumerates the currently installed service providers.

WpGetErrorString Translates an error code.

WpListSites Lists the sites for which there is currently information in the registry.

WpPost Posts one or more files or directories to the specified site.

WpPostEx Posts one or more files or directories to the specified site, using a user name and password.

WpPostFile Posts one file or directory to the specified site.

The Web Publishing SPI

The Web Publishing service provider interface (SPI) describes the interface each service provider must support to allow the core web publishing services to post content. The SPI DLLs are OLE COM servers provide the following methods and helper functions. The Web Publishing API functions and the Web Publishing Wizard route requests to a provider based on a site name or URL, and use the SPI functions to post the files.
Interface Definition

The Web Publishing SPI consists of the following methods.

Helper function Description

WppBindToSite Retrieves the address of an interface if the provider DLL owns the site name or the URL.

WppDeleteSite Deletes a site name that has been configured.

Interface method Description

AddWizardPages Allows the provider DLLs to plug pages into the wizard invoked by the WpPost function.

DeleteFile Deletes the given file from the destination site.

FindClose Closes the specified search handle.

FindFirstFile Searches a directory for a file whose name matches the specified file name on the destination site.

FindNextFile Continues a file search from a previous call to the FindFirstFile function.

GetError Retrieves additional information about an error.

GetParam Retrieves a parameter value for this site.

GetSiteInfo Retrieves the site information for the current object.

NetworkConnect Connects to the Internet.

NetworkDisconnect Disconnects from the Internet.

PostFiles Posts files to the specified URL.

ServerLogin Logs the user on to the Internet server.

ServerLogout Logs the user out of the Internet server.

SetParam Sets the value of a parameter for a given site.

SetProgressUpdateProc Specifies the callback function.

Helper Functions

Each service provider DLL must export one helper function not available through the COM interface: WppBindToSite. This entry point will be called from WpBindToSite and WpPost in order to obtain a pointer to the service provider object. It will also be called from WpCreateSite.
If a service provider exports a WppDeleteSite entry point, it will be called from WpDeleteSite.
Note that one of the primary design changes in Web Publishing 1.5 is the shift of responsibility for maintaining site information from the individual service providers to the Web Publishing API. Providers should not maintain site-related state information independently of the Web Publishing API except when necessary. However, if separate record-keeping is necessary, a service provider is guaranteed under this model to be notified whenever sites are added, removed, or utilized for posting.
Self-Registration Responsibilities

Service provider DLLs are required to export a DllRegisterServer method that performs the following functions:
Registers its object's CLSID according to standard COM procedure.
Inserts a subkey for itself under HKLM\System\CurrentControlSet\Services\WebPost\Providers named with its CLSID and containing the following values.

Value Meaning

Provider A string that contains the name of the provider. This name is used in the wizard; it appears in the list box that contains the names of the providers.

Path A string that contains the path of the service provider DLL.

Priority A DWORD value that indicates the provider's priority. Zero is highest priority. Microsoft Web Publishing 1.5 service providers' priorities start at 0x00010000 and are 0x00000100 apart.

PostInfoRequired(new) If this DWORD value is non-zero, then this service provider requires a posting information file in order to obtain all the information necessary to post. If the posting information file cannot be retrieved, the attempt to create a site using this provider will fail.

(Optional.) Calls WpCreateSite to add the sites it supports to the registry.

The File Upload Control

The File Upload Control is an ActiveX control that uses the Web Publishing API. It can be included on an HTML page to allow posting to a server. Typical applications would be for a file upload area, or for an ISP to allow easy uploading to a personal Web pages site. The control also provides all configuration information normally provided by the wizard.
When the user sees the control on a page, he or she can simply drag files onto it to have them instantly sent, or double-click to display a dialog allowing selection of the local files to be transmitted. Right-clicking the icon will bring up a property sheet for the site, which will allow the user to edit the parameters.
Note If you intend to use this control from Visual Basic® applications on machines where Internet Explorer is not installed, you will need the following binary files: OLEPRO32.DLL, MSVCRT40.DLL, MSVCIRT.DLL.
Interface Definition

The File Upload Control interface has the following methods.

Method Description

AboutBox Displays information about the File Upload Control.

CreatePermBinding Creates a permanent site and binds to it.

CreateTempBinding Creates a temporary site and binds to it.

FoundPostInfo Checks whether a postinfo file was found on the target server.

SetBindingParam Sets binding parameters.

If the site should be retained on the client machine after the post is complete, the CreatePermBinding method should be used. The CreatePermBinding method will allow the author to specify a site name, URL, and, optionally, a provider. The call will return a value indicating whether the site was created, the site already existed, or the call failed. The author also has the ability to determine whether the path information from the client will be preserved when passing the file to the server. There are three flags supported for this method: strip, preserve, and prompt. The strip option can be used in a raw file upload situation where only the files are desired. The preserve option will assume the path of the first file/directory sent will become the base directory for this site. The prompt option will display a dialog allowing the user to set the local base directory. This dialog will be preloaded with the path of the first file/directory but the user will be allowed to change it as needed.
If the site definition will only be used for a single session, the CreateTempBinding method should be called. The only UI required of the ActiveX control is the file selection dialog, which is only displayed if the user double-clicks the icon, a transferring files dialog similar to the one used in the wizard, and a dialog indicating the completion status (success or error). There is also a dialog that can be brought up on a right-click that allows the user to set the local base directory.
Web Publishing Wizard

This section describes the command-line options for the Web Publishing Wizard, Wpwiz.exe.
Syntax
Wpwiz [–w "FriendlyName"] [–u "URL"] [–n "UserName"] [–p "password"] [–s "Service"] [–f [flags]] path [...]

Parameters

-w "FriendlyName" The friendly name to use for the site.

-u "URL" The destination URL to use for the site.

-n "UserName" The username to use for the site.

-p "Password" The password to use for the site.

-s "Service" The service provider to use for the site.

-f[flags] Force flags. By default the Wizard will skip any pages for which the required information has already been provided on the command line. These flags allow you to override this default behavior and force the Wizard to show whatever pages you specify.
There should not be a space between the "-f" and the list of page letter-identifiers. The letter-identifiers may appear in any order, and again should not be separated by spaces. The letter-identifiers are:

a All pages (shorthand for "iswnup")

i Introductory (welcome) page

s Source paths page (where user specifies file/folder to be published)

w Web server page (where user selects from list of existing friendly-named sites)

n Name the web server pages (where user provides friendly name for new site)

u URL page (where user provides URL for new site)

p Provider-specific pages (i.e., FTP prompts for Server name and Subfolder)

-b Disable auto-binding. This only applies when a new site is being created.

-i Don't recurse into folder being published; only publish its immediate children.

path [path [path [...]]] List of files to be published. Paths must be complete and absolute. Paths may be interspersed with flags.

Example
The following example invokes the Web Publishing wizard with the friendly name New Site, the URL http://myserver.com/myfolder, the user name anonymous, the password e-mail, with all flags and no auto-binding on the files Index.htm and Hello.htm. Note that the final path must be enclosed in double-quote marks since it contains a space.
C:\> wpwiz -w "New Site" -u "http://myserver.com/myfolder"
-n "anonymous" -p "e-mail" -s "FTP" -fa -b -i C:\Index.htm
"C:\HTML Files\Hello.htm" 
Top of Page
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.

Local file	Posted to
c:\mysite\file.html	http://www.mysite.com/file.html
c:\mysite\images\gifs\me.gif	http://www.mysite.com/images/gifs/me.gif

Local file	Posted to
c:\site2\images\icons\redball.gif	http://www.mysite.com/redball.gif

Method	Description
WpBindToSite	Obtains a pointer to a service provider object supporting either the IWPSite interface or the IWPProvider interface.
WpCreateSite	Creates a new site entry in the registry.
WpCreateSiteEx	Creates a new site entry in the registry, using a user name and password.
WpDeleteSite	Deletes the information for a site from the registry.
WpDoesSiteExist	Determines whether or not the specified site exists.
WpEnumProviders	Enumerates the currently installed service providers.
WpGetErrorString	Translates an error code.
WpListSites	Lists the sites for which there is currently information in the registry.
WpPost	Posts one or more files or directories to the specified site.
WpPostEx	Posts one or more files or directories to the specified site, using a user name and password.
WpPostFile	Posts one file or directory to the specified site.

Helper function	Description
WppBindToSite	Retrieves the address of an interface if the provider DLL owns the site name or the URL.
WppDeleteSite	Deletes a site name that has been configured.

Interface method	Description
AddWizardPages	Allows the provider DLLs to plug pages into the wizard invoked by the WpPost function.
DeleteFile	Deletes the given file from the destination site.
FindClose	Closes the specified search handle.
FindFirstFile	Searches a directory for a file whose name matches the specified file name on the destination site.
FindNextFile	Continues a file search from a previous call to the FindFirstFile function.
GetError	Retrieves additional information about an error.
GetParam	Retrieves a parameter value for this site.
GetSiteInfo	Retrieves the site information for the current object.
NetworkConnect	Connects to the Internet.
NetworkDisconnect	Disconnects from the Internet.
PostFiles	Posts files to the specified URL.
ServerLogin	Logs the user on to the Internet server.
ServerLogout	Logs the user out of the Internet server.
SetParam	Sets the value of a parameter for a given site.
SetProgressUpdateProc	Specifies the callback function.

Value	Meaning
Provider	A string that contains the name of the provider. This name is used in the wizard; it appears in the list box that contains the names of the providers.
Path	A string that contains the path of the service provider DLL.
Priority	A DWORD value that indicates the provider's priority. Zero is highest priority. Microsoft Web Publishing 1.5 service providers' priorities start at 0x00010000 and are 0x00000100 apart.
PostInfoRequired(new)	If this DWORD value is non-zero, then this service provider requires a posting information file in order to obtain all the information necessary to post. If the posting information file cannot be retrieved, the attempt to create a site using this provider will fail.

Method	Description
AboutBox	Displays information about the File Upload Control.
CreatePermBinding	Creates a permanent site and binds to it.
CreateTempBinding	Creates a temporary site and binds to it.
FoundPostInfo	Checks whether a postinfo file was found on the target server.
SetBindingParam	Sets binding parameters.