Microsoft Web Publishing SDK Version 1.5 Programmer's Reference

Microsoft Web Publishing SDK Version 1.5 Programmer's Reference


This document contains detailed descriptions of the interface methods and code examples for the Microsoft® Web Publishing Software Development Kit (SDK). The examples in the Programmer's Reference are not complete samples and often omit most error processing.

Note The Web Publishing interfaces (including the File Upload Control interface) cannot be used from a UI-less environment. For instance, if a pop-up dialog is created during a server-side run, the client never sees the dialog on its end and the process cannot complete.

arrowy.gifThe Web Publishing API

arrowy.gifThe Web Publishing SPI

arrowy.gifThe File Upload Control Interface

arrowy.gifAppendix A, Structures

arrowy.gifAppendix B, Error Codes

arrowy.gifAppendix C, Parameters

The Web Publishing API

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.
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.
WpPostFile Posts one file or directory to the specified site.

WpBindToSite

DWORD WpBindToSite(
    [in]    HWND      hWnd
    [in, string]      LPTSTR   szSiteName
    [in, string]      LPTSTR   szSiteURL
    [in]    DWORD     dwFlags
    [in]    DWORD     dwReserved
    [out]   LPVOID *  ppUnk
    );

Attempts to determine the provider responsible for servicing the specified site based upon szSiteName and/or szSiteURL.

hWnd
Optional. Window handle to receive focus upon completion of this API call. May be NULL.
szSiteName
Posting site name. May be NULL if valid szSiteURL is given.
szSiteURL
Posting site URL. May be NULL if valid szSiteName is given.
dwFlags
Action flags. Possible values are shown in the following table.
Value Meaning
WPF_NO_DIRECT_LOOKUP Do not attempt to look up the site based on the posting site name. This has the same effect as a NULL or empty szSiteName.
WPF_NO_URL_LOOKUP Do not attempt to look up the site based on the posting site URL. This has the same effect as a NULL or empty szSiteURL.
dwReserved
Reserved. Must be set to zero.
ppUnk
Address of an IUnknown pointer, which can be queried upon return to determine whether the service provider supports the old IWPSite or the new IWPProvider interface. May not be NULL.

The site lookup procedure works as follows:

  1. If szSiteName and szSiteURL are both either NULL or empty, return E_INVALIDARG.
  2. Registry lookup. If szSiteName is non-NULL/empty and WPF_NO_DIRECT_LOOKUP is not set:
    1. Get a site subkey.
    2. Check szSiteName for a match with the subkey name. If there is a match, get the site URL and call WppBindToSite into the indicated provider with the WPF_FORCE_BIND flag and return the interface pointer so obtained.
    3. If all subkeys have been enumerated, proceed to URL Lookup. Otherwise return to step 2-1.
  3. URL lookup. If szSiteURL is non-NULL/empty and WPF_NO_URL_LOOKUP is not set:
    1. Get a site subkey.
    2. Check whether the szSiteURL value of the subkey is a prefix of szSiteURL. If so, get the site name and call WppBindToSite into the indicated provider with the WPF_FORCE_BIND flag and return the interface pointer so obtained.
    3. If all subkeys have been enumerated, quit with error result. Otherwise return to step 3-1.

Examples
C/C++

{
    HRESULT hResult = NOERROR;
    void *pUnknown;

    hResult = WpBindToSite(NULL, "site1", NULL, 0, 0, &pUnknown);
}

WpCreateSite

DWORD WpCreateSite(
    [in, string]   LPTSTR   szSiteName
    [in, string]   LPTSTR   szSiteLocalBaseDir
    [in, string]   LPTSTR   szSiteURL
    [in, string]   LPTSTR   szProviderCLSID
    [in]           DWORD    dwFlags
    );

Creates a new site in the registry.

szSiteName
Posting site name.
szSiteLocalBaseDir
Optional. Local base directory for the site. If NULL, then the local base directory feature is not used for the site.
szSiteURL
Posting site URL.
szProviderCLSID
Optional. CLSID as string, of the provider that will handle this site. If NULL, then this method will search for a posting information (postinfo) file or attempt an auto-bind to an appropriate provider. For more information, see the "Remarks" section below.
dwFlags
Action flags. Possible values are shown in the following table.
Value Meaning
WPF_USE_PROVIDER_PASSED Use the provider specified in szProviderCLSID even if there is a postinfo file and it does not list this provider. Typically this is used after WpCreateSite has been called once and has returned WEBPOST_ERROR_PROV_NOT_IN_POSTINFO.

Site creation proceeds as follows:

  1. Create a registry key for the site, and values on that key for the local base directory, flags, and destination URL.
  2. Attempt to retrieve a postinfo file from the root directory of the destination URL.
  3. If the service provider to use was not specified in the call to WpCreateSite, and the postinfo file either could not be retrieved or did not specify the service provider to use, determine the service provider by auto-binding. This entails calling WppBindToSite without the WPF_FORCE_BIND flag against each of the service providers installed on the user's machine until one returns success. If none return success, return WEBPOST_ERROR_AUTOBIND_FAILED.
  4. The service provider is now known. Create a value on the site key specifying the service provider for the site.
  5. Call WppBindToSite against that service provider with the WPF_FORCE_BIND flag. If WppBindToSite returns an error, WpCreateSite attempts to obtain and cache a translation for the error code, and returns WEBPOST_ERROR_EXTENDED_ERROR. The cached error message can then be retrieved by calling WpGetErrorString with the WEBPOST_ERROR_EXTENDED_ERROR error code.

