 | ||||
| ||||
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.
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® control, which can easily be included on HTML pages. |
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:
| Local file | Posted to |
| c:\MySample\file.html | http://sample.microsoft.com/file.html |
| c:\MySample\images\gifs\me.gif | http://sample.microsoft.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://sample.microsoft.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.
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 ISPs 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 computer) 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 a 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, 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 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.
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 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 and 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.
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 off from the Internet server. |
| SetParam | Sets the value of a parameter for a given site. |
| SetProgressUpdateProc | Specifies the callback function. |
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.
Service provider DLLs are required to export a DllRegisterServer method that performs the following functions:
| 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 nonzero, 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. |
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 users see the control on a page, they can simply drag files onto it to have them instantly sent, or double-click to display a dialog box 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 Microsoft® Visual Basic® applications on machines where Microsoft® Internet Explorer is not installed, you will need the following binary files: Olepro32.dll, Msvcrt40.dll, Msvcirt.dll.
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 box allowing the user to set the local base directory. This dialog box 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 box, which is only displayed if the user double-clicks the icon, a transferring files dialog box similar to the one used in the wizard, and a dialog box indicating the completion status (success or error). There is also a dialog box that can be brought up on a right-click that allows the user to set the local base directory.
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 | Description | ||||||||||||||
| -w "FriendlyName" | The friendly name to use for the site. | ||||||||||||||
| -u "URL" | The destination URL to use for the site. | ||||||||||||||
| -n "UserName" | The user name 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:
| ||||||||||||||
| -b | Disable autobinding. 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://sample.microsoft.com/myfolder, the user name anonymous, the password e-mail, with all flags and no autobinding on the files Index.htm and Hello.htm. Note that the final path must be enclosed in quotation marks because it contains a space.
C:\> wpwiz -w "New Site" -u "http://sample.microsoft.com/myfolder" -n "anonymous" -p "e-mail" -s "FTP" -fa -b -i C:\Index.htm "C:\HTML Files\Hello.htm"
Did you find this topic useful? Suggestions for other topics? Write us!
© 1999 Microsoft Corporation. All rights reserved. Terms of use.
Back to top