Examples
C/C++

{
    HRESULT hResult = NOERROR;

    hResult = WpCreateSite("site1", NULL, "site1", NULL, 0);
}

WpDeleteSite

DWORD WpDeleteSite(
    [in, string]   LPTSTR   szSiteName
    );

Deletes a site from the registry.

szSiteName
Posting site name.

WpDeleteSite calls WppDeleteSite on the provider that owns the specified site.

Examples
C/C++

{
    HRESULT hResult = NOERROR;

    hResult = WpDeleteSite("site1");
}

WpDoesSiteExist

DWORD WpDoesSiteExist(
    [in, string]   LPTSTR   szSiteName
    [out]          BOOL   *   pbSiteExists
);

Checks to see whether a site with the specified name exists.

szSiteName
Posting site name.
pbSiteExists
Returned as TRUE if site exists, FALSE otherwise.

Examples
C/C++

{
    HRESULT hResult = NOERROR;
    BOOL b;

    hResult = WpDoesSiteExist("site1",&b);
}

WpEnumProviders

DWORD WpEnumProviders(
    [in, out]   LPDWORD   pdwProvidersBufLen
    [out]       LPWPPROVINFO   pProvidersBuffer
    [out]       LPDWORD   pdwNumProviders
    );

Retrieves the list of all currently registered providers.

pdwProvidersBufLen
Size, in bytes, of pProvidersBuffer. On return, contains the actual number of bytes used in pProvidersBuffer. If pProvidersBuffer is NULL or too small to hold all the providers, this parameter shows the necessary size of the buffer to allocate.
pProvidersBuffer
Receives an array of WPPROVINFO structures.
pdwNumProviders
Number of providers. This value is set whether or not pProvidersBuffer is NULL or points to a large enough buffer.

Examples
C/C++

{
    HRESULT hResult = NOERROR;
    DWORD BufLen;
    DWORD Num;

    hResult = WpEnumProviders(&BufLen, NULL, &Num); 
}

WpGetErrorString

DWORD WpGetErrorString(
    [in]        UINT      uErrCode
    [in, out]   LPTSTR    szOutputBuf
    [in, out]   DWORD *   pdwBuflen
    );

Provides a textual explanation of the specified error code.

uErrCode
The error code to translate.
szOutputBuf
The error message as NULL-terminated string. If NULL or not large enough, then use the value returned in pdwBufLen to allocate the necessary buffer.
pdwBufLen
On entry, the size of buffer provided. On return, the required buffer size in bytes.

Examples
C/C++

{
    HRESULT hResult = NOERROR;
    DWORD BufLen;

    hResult = WpGetErrorString(0, NULL, &BufLen);
}

WpListSites

DWORD WpListSites(
    [in, out]   LPDWORD        pdwSitesBufLen
    [out]       LPWPSITEINFO   pSitesBuffer
    [out]       LPDWORD        pdwNumSites
    );

Retrieves the list of all sites about which Web Publishing currently has information.

pdwSitesBufLen
Size, in bytes, of pSitesBuffer. On return, contains the actual number of bytes used in pSitesBuffer. If pSitesBuffer is NULL or too small to hold all the sites, this parameter shows the necessary size of the buffer to allocate.
pSitesBuffer
Receives an array of WPSITEINFO structures.
pdwNumSites
Number of sites. This value is set whether or not pdwSitesBuffer is NULL or points to a large enough buffer.

Examples
C/C++

{
    HRESULT hResult = NOERROR;
    DWORD BufLen;
    DWORD Num;

    hResult = WpListSites(&BufLen, NULL, &Num);
}

WpPost

DWORD WpPost(
    [in]        HWND      hWnd
    [in]        DWORD     dwNumLocalPaths
    [in]        LPTSTR *  pszLocalPaths
    [in, out]   LPDWORD   pdwSiteNameBufLen
    [in, out]   LPTSTR    szSiteName
    [in, out]   LPDWORD   pdwDestURLBufLen
    [in, out]   LPTSTR    szDestURL
    [in]        DWORD     dwFlags
    );

Posts files and directories to a desired site.

hWnd
Optional. Window handle to receive focus upon completion of this API call. May be NULL.
dwNumLocalPaths
Number of elements in the array pointed to by pszLocalPaths.
pszLocalPaths
String names of files or directories to be posted. If the string specifies a directory (and the WPF_NO_RECURSIVE_POST flag is not set in the dwFlags parameter), all the files in that directory are posted.
pdwSiteNameBufLen
Size, in bytes, of buffer szSiteName. On return, contains the actual number of bytes used in szSiteName. If szSiteName is NULL or too small, this parameter shows the necessary size of the buffer to allocate.
szSiteName
The posting site name. This parameter and the szDestURL parameter may not both be NULL or empty if the WPF_NO_WIZARD flag is set. If this parameter is non-NULL and of sufficient size, and the WPF_NO_WIZARD flag is not set, then on return it will contain the site to which the files were posted.
pdwDestURLBufLen
Size, in bytes, of buffer szDestURL. On return, contains the actual number of bytes used in szDestURL. If szDestURL is NULL or too small, this parameter shows the necessary size of the buffer to allocate.
szDestURL
The destination URL. If this parameter is non-NULL and of sufficient size, and the WPF_NO_WIZARD flag is not set, then on return it will contain the destination URL for the site.
dwFlags
Action flags. Possible values are shown in the following table.
Value Meaning
WPF_FIRST_FILE_AS_DEFAULT Take the first file specified in pszLocalPaths as the file that will be shown as the default page.
WPF_NO_RECURSIVE_POST If any element in pszLocalPaths points to a directory, do not post files recursively.
WPF_NO_WIZARD Do not prompt the user for any input.
WPF_NO_DIRECT_LOOKUP Do not attempt to look up the site based on the site name. This has the same effect as a NULL or empty szSiteName.
WPF_NO_URL_LOOKUP Do not attempt to look up the site based on the site URL. This has the same effect as a NULL or empty szSiteURL.
WPF_NO_PROGRESS_DLGS Do not show the "Publishing files" progress bar during the transfer of files to the destination computer.
WPF_NO_UI Predefined combination of WPF_NO_WIZARD and WPF_NO_PROGRESS_DLGS.
WPF_SHOWPAGE_WELCOME Forces the wizard to display the initial "Publish Your Files on the Web" page. Normally this page is skipped if the only other page being displayed is the Finish page. Note that the WPF_NO_WIZARD flag overrides this one.
WPF_SHOWPAGE_SRCFILE Forces the wizard to display the "Select a File or Folder" page. Normally this page is skipped if the path or paths to publish are specified in the call to WpPost. Note that the WPF_NO_WIZARD flag overrides this one.
WPF_SHOWPAGE_DESTSITE Forces the wizard to display the "Select a Web Server" page. Normally this page is skipped if the site name is specified in the call to WpPost. Note that the WPF_NO_WIZARD flag overrides this one.
WPF_SHOWPAGE_PROVIDER Forces the wizard to display any and all pages associated with the service provider. Note that it is the responsibility of service provider implementations to be compliant with this flag (see the specification of the AddWizardPages SPI function below). Note that the WPF_NO_WIZARD flag overrides this one.
WPF_SHOWPAGE_ALL Predefined combination of WPF_SHOWPAGE_*. Note that the WPF_NO_WIZARD flag overrides this one.

If the wizard is invoked (the WPF_NO_WIZARD flag is not set), the wizard will examine the information specified in the call to WpPost and display the minimum set of pages necessary to complete the publishing process (this minimum-UI behavior may be overridden with the WPF_SHOWPAGE flags as described in the table below). If the user is prompted to enter the friendly name and/or URL for the site, this information is returned to the caller of WpPost in the buffers provided.

If the wizard is not invoked, WpPost calls WpBindToSite to get an interface pointer to the provider that owns the specified site. If the WpBindToSite call fails, WpPost tries to create the site by calling WpCreateSite. Note that WpPost passes the destination URL to WpBindToSite and WpCreateSite. When calling WpCreateSite, it also passes NULL for the local base directory, indicating that this site does not use the local base directory feature and that all posts to this site should go to the root destination URL; and it passes NULL for the service provider, specifying that the service provider should be determined by auto-binding. If the site's provider cannot be determined from the site name passed to WpPost or an auto-bind, WpPost will fail.

Since WpPost relies on WpBindToSite to do site lookup, all site lookup functionality resides within WpBindToSite. The procedure followed when performing this lookup is detailed under WpBindToSite.

Examples
C/C++

{
    HRESULT hResult = NOERROR;
    LPTSTR szLocalPaths = {"c:\\MyDir"};

    hResult = WpPost(NULL, 1, &szLocalPaths, 0, NULL, 0, NULL, 0);
}

WpPostFile

HRESULT WpPostFile(
    [in]        LONG      hWnd
    [in]        BSTR      bstrLocalPath
    [in, out]   LONG *    plSiteNameBufLen
    [in, out]   BSTR      bstrSiteName
    [in, out]   LONG *    plDestURLBufLen
    [in, out]   BSTR      bstrDestURL
    [in]        LONG      lFlags
    [out, retval]   LONG *   plRetCode
    );

Simply a version of WpPost accessible through WpObj's COM interface. The functionality is identical to that described in WpPost except as follows:

hWnd
Same as WpPost.
bstrLocalPath
String name of a single file or directory to be posted. If the string specifies a directory (and the WPF_NO_RECURSIVE_POST flag is not set in the lFlags parameter), all the files in that directory are posted.
plSiteNameBufLen
Same as WpPost.
bstrSiteName
Same as WpPost.
plDestURLBufLen
Same as WpPost.
bstrDestURL
Same as WpPost.
lFlags
Same as WpPost.
plRetCode
Pointer to a long integer that receives the return code of the operation.

The Web Publishing SPI

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 configured site.
Interface method Description
AddWizardPages Allows the provider DLLs to plug pages into the wizard invoked by the WpPost function.
DeleteFile Deletes the specified 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 method.
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.

WppBindToSite

LONG WppBindToSite(
    [in]           HWND      hwnd,
    [in, string]   LPCTSTR   wsSiteName,
    [in, string]   LPCTSTR   wsURL,
    [in]           REFIID    riid,
    [in]           DWORD     fdwFlags,
    [in]           DWORD     dwReserved,
    [out]          PVOID *   ppvObj
    );

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

hwnd
Handle of the window to which the focus returns when the wizard, if invoked, completes. This parameter can be NULL if the wizard is not invoked or if this function is called from a console application.
wsSiteName
Optional. Address of a null-terminated string that contains an Internet site name.
wsURL
Optional. Address of a null-terminated string that contains a URL.
riid
Interface identifier. All providers should support the IID_IWPSite interface identifier. Provider implementations that implement IWPProvider should also support the IID_IWPProvider ID.
fdwFlags
Action flags. Possible values are shown in the following table.
Value Meaning
WPF_FORCE_BIND The provider should not query the site to see whether it can post to it (that is, do not test whether the protocol used by the provider is supported by the server).
dwReserved
Reserved, and must be set to zero (0).
ppvObj
Address of a variable to receive the interface address.

Examples

See a C++ sample provider template included with WebPost in the Internet Client SDK.

WppDeleteSite

LONG WppDeleteSite(
    [in, string]   LPCTSTR   wsSiteName
    ); 

Deletes a configured site.

wsSiteName
Address of a null-terminated string that contains the site name.

Examples

See a C++ sample provider template included with WebPost in the Internet Client SDK.

AddWizardPages

HRESULT AddWizardPages(
    [in]        LPVOID   pvFlags,
    [in]        LPFNADDPROPSHEETPAGE   pfnAdd,
    [in, out]   LPARAM   pParam
    );

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

pvFlags
The address of a LONG containing action flags. This parameter must be cast to an LPVOID in the call to AddWizardPages for backward compatibility. The only flag value supported is WPF_SHOWPAGE_PROVIDER, which indicates that the service provider should add its pages to the wizard whether or not it thinks that they are required.
pfnAdd
Address of a function that this Web Publishing service provider should use to add wizard pages. The declaration of this function-pointer type (LPFNADDPROPSHEETPAGE) is included in the header files of the Win32 SDK.
pParam
Address of a page identifier, an unsigned integer.

As input to this function, the low-order word is the dialog identifier of the page after the last page of the provider, and the high-order word is the dialog identifier of the page before the first page of the provider.

As output from this function, the low-order word is the dialog identifier of the provider's last page, and the high-order word is the dialog identifier of the provider's first page. If the provider has no pages, it should return zero as the page identifier.

As an example, in setting up a new site the wizard would provide the friendly site name and the site's URL and the provider DLLs would handle the rest of the site set up. The dialog identifier of the provider wizard page should be a value between the values of IDD_FIRST_PROV_PAGE and IDD_LAST_PROV_PAGE, as defined in the file WPPDEFS.H included with the stubbed service provider among the SDK samples.

Commit

HRESULT Commit(void);

Ensures that all the files posted to this server with the PostFiles function are actually written to the Internet server.

If a callback function has been specified to the service provider with a previous call into SetProgressUpdateProc, the service provider should call the callback function while committing. See the description of SetProgressUpdateProc for more information.

DeleteFile

HRESULT DeleteFile(
    [in, string]   LPCWSTR   wsFile
    );

Deletes the given file from the destination site.

wsFile
Address of a null-terminated string that contains the name of the file to delete.

FindClose

HRESULT FindClose(
    [in]   HANDLE   hSearchHandle
    );

Closes the specified search handle.

hSearchHandle
Search handle returned by a previous call to the FindFirstFile function.

The FindFirstFile and FindNextFile functions use the search handle to locate files with names that match a given name.

FindFirstFile

HRESULT FindFirstFile(
    [in, string]   LPCWSTR    wsSearchFile,
    [out]          LPWIN32_FIND_DATAW   pFindFileData,
    [out]          LPHANDLE   pSearchHandle
    );

Searches a directory for a file whose name matches the specified file name on the destination site identified by this object. It examines subdirectory names as well as file names.

wsSearchFile
Address of a null-terminated string that contains the file name to find.
pFindFileData
Address of a WIN32_FIND_DATA structure that receives information about the file or subdirectory that has been found.
pSearchHandle
Address of a variable that receives a handle that can be used for subsequent calls to the FindNextFile and FindClose functions.

FindNextFile

HRESULT FindNextFile(
    [in]    HANDLE   hSearchHandle,
    [out]   LPWIN32_FIND_DATAW   pFindFileData
    ); 

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

hSearchHandle
Search handle returned by a previous call to the FindFirstFile function.
pFindFileData
Address of a WIN32_FIND_DATA structure that receives information about the file or subdirectory that has been found.

GetError

HRESULT GetError(
    [out]       LPDWORD   pdwErrorType,
    [in, out]   LPDWORD   pdwErrorCode,
    [in, out]   LPDWORD   pdwErrorBufLen,
    [out, string]   LPWSTR   wsError
    );

Retrieves additional information about an error.

pdwErrorType
Indicates the error type. Currently set to zero.
pdwErrorCode
Indicates the error code.
pdwErrorBufLen
Indicates the size, in bytes, of the wsError buffer. Set to the number of bytes written to wsError if the buffer was large enough, or to the required buffer size if the buffer was not large enough.
wsError
Address of a buffer that receives the error information.

GetParam

HRESULT GetParam(
    [in, string]   LPCWSTR   wsParameter,
    [in, out]      LPDWORD   pdwValueBufLen,
    [out, string]  LPWSTR    wsValue
    );

Retrieves a parameter value for this site.

wsParameter
Address of a null-terminated string that contains the name of a site parameter.
pdwValueBufLen
Address of a variable that receives the size of the wsValue buffer. If wsValue is NULL, or if the buffer length is short, this variable receives the size, in bytes, of the parameter name.
wsValue
Address of a buffer that receives the value of the parameter queried.

GetSiteInfo

HRESULT GetSiteInfo(
    [out]       LPWPSITEINFO   pbSite,
    [in, out]   LPDWORD       pdwSiteBufLen
    );

Retrieves the site information for the current object.

Note With version 1.5, implementation of this function has become optional, since site management should be done with the Web Publishing API.

pbSite
Address of a buffer that receives a WPSITEINFO structure containing the site information.
pdwSiteBufLen
Address of a variable that contains the size, in bytes, of the pbSite buffer.

NetworkConnect

HRESULT NetworkConnect(
    [in, string]   LPCWSTR   wsUserName,
    [in, string]   LPCWSTR   wsPassword
    );

Connects to the Internet.

wsUserName
Address of a null-terminated string that contains the user name for the Internet connection.
wsPassword
Address of a null-terminated string that contains the password for the Internet connection.

NetworkDisconnect

HRESULT NetworkDisconnect(void);

Disconnects from the Internet (hangs up if a dial-up connection was used).

PostFiles

HRESULT PostFiles(
    [in]           DWORD   cLocalPaths,
    [in, string]   LPWSTR *   pwsLocalPaths,
    [in, out]      LPDWORD    pdwURLBufLen,
    [in, out, string]   LPWSTR   wsURL,
    [in]           DWORD   fdwFlags
    );

Posts files to the specified URL on the destination site identified by this object.

cLocalPaths
Number of elements in the pwsLocalPaths array.
pwsLocalPaths
Address of an array of null-terminated strings that contain the file names or directories to be posted on the Internet. If any of these strings point to a directory and the WPF_NO_RECURSIVE_POST flag is not set in fdwFlags, all the files in that directory are posted.
pdwURLBufLen
Address of a variable that indicates the length of the wsURL buffer. When the function returns, the variable contains the length, in bytes, of the buffer.
wsURL
Optional. Address of a null-terminated string that contains the destination URL. If this parameter is NULL, the files are posted in the root URL for the site.

If this parameter is not NULL, the URL of the copied file, or the URL of the directory that the files were copied to, is returned in the buffer pointed to by this parameter.

fdwFlags
Action flags.
Value Meaning
WPF_NO_RECURSIVE_POST If any element in the pwsLocalPaths array points to a directory, do not post files recursively.

Changes for version 1.5:
Service providers are no longer required to support the posting of multiple files. It is not a violation of the interface contract for a service provider to return failure if cLocalPaths is greater than 1.
If a callback function has been specified to the service provider with a previous call into SetProgressUpdateProc, the service provider should call the callback function while posting. See the description of SetProgressUpdateProc below for more information.

See also WpPost

ServerLogin

HRESULT ServerLogin(
    [in, string]   LPCWSTR   wsUserName,
    [in, string]   LPCWSTR   wsPassword
    );

Logs the user on to the Internet server.

wsUserName
Address of a null-terminated string that contains the user name for the Internet server.
wsPassword
Address of a null-terminated string that contains the password for the Internet server.

The given user name and password are for the Internet server. They may or may not be the same as those used for the NetworkConnect function.

ServerLogout

HRESULT ServerLogout(void);

Logs the user out of the Internet server.

SetParam

HRESULT SetParam(
    [in, string]   LPCWSTR   wsParameter,
    [in, string]   LPCWSTR   wsValue
    ); 

Sets the value of a parameter for a given site.

wsParameter
Address of a null-terminated string that contains a parameter name.
wsValue
Address of a null-terminated string that contains the configuration parameter value.

SetProgressUpdateProc

HRESULT SetProgressUpdateProc(
    [in]   LONG *   pfnProgressUpdateProc
    ); 

Specifies the callback function the provider should use to update the "Publishing Files" progress dialog displayed by the API.

pfnProgressUpdateProc
Function with the following declaration:
HRESULT CALLBACK *pfnProgressUpdateProc(
    [in, string   LPCWSTR   wsFileName,
    [in]          DWORD     dwNumBytes
    );

The type PFNPROGRESSUPDATEPROC declared in WPSPI.IDL encapsulates this declaration.

The service provider should cache the function pointer specified here so that it can call into the update procedure from PostFiles and Commit. (The progress bar is reset after all the PostFiles calls have been made, and fills a second time during the call to Commit.)

The Service Provider should call this function from both PostFiles and Commit to update the progress dialog as it posts and commits the files passed to it. WpPost will do a series of PostFiles calls, followed by a single call to Commit. The API keeps track of the total number of bytes being transferred, so on each call the service provider should just specify the file name to display and the number of bytes that have been posted or committed since the last call.

If the update procedure returns an error, the Service Provider must quit its current operation and return the error (as the result code from PostFiles or Commit). This ensures that if the "Cancel" button is clicked by the user during publishing, it will be processed correctly.

A typical call to the callback procedure is as follows:

HRESULT = (*m_pfnProgressUpdateProc)(wsFileName, dwFileSize);

If the service provider wishes to change the file name displayed in the progress dialog without advancing the progress bar, it should make a call such as the following:

hResult = (*m_pfnProgressUpdateProc)(wsFileName, 0);

The File Upload Control Interface

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.

AboutBox

HRESULT AboutBox(void);

Displays a friendly message about the File Upload Control.

CreatePermBinding

CreatePermBinding(
    [in]   BSTR   bstrBindingName,
    [in]   BSTR   bstrDestUrl,
    [in]   BSTR   bstrProvCLSID
    ); 

Creates a permanent site and binds to it.

bstrBindingName
Address of a null-terminated string that contains the site name. This may not be NULL or empty.
bstrDestUrl
Address of a null-terminated string that contains the destination URL for the site. This is where the files dropped on the File Upload Control will be posted. This may not be a NULL or empty.
bstrProvCLSID
Address of a null-terminated string that contains the CLSID of the provider that will handle this site. This may be NULL or empty, in which case the File Upload Control will attempt to find a posting information file or auto-bind to an appropriate provider.

The site information is persistent, that is, it will remain on the user's machine even after the browser is shut down.

CreateTempBinding

HRESULT CreateTempBinding(
    [in]   BSTR   bsDestUrl,
    [in]   BSTR   bsProvCLSID
    ); 

Creates a temporary site and binds to it.

bsDestUrl
Address of a null-terminated string that contains the destination URL for the site. This is where the files dropped on the File Upload Control will be posted. This may not be NULL or empty.
bsProvCLSID
Address of a null-terminated string that contains the CLSID of the provider that will handle this site. This may be NULL or empty, in which case the File Upload Control will attempt to find a posting information file or auto-bind to an appropriate provider.

Garbage collection should take care of this site information when the user shuts down the browser.

Example

Sample HTML Usage

<HTML>
<HEAD>
<TITLE>File Upload Control</TITLE>
</HEAD>

<BODY LEFTMARGIN=20 TOPMARGIN=20 BGCOLOR=#FFFFFF TEXT=#000000 LINK=#FF0066 VLINK=#330099 ALINK=#000000 language="VBS" onload="InitializeControl">

<FONT FACE="ARIAL" SIZE=2>

<CENTER>

<p><FONT SIZE=5><B>Welcome</B></FONT>
</CENTER>

<H3>File Upload</H3>

<p>
You can upload your html content using this control.
<OBJECT
    classid="clsid:886E7BF0-C867-11CF-B1AE-00AA00A3F2C3"
    id=FlUpl1
    width=100
    height=100
    align=textmiddle
    color=blue
    codebase=http://eshwar_crs/flupl/FlUpl.cab#Version=6,0,86,0
>
</OBJECT> 
You may drag and drop files onto it. Or double click on it to get a FileOpen dialog.

<SCRIPT LANGUAGE="VBS">

Sub InitializeControl
    FlUpl1.CreateTempBinding "http://my_server", "{8B14B770-748C-11D0-A309-00C04FD7CFC5}"
End Sub

</SCRIPT>

<P ALIGN=CENTER><FONT SIZE=2><B>For more information on VB Script, visit the <A TARGET="_top" HREF="/vbscript/default.htm">VB Script site.</A></B></FONT>

</FONT>

</BODY>
</HTML>

FoundPostInfo

HRESULT FoundPostInfo(void);

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

This property is set to true if during a CreateTempBinding or CreatePermBinding call a postinfo file was found on the server.

Example


' This example demonstrates binding parameters required by the CRS provider

Flupl.CreateTempBinding "<http://www.icp.com/hello>", "{FFCF1E40-7978-11D0-B1C9-00AA006DCDF4}"

If not Flupl.FoundPostInfo then
    Flupl.SetBindingParam "Servername", "www.crsserver.com <http://>"
    Flupl.SetBindingParam "Authentication", "MSN, NTLM"
Endif

SetBindingParam

HRESULT SetBindingParam(
    [in]   BSTR   bstrParamName,
    [in]   BSTR   bstrParamValue
    ); 

Sets the parameters of an incomplete binding in case a previous CreateTempBinding or CreatePermBinding call failed to find a postinfo file on the server.

bstrParamName
Address of a null-terminated string that contains the name of the provider-specific binding parameter to be set.
bstrParamValue
Address of a null-terminated string that contains the value to which the parameter should be set.

This method takes the name of the provider-specific binding parameter and the value and sets it. This should be used only as a fallback mechanism in case the postinfo file isn't found on the server.

Appendix A, Structures

The following structures are used in this SDK.

WPPROVINFO

typedef struct tagWPPROVINFO
{
    DWORD    dwSize;
    DWORD    dwFlags;
    DWORD    dwPriority;
    LPTSTR   lpszProviderName;
    LPTSTR   lpszProviderCLSID;
    LPTSTR   lpszDllPath;
}
WPPROVINFO, *LPWPPROVINFO;
dwSize
Size of the provider information structure in bytes, including the string buffers for the name, CLSID, and DLL path.
dwFlags
Provider flags. Not currently used.
dwPriority
Integer that indicates the provider's priority. Zero is highest priority.
lpszProviderName
Friendly name of the provider.
lpszProviderCLSID
CLSID of the provider implementation object.
lpszDllPath
Fully qualified path of the DLL that contains the COM server for the provider.

WPSITEINFO

typedef struct tagWPSITEINFO
{
    DWORD    dwSize;
    DWORD    dwFlags;
    LPTSTR   lpszSiteName;
    LPTSTR   lpszSiteURL;
}
WPSITEINFO, *LPWPSITEINFO;
dwSize
Size of the site information structure in bytes, including the string buffers for the site name and URL.
dwFlags
Site flags. Not currently used.
lpszSiteName
Friendly name of the site.
lpszSiteURL
Destination URL for the site (location where posted files can be accessed).

Appendix B, Error Codes

The following error codes are used in this SDK.

Web Publishing API

Error code Meaning
WEBPOST_ERROR_AUTOBIND_FAILED The Web Publishing API was unable to automatically determine which service provider to use for this site.
WEBPOST_ERROR_BAD_PROV_PTR The Web Publishing API was not able to obtain a valid pointer to the requested service provider.
WEBPOST_ERROR_COCREATE_WIZARD The Web Publishing API could not invoke the Web Publishing Wizard.
WEBPOST_ERROR_CREATE_SITE An error occurred while the Web Publishing API was creating the requested site.
WEBPOST_ERROR_DELETE_SITE An error occurred while the Web Publishing API was deleting the requested site.
WEBPOST_ERROR_ENUM_PROVS An error occurred while the Web Publishing API was enumerating the providers on this system.
WEBPOST_ERROR_EXTENDED_ERROR A Web Publishing extended error occurred. This means that the API received an error code that the API client may not be able to translate, so the API performed the translation and cached the error message for retrieval on a call to the WpGetErrorString method.
WEBPOST_ERROR_HTTP_GET_FAILED Informational (nonfailure) result indicating failure in the attempt to retrieve one of the published files with an HTTP GET. This error is only returned in cases where the files were all successfully uploaded.
WEBPOST_ERROR_INIT_FAILED An error occurred while attempting to initialize the Web Publishing API DLL.
WEBPOST_ERROR_INVALID_POSTINFO Informational (nonfailure) result indicating that the postinfo file found on the server during site creation could not be parsed correctly. This error is only returned if the site creation is otherwise successful.
WEBPOST_ERROR_LIST_SITES An error occurred while the Web Publishing API was enumerating the sites on this system.
WEBPOST_ERROR_NO_EXT_ERR_INFO An extended error occurred in the Web Publishing API, but the error message could not be retrieved.
WEBPOST_ERROR_NO_POSTINFO Informational (nonfailure) result indicating that the postinfo file could not be retrieved during a site creation. This error is only returned if the site creation is otherwise successful.
WEBPOST_ERROR_POST_FILES An error occurred while the Web Publishing API was attempting to post the requested files.
WEBPOST_ERROR_POSTINFO_REQUIRED This service provider requires a postinfo file on the server, and none could be found.
WEBPOST_ERROR_PROV_CORRUPT The Web Publishing API could not retrieve all of the required service provider information.
WEBPOST_ERROR_PROV_DLL The Web Publishing API could not load the DLL for one of its service providers.
WEBPOST_ERROR_PROV_EP The Web Publishing API could not locate a required entry point in one of its service providers.
WEBPOST_ERROR_PROV_NOT_IN_POSTINFO The server to which you are trying to post does not indicate support for the service provider you have requested.
WEBPOST_ERROR_PROV_QI The Web Publishing API was unable to determine what interface is exported by the specified service provider.
WEBPOST_ERROR_PROVCLSID_UNKNOWN The Web Publishing API could not locate the service provider used to transfer files to this site.
WEBPOST_ERROR_SITE_CORRUPT The Web Publishing API could not retrieve all of the required site information.
WEBPOST_ERROR_SITE_DOESNOTEXIST The Web Publishing API could not delete the requested site because no site with the specified name exists.
WEBPOST_ERROR_SITE_EXISTS The Web Publishing API could not create the requested site because a site with the same name already exists.
WEBPOST_ERROR_UNKNOWN An unknown error occurred during Web Publishing.
WPWIZ_ERROR_COCREATE_WEBPOST The Web Publishing Wizard could not create the Web Publishing implementation object.
WPWIZ_ERROR_FILE_NOT_FOUND The local file(s) selected to be published could not be found.
WPWIZ_ERROR_INIT_FAILED An error occurred during the initialization of the Web Publishing Wizard.
WPWIZ_ERROR_NO_PROVIDERS The Web Publishing Wizard could not run because there are no service providers installed.
WPWIZ_ERROR_OUTOFMEMORY The Wizard ran out of memory.
WPWIZ_ERROR_PROPSHEET_ERROR The wizard received an error result back from the PropertySheet() call into the system.
WPWIZ_ERROR_PROV_QI The Web Publishing Wizard could not determine which interface is exported by the requested service provider.
WPWIZ_ERROR_STATE_PTR The Web Publishing Wizard could not retrieve a pointer to its state object.
WPWIZ_ERROR_UNKNOWN An unknown error occurred.
WPWIZ_ERROR_WEBPOST_PTR The Web Publishing Wizard cannot complete the operation because it does not have a pointer to the Web Publishing API implementation object.

Web Publishing SPI

Error code Meaning
CRSWPP_BIND_FAILED Could not bind to the site with the information specified.
CRSWPP_FAILED_AUTH You do not have the necessary access privileges to post content to this CRS server.
CRSWPP_INVALID_POSTINFO_FILE The postinfo file is invalid on the server you selected.
CRSWPP_NO_MATCHING_MAPURL The CRS project you selected has no MAPURL.
CRSWPP_POSTINFO_NEEDED Server does not have a postinfo file. Additional information is needed, please invoke my Wizard Pages to complete bind operation.
CRSWPP_PROJECT_BINDING_INCOMPLETE An internal error (0x2205) has occurred in the CRS service provider.
CRSWPP_SECURITY_PACKAGE The initialization of the security package failed.
CRSWPP_SECURITY_PACKAGE_NOT_FOUND The security package(s) required by the server could not be found on your computer.
CRSWPP_SERVER_BINDING_INCOMPLETE The site is not yet bound to a CRS server.
CRSWPP_SERVER_NOT_RESPONDING The CRS server is not responding.
FTPWPP_ERROR_AUTHENTICATION_FAILED The FTP service provider was unable to log on to the FTP server.
FTPWPP_ERROR_INETOPEN_FAILED The FTP service provider was not able to connect to the Internet.
WPP_POST_POSTING_NO_RESPONSE_ERROR Posting Server response is either missing or invalid. No status is available about the uploaded files.
WPP_POST_POSTING_SERVER_ERROR Server returned a posting error.
WPP_POST_POSTING_URL_ERROR The supplied posting URL is invalid.

Appendix C, Parameters

The following tables list the parameters supported by each Microsoft service provider. When writing a posting information file for a server, as many parameters as possible should be specified for each service provider the server will support, in order to minimize the amount of information that must be entered by a user.

The DefaultPage parameter is handled by the Web Publishing API (as such it is not listed under the individual service providers below). It specifies the name to use when saving a file as the default page for a site (when indicated by the WPF_FIRST_FILE_AS_DEFAULT flag to WpPost).

Content Replication System Service Provider

Parameter Example value Meaning
Authentication NTLM The name of the security package to use when authenticating against the server.
ServerName myserver The name of the CRS server.

FTP Service Provider

If present, the special string "$USERNAME" will be replaced with the name of the account used to log on to the server during publishing. This string can be used in the ServerName and Subfolder values.

ConnectTimeout, ConnectRetries, SendTimeout, and ReceiveTimeout were made site parameters to allow dynamic adjustment of the waiting behavior on network calls. However, a typical postinfo file will probably not need to include these parameters. The values listed under "Example value" for these four parameters are the defaults.
Parameter Example value Meaning
ServerName myserver The name of the FTP server.
Subfolder home/users/$USERNAME The path on the FTP server where files should be saved. Note that $USERNAME will be replaced with the "UserName" value.
ConnectTimeout 30000 (msec) The length of the timeout to use when connecting to the server.
ConnectRetries 5 The number of retries to make when connecting to the server.
SendTimeout 30000 (msec) The length of the timeout for all network packets sent.
ReceiveTimeout 30000 (msec) The length of the timeout for all network packets received.
BasePath - This value is obsolete. If present on a site key that was used with version 1.1 of the Web Publishing Wizard, it will be upgraded to "Subfolder" the first time the FTP provider binds to the site.
FtpServerName - This value is obsolete. If present on a site key that was used with version 1.1 of the Web Publishing Wizard, it will be upgraded to "ServerName" the first time the FTP provider binds to the site.

HTTP POST Service Provider

Parameter Example value Meaning
PostingURL http://myserver/scripts/cpshost.dll?PUBLISH The URL of the HTTP POST acceptor.
TargetURL http://myserver/users The URL where the uploaded files should be placed.

© 1997 Microsoft Corporation. All rights reserved. Terms of Use.