Previous Page TOC Next Page



Appendix B


ActiveX Control Automation Command Reference


by William Robert Stanek

This appendix is organized using a reference guide and tutorial style that is easy to follow and reference quickly. You will find major sections for the FrontPage Explorer, the FrontPage Editor, and the FrontPage To Do List. Within the major sections, you will find listings of all the procedures you can use with a particular FrontPage Component.

ActiveX technology is simply Object Linking and Embedding (OLE) for the Internet. The sections that follow examine the OLE interface for FrontPage.Sections devoted to procedures are organized into four parts:


Using ActiveX Control Automation with the Frontpage Explorer


The FrontPage Explorer's OLE interface provides a specific set of OLE commands that you can use in your wizards. This section highlights these commands.

vtiBringToTop


The vtiBringToTop procedure brings the FrontPage Explorer to the front of the display and makes it active.

Parameters

None

Return Value

None

Usage

Visual C++:




void vtiBringToTop();

Visual Basic:




vtiBringToTop

vtiCancelRequests


The vtiCancelRequests procedure cancels any pending requests from the FrontPage Explorer to the Web server. This procedure has the same effect as pushing the Stop button on the FrontPage Explorer or FrontPage Editor toolbar.

Parameters

None

Return Value

None

Usage

Visual C++:




void vtiCancelRequests();

Visual Basic:




CancelRequests

vtiCreateFolder


The vtiCreateFolder procedure creates a folder in the current web.

Parameters

FolderURL: a string that specifies the name of the folder to create, such as Images or Videos.

Return Value

The procedure returns the value of 1 to indicate success and the value of 0 to indicate failure.

Usage

Visual C++:




long vtiCreateFolder (LPCTSTR pszFolderUrl);

Visual Basic:




vtiCreateFolder (FolderUrl as String) as Long

Using vtiCreateWeb


The vtiCreateWeb procedure creates a new Web. All the rules for Web names apply when you create a Web. Keep in mind that the RootWeb is generally created when FrontPage is installed. All Webs you add afterward are children of the RootWeb and as such are stored in subdirectories under the RootWeb. Because this is a blocking procedure, it is expected to pass output back to the caller, which is usually the exit status of the wizard.



Normally, FrontPage creates new Webs (when necessary) before launching a wizard. This means that most of the time you don't need to call this procedure directly.



Parameters

ServerName: the host name or IP address of the Web server, which can include an optional port number. Examples: www.your_company.com, www.your_company.com:8080.

WebName: the name of the Web you want to create. Example: your_web.

Return Value

The procedure returns the value of 1 to indicate success and the value of 0 to indicate failure.

Usage

Visual C++:




long vtiCreateWeb(LPCTSTR szServerName, LPCTSTR szWebName);

Visual Basic:




vtiCreateWeb(ServerName as String, WebName as String) as Long

vtiDisableErrorDialogs


The vtiDisableErrorDialogs procedure allows you to turn off the display of error message dialog boxes that might be caused by your OLE Automation calls. You will find that this procedure is useful when creating automated processes.

Parameters

YesNo: turn error dialogs on or off. A setting of true tells the FrontPage Explorer to turn off error dialogs until the current action is completed.

Usage

Visual C++:




void vtiDisableErrorDialogs(BOOL bYesNo);

Visual Basic:




vtiDisableErrorDialogs(YesNo as Integer)

Return Value

None.

vtiEditWebPage


The vtiEditWebPage procedure loads a page into the appropriate editor. Because you can use relative and absolute URL paths, the page can come from the current Web or from the Internet. The FrontPage Explorer determines the editor to use based on the extension of the file you are loading. Usually, the editor for HTML documents is the FrontPage Editor.

Because the procedure is non-blocking, it returns control immediately and does not wait until the page is loaded into an editor.

Parameters

PageURL: the relative or absolute path to the file. For absolute paths, you should use the full hypertext reference. Examples: http://www.your_server2.com/, banner.gif, and index.html.

Return Value

The procedure returns the value of 1 to indicate success and the value of 0 to indicate failure.

Usage

Visual C++:




long vtiEditWebPage(LPCTSTR pszPageURL);

Visual Basic:




vtiEditWebPage(PageURL as String) as Long

vtiGetDocToFile


The vtiGetDocToFile procedure retrieves a document and saves it to a local file on the user's file system. Because you can use relative and absolute URL paths, you can retrieve the page from the current Web or from the Internet. This call blocks until the file is finished downloading.

Parameters

URL: the relative or absolute path to the file. For absolute paths, you should use the full hypertext reference. Examples: http://www.your_server2.com/, banner.gif, and index.html.

FileName: the full path to where the file should be saved on the user's file system. Example: C:\temp\newpage.htm.

Return Value

The procedure returns the value of 1 to indicate success and the value of 0 to indicate failure.

Usage

Visual C++:




long vtiGetDocToFile(LPCTSTR pszURL, LPCTSTR pszFilename);

Visual Basic:




vtiGetDocToFile(URL as String, FileName as String) as Long

vtiGetFoldersList


The vtiGetFoldersList procedure returns a list of URLs to subfolders of a specified folder.

Parameters

ParentFolderUrl: the folder in which FrontPage should look for subfolders. If you want to get a list of top-level folders, use an empty string.

Return Value

The procedure returns a list of folder URLs.

Usage

Visual C++:




BSTR vtiGetFoldersList(LPCTSTR pszParentFolderUrl);

Visual Basic:




vtiGetFoldersList (ParentFolderUrl as String) as String

vtiGetPagesInFolder


The vtiGetPagesInFolder procedure returns a list of files that are found in the named folder. Files are always listed by page title and URL.

Parameters

FolderUrl: a string containing the name of the folder to look in for files. To get a list of pages in the top-level folder, use an empty string.

Type: the type of files to return in the list. A setting of 0 tells the procedure to return a list of all files in the folder. A setting of 1 tells the procedure to return a list of HTML pages in the folder. A setting of 2 tells the procedure to return a list of images in the folder. A setting of 3 tells the procedure to return a list of video files in the folder. A setting of 4 tells the procedure to return a list of executable files in the folder. A setting of 5 tells the procedure to return a list of sound files in the folder. A setting of 6 tells the procedure to return a list of database files in the folder. A setting of 7 tells the procedure to return a list of HTX files in the folder. A setting of 8 tells the procedure to return a list of PowerPoint Animation files in the folder.

Return Value

The procedure returns a list of page titles and URLs. Items in the list are separated by the newline character \n, such as "title1\nURL1\ntitle2\nURL2\n".

Usage

Visual C++:




BSTR vtiGetPagesInFolder(LPCTSTR pszFolderUrl, long lType);

Visual Basic:




vtiGetPagesInFolder (FolderURL as String, Type as long) as String

vtiGetPageList


The vtiGetPageList procedure returns a list of all the files of a specific type in the current Web. The list organizes files by URL and title.

There are three file types that you can request: HTML, Image, and All. HTML files have extensions that match the extensions expected by the vti_HtmlExtensions Web meta-information variable. Image files are those that have the .gif, .jpg, or .jpeg extension. When you request all files, you see all files in the Web regardless of the file extension.

Parameters

DocType: an integer value from 0-2 that identifies the type of document you want to see a listing of. If the value of DocType is 0, all files in the current Web are returned. If the value of DocType is 1, only HTML files are returned. If the value of DocType is 2, Image files are returned.

Return Value

The procedure returns a string with two entries. The first entry is for the document title. The second entry is for the page URL of the document. If a document doesn't have a title, the page URL is inserted in the position normally reserved for the title. A new line character is used to separate each entry and all successive entries. If there is no current Web or there are no documents in the current Web, the result is an empty string. Examples:




"My Home Page\nindex.htm\nMy Link Page\nlinks.htm"

and




"My Home Page" & CHR$(10) & "index.htm" & CHR$(10) &



¬"My Link Page" & CHR$(10) & "links.htm".

NOTE

In Visual C++, the newline character is backslash n (\n). In Visual Basic, the newline character is CHR$(10).



Usage

Visual C++:




CString vtiGetPageList(long lType);

Visual Basic:




vtiGetPageList(DocType as Long) as String

vtiGetWebMetaInfo


The vtiGetWebMetaInfo procedure is used to get a meta-information variable associated with a Web. All Webs have meta-information lists, which contain name-value pairs for meta-information parameters. Parameters that begin with the prefix vti_ are reserved by FrontPage. As with other meta-information variables, the parameter names for Webs are not case-sensitive.

Parameters

Key: a key word that identifies the meta-information variable you want to get.

Most parameter names associated with Webs are fixed and include


Return Value

The procedure returns a string containing the value of the requested key, or an empty string if the key doesn't exist.

Usage

Visual C++:




CString vtiGetWebMetaInfo(LPCTSTR szKey);

Visual Basic:




vtiGetWebMetaInfo(Key as String) as String

vtiGetWebPageMetaInfo


The vtiGetWebPageMetaInfo procedure is used to get a meta-information variable associated with a specific document in the current Web. All files in your Webs have meta-information lists, which are separate from the meta-information list for the Web the document is in.

Parameters

URL: the name of the file in the current Web. Values for this parameter can reference subdirectories. Valid subdirectories for most Webs include cgi-bin, images, and _private. Examples: newpage.htm, images\banner.gif.

KeyName: a key word that identifies the meta-information variable you want to get. Entries beginning with the prefix vti_ are reserved by FrontPage. As with other meta-information variables, the key names are not case-sensitive.

Most key names associated with documents are fixed and include the following:


Return Value

The procedure returns a string containing the value of the requested key, or an empty string if the key doesn't exist.

Usage

Visual C++:




CString vtiGetWebPageMetaInfo(LPCTSTR szURL, LPCTSTR szKeyName);

Visual Basic:




vtiGetWebPageMetaInfo(URL as String, KeyName as String) as String

vtiGetWebTitle


The vtiGetWebTitle procedure returns the title of the current Web, which is set by the Web's author in the FrontPage Explorer.

Parameters

None

Return Value

The procedure returns the title of the current Web as a string. If there is no current Web or if the current Web is the RootWeb, the procedure returns an empty string. If no title has been set, the return value is the same as the Web's URL. As a result, one way to see if the Web title has not been uniquely set is to compare the value returned by the vtiGetWebURL procedure to the value returned by the vtiGetWebTitle procedure.

Usage

Visual C++:




CString vtiGetWebTitle();

Visual Basic:




vtiGetWebTitle as String

vtiGetWebURL


The vtiGetWebURL procedure returns the URL of the current Web as a full hypertext reference. This means the URL includes everything from the http:// to the subdirectory for the current Web. Because the URL is in complete form, you can insert it into pages to reference the base document in a Web.

Parameters

None

Return Value

The procedure returns the URL of the current Web. Examples: http://www.your_company.com, http://www.your_company.com:8080, and http://www.your_company.com/sampleweb.

Usage

Visual C++:




CString vtiGetWebURL();

Visual Basic:




vtiGetWebURL as String

vtiIsPageInWeb


You use the vtiIsPageInWeb procedure to see whether a document exists in the current Web. You should always use this procedure before adding documents to the current Web.

Parameters

URL: the name of the file you want to check, which is usually called the page URL. Values for this parameter can reference subdirectories. Valid subdirectories for most Webs include cgi-bin, images, and _private. Examples: newpage.htm, images\banner.gif.

Return Value

The procedure returns a value other than zero if the document is in the Web, and 0 if the document is not in the Web.

Usage

Visual C++:




BOOL vtiIsPageInWeb(LPCTSTR szURL);

Visual Basic:




vtiIsPageInWeb(URL as String) as Integer

vtiListWebs


This procedure returns a list of FrontPage webs on the specified server.

Parameters

Server: the URL to the server including the protocol, such as http://www.tvp.com, https://www.tvp.com, or file://MyWebs. You can include an optional port number if necessary.

User: the user name to place in the authorization dialog box. If this string is empty, the user has to enter both a user name and password. If you set a value for this parameter, the user can change the user name in the authorization dialog box.

Password: the password for the specified user.

Return Value

The procedure returns a list of FrontPage webs on the specified server. Items in the list are separated by the newline character \n such as "MyWeb\nTalkWeb\n".

Usage

Visual C++:




BSTR vtiListWebs(LPCTSTR pszServer, LPCTSTR pszUser, LPCTSTR pszPassword);

Visual Basic:




vtiListWebs (Server as String, User as String, Password as String) as String

vtiOpenWeb


The vtiOpenWeb procedure is used to open a Web on a specified server that does not have to be the current server. Before the FrontPage Explorer opens the Web, the user must enter an appropriate user name and password in the authorization dialog box.

Until the Web is open or an error occurs, the call blocks. Errors can occur if the user cannot validate their access to the server.

Parameters

ServerName: the host name or IP address of the Web server, which can include an optional port number. Examples: www.your_company.com, www.your_company.com:8080.

WebName: the name of the Web you want to access with no initial slash. Use an empty string if you want the user to access the RootWeb. Example: your_web.

User: the user name to place in the authorization dialog box. If this string is empty the user has to enter both a username and password. If you set a value for this parameter, the user can change the user name in the authorization dialog box.

Return Value

The procedure returns a value other than zero if the Web is open, and 0 if the Web is not open.

Usage

Visual C++:




BOOL vtiOpenWeb(LPCTSTR pszServer, LPCTSTR pszWebName, LPCTSTR pszUser);

Visual Basic:




vtiOpenWeb(Server as String, WebName as String, User as String) as Integer

vtiOpenWebWithPassword


While vtiOpenWebWithPassword is similar to vtiOpenWeb, this procedure allows you to specify a password as well as a user name. You will find that this procedure is useful for creating automated processes that manipulate secure webs.

Parameters

Server: the URL to the server including the protocol, such as http://www.tvp.com, https://www.tvp.com, or file://MyWebs. You can include an optional port number if necessary.

WebName: the name of the Web you want to access with no initial slash. Use an empty string if you want the user to access the RootWeb. Example: your_web.

User: the user name to place in the authorization dialog box. If this string is empty, the user has to enter both a user name and password. If you set a value for this parameter, the user can change the user name in the authorization dialog box.

Password: the password for the specified user.

Return Value

The procedure returns the value of 1 to indicate the web is opened successfully and the value of 0 to indicate failure.

Usage

Visual C++:




BOOL vtiOpenWebWithPassword (LPCTSTR pszServer, LPCTSTR pszWebName, 




¬LPCTSTR pszUser, LPCTSTR pszPassword);

Visual Basic:




vtiOpenWebWithPassword (Server as String, WebName as String, User as 




¬String, Password as String) as Integer

vtiPromptOpenWeb


The vtiPromptOpenWeb procedure tells the FrontPage Explorer to display the Open Web dialog box.

Parameters

None

Return Value

None

Usage

Visual C++:




void vtiPromptOpenWeb();

Visual Basic:




vtiPromptOpenWeb

vtiPublishWeb


The vtiPublishWeb procedure is used to publish webs. Using this procedure, you can publish the current web to a target server.

You can set a time-out for this command to ensure that control returns to the user. Here's the syntax in Visual Basic:




App.OleRequestPendingTimeout = 2500



App.OleRequestPendingMsgTxt = "Please be patient. Update in Progress."



vtiPublishWeb(ServerURL as String, WebName as String, Flags as Long, 



¬User as String, Password as String) as Long

Parameters

ServerUrl: the web to which you are publishing including the protocol, such as http://www.tvp.com, https://www.tvp.com, or file://MyWebs. You can include a port number if necessary.

WebName: the name of the Web you want to access with no initial slash. Use an empty string if you want the user to access the RootWeb. Example: NewWeb.

User: the user name to place in the authorization dialog box. If this string is empty, the user has to enter both a username and password. If you set a value for this parameter, the user can change the user name in the authorization dialog box.

Password: the password for the specified user.

Flags: sets options. A setting of 1 allows you to perform an incremental copy, meaning only pages that have changed are copied. A setting of 2 allows you to add the web to an existing web. A setting of 4 allows you to copy all subwebs of the Root Web. These flags can be combined using a logical OR syntax—like the syntax for UNIX chmod. For example, a setting of 6 allows to you copy all subwebs of the Root Web and add the web to an existing web.

Return Value

The procedure returns the value of 1 to indicate success and the value of 0 to indicate failure.

Usage

Visual C++:




long vtiPublishWeb(LPCTSTR pszServerUrl, LPCTSTR pszWebName, long dwFlags, 




¬LPCTSTR pszUser, LPCTSTR pszPassword)

Visual Basic:




vtiPublishWeb(ServerURL as String, WebName as String, Flags as Long, User




¬ as String, Password as String) as Long

vtiPutDocument


The vtiPutDocument procedure gets a single file from the user's file system and adds it to the current Web. Before updating the current Web, the FrontPage Explorer checks the authoring permissions of the user who opened the current Web. If the user has no authoring permissions, an error occurs. An error also occurs if there is no open Web.


TIP

To add several documents to the current Web, use the procedure vtiPutDocuments.


When a document is successfully added to the current Web, the server uses the FrontPage Server Extensions to expand any WebBots the page might contain. The server also regenerates documents linked to the uploaded document as necessary. The last thing the server does is refresh the explorer views to ensure they show a current representation of the Web.

Because the vtiPutDocument overwrites any existing document if there is a naming conflict, you should always check for an existing Web document with the same name before you use this procedure. Use the procedure vtiIsPageInWeb to perform this check.

Parameters

FileName: the full path to the document on the user's file system, which can be an ASCII text or binary file. Example: C:\FrontPage\newpage.htm.

URL: the name of the file after you add it to the Web, which is usually called the page URL. Values for this parameter can reference subdirectories. However, this procedure cannot create new directories. Valid subdirectories for most Webs include cgi-bin, images, and _private. Examples: newpage.htm, images\banner.gif.

BlockingRequest: Determines whether the procedure is blocking or non-blocking. Keep in mind that if this procedure is used as a non-blocking call, there is no way to determine when the request has completed. For this reason, you should normally set this parameter to True.

Return Value

The procedure returns the value of 1 to indicate success and the value of 0 to indicate failure.

Usage

Visual C++:




long vtiPutDocument(LPCTSTR szFileName, LPCTSTR szURL, BOOL bBlockingRequest);

Visual Basic:




vtiPutDocument(FileName as String, URL as String, BlockingRequest as Integer)



¬ as Long

vtiPutDocuments


The vtiPutDocuments procedure gets multiple files from the user's file system and adds them to the current Web. Before updating the current Web, the FrontPage Explorer checks the authoring permissions of the user who opened the current Web. If the user has no authoring permissions, an error occurs. An error also occurs if there is no open Web.

Unlike the vtiPutDocument procedure, this procedure does not enable you to accidentally overwrite files. If a naming conflict occurs, a dialog box is displayed that enables users to overwrite the existing document or preserve it.

The method turns off document dependency updating while documents are being added to the current Web, which saves time. When all documents are successfully added to the current Web, the method turns on document dependency updating so that the server can use the FrontPage Server Extensions to expand any WebBots the page might contain. The server also regenerates documents linked to the uploaded document as necessary. However, the method does not instruct the server to update the FrontPage Explorer views. For this reason, your wizard should call the vtiRefreshWebFromServer procedure soon after executing the vtiPutDocuments procedure.

Parameters

FileName: the full path to the document on the user's file system, which can be an ASCII text or binary file. Example: C:\FrontPage\newpage.htm.

FileList: a list of full paths to files on the user's file system, which can be ASCII text or binary. All file names in the list must be separated by the new line character. Example: C:\FrontPage\newpage.htm\nC:\FrontPage\banner.gif.


NOTE

If you are using Visual Basic, you might want to place App.Path and the file separator into a string before adding the name of a file in the current directory.


UrlList is a list of URLs for the files you are adding to the Web. This list must be in the exact order you used in the FileList parameter. Values for this parameter can reference subdirectories. However, this procedure cannot create new directories. Valid subdirectories for most Webs include cgi-bin, images, and _private. Example: newpage.htm\nimages\banner.gif.

Return Value

The procedure returns a value other than zero if the call succeeds, and 0 if the call does not succeed.

Usage

Visual C++:




BOOL vtiPutDocuments(LPCTSTR szFileList, LPCTSTR szUrlList);

Visual Basic:




vtiPutDocuments(FileList as String, UrlList as String) as Integer

vtiPutWebMetaInfo


The vtiPutWebMetaInfo procedure is used to set the list of meta-information variables associated with a Web. When you use this procedure, you force FrontPage to update all documents that use meta-information variables.


NOTE

Use the vtiGetWebMetaInfo procedure to retrieve a current list of meta-information variables.


Because this is a blocking procedure, it is expected to pass output back to the caller, which is usually the exit status of the wizard.


TIP

Before you use this procedure you should ensure that a Web is open in the FrontPage Explorer. You can do this by checking the string returned by the vtiGetWebURL procedure. If the string is empty, no Web is open in the FrontPage Explorer and you get an error if you try to use the vtiPutWebMetaInfo procedure.



Parameters

NameValuePairs: a string containing a list of the names of the meta information variables you are setting and their associated values. The colon character is used to separate variable names and values, and the new line character is used to separate name-value pairs. The server does not track the case of your variable names and stores the variables in all lowercase regardless of the original case. Examples: webmaster:william@tvp.com\nphone:555-1212 or "webmaster:william@tvp.com" & CHR$(10) & "phone:555-1212".


NOTE

In Visual C++, the newline character is backslash n (\n). In Visual Basic, the newline character is: CHR$(10).



Return Value

The procedure returns the value of 1 to indicate success and the value of 0 to indicate failure.

Usage

Visual C++:




long vtiPutWebMetaInfo(LPCTSTR szNameValuePairs);

Visual Basic:




vtiPutWebMetaInfo(NameValuePairs as String) as Long

vtiPutWebPageMetaInfo


The vtiPutWebPageMetaInfo procedure sets meta-information variables associated with a specific page. Because this is a blocking procedure, it is expected to pass output back to the caller, which is usually the exit status of the wizard.

Parameters

PageURL: the page in the current Web for which you want to set meta-information variables. Example: index.htm.

NameValuePairs: a string containing a list of the names of the meta information variables you are setting and their associated values. The colon character is used to separate variable names and values, and the new line character is used to separate name-value pairs. The server does not track the case of your variable names and stores the variables in all lower-case regardless of the original case. Examples: webmaster:william@tvp.com\nphone:555-1212 or "webmaster:william@tvp.com" & CHR$(10) & "phone:555-1212".


NOTE

In Visual C++, the newline character is backslash n (\n). In Visual Basic, the newline character is CHR$(10).



Return Value

The procedure returns the value of 1 to indicate success and the value of 0 to indicate failure.

Usage

Visual C++:




long vtiPutWebPageMetaInfo(LPCTSTR pszURL, LPCTSTR pszNameValuePairs);

Visual Basic:




vtiPutWebPageMetaInfo(PageURL as String, NameValuePairs as String) as Long

vtiQuit


The vtiQuit procedure is the same as choosing Exit from the FrontPage Explorer's File menu.

Parameters

None.

Return Value

None.

Usage

Visual C++:




void vtiQuit ();

Visual Basic:




vtiQuit

vtiRefreshWebFromServer


The vtiRefreshWebFromServer tells the FrontPage Explorer to refresh all its views of the current Web. The explorer does this by placing a call to the Server that checks for updates. If updates have been made, the explorer's views are refreshed to reflect the current information.

Because this is a blocking procedure, it is expected to pass output back to the caller, which is usually the exit status of the wizard. You will usually want to call the vtiRefreshWebFromServer after you upload documents using the vtiPutDocuments procedure.


TIP

Before you use this procedure, you should ensure that a Web is open in the FrontPage Explorer. You can do this by checking the string returned by the vtiGetWebURL procedure. If the string is empty, no Web is open in the FrontPage Explorer, and you get an error if you try to use the vtiRefreshWebFromServer procedure.



Parameters

None

Return Value

None

Usage

Visual C++:




void vtiRefreshWebFromServer();

Visual Basic:




vtiRefreshWebFromServer

vtiRemoveWeb


The vtiRemoveWeb procedure is used to remove a named Web from the current Web server. Before removing a Web, the FrontPage Explorer checks the permissions of the user who opened the current Web. If the user has no administrative permissions, an error occurs. An error also occurs if there is no open Web.


TIP

Before you use this procedure, you should ensure that a Web is open in the FrontPage Explorer. You can do this by checking the string returned by the vtiGetWebURL procedure. If the string is empty, no Web is open in the FrontPage Explorer and you get an error if you try to use the vtiRemoveWeb procedure.



Parameters

WebName: the name of the Web to remove. The Web name must match that of a valid Web on the current server and should not reference the RootWeb. Additionally, the Web name must begin with a forward slash. Examples: /myweb and /sampleweb.

Return Value

The procedure returns the value of 1 to indicate success and the value of 0 to indicate failure.

Usage

Visual C++:




long vtiRemoveWeb(LPCTSTR szWebName);

Visual Basic:




vtiRemoveWeb(WebName as String) as Long

vtiRemoveWebPages


The vtiRemoveWebPages procedure allows you to delete files from the current web.

Parameters

PageList: a list of files to remove from the current web. Items in the list are separated by the newline character \n, such as "home.htm\nimages\myPic.gif\n".

Return Value

The procedure returns the value of 1 to indicate success and the value of 0 to indicate failure.

Usage

Visual C++:




long vtiRemoveWebPages(LPCTSTR pszPageList)

Visual Basic:




vtiRemoveWebPages(PageList as String) as Long

vtiSetWebRecalcDependencies


The vtiSetWebRecalcDependencies procedure can be used to turn document dependency updating on or off in the current Web. The procedure does this by setting the value of the meta-information variable vti_AutoRecalc, which is a boolean value—a setting of 0 turns off dependency updating and a setting of 1 turns on dependency updating.

Although turning off document dependency is useful when you are adding or deleting many documents, you should note that while dependency updating is turned off, any uploaded documents are stored temporarily in the _vti_shm directory. This means they are not visible in FrontPage views or available to browsers. Further, any documents containing WebBots are not expanded into the source and HTML documents are needed to use the pages.

When you turn document dependency back on, the entire Web is updated and checked for dependencies. This means documents in the _vti_shm directory are moved to whatever directory they should be stored in and documents containing WebBots are expanded. Because this is a blocking procedure, it is expected to pass output back to the caller, which is usually the exit status of the wizard.

Parameters

RecalcOn: set to False to turn off document dependency updating and True to turn it back on.


NOTE

For some programming languages, you cannot use boolean values. In this case, the boolean values True and False can be expressed as integer values of 1 and 0 respectively.



Return Value

None

Usage

Visual C++:




void vtiSetWebRecalcDependencies(BOOL bRecalcOn);

Visual Basic:




vtiSetWebRecalcDependencies(RecalcOn as Integer)

Using ActiveX Control Automation With the Frontpage Editor


You will use the FrontPage Editor's OLE interface whenever you want to access pages using the FrontPage Editor. This section highlights these commands.

vtiBringPageToTop


The vtiBringPageToTop procedure tells the FrontPage Editor to make the specified page the active—top—page.

Parameters

URL: the absolute or relative URL of the page.

WebURL: the URL of the FrontPage web that contains the page. Set this parameter to an empty string if you use an absolute URL to the page.

Cookie: set to an empty string.

ToDoTaskId: set to 0.

Return Value

The procedure returns the value of 1 to indicate success and the value of 0 to indicate failure.

Usage

Visual C++:




long vtiBringPageToTop(LPCTSTR szURL,LPCTSTR szWebURL, 




¬LPCTSTR szCookie, long toDoTaskId);

Visual Basic:




vtiBringPageToTop(URL as String, WebURL as String, Cookie as 




¬String, toDoTaskId as Long) as Long

vtiBringToTop


The vtiBringToTop procedure brings the FrontPage Editor to the front of the display and makes it active.

Parameters

None

Return Value

None

Usage

Visual C++:




void vtiBringToTop();

Visual Basic:




vtiBringToTop

vtiGetBookmarkList


This procedure retrieves a list of internal bookmarks in the specified HTML page.

Parameters

PageUrl: the absolute or relative URL to the page you want to examine.

WebURL: the URL of the FrontPage web which contains the page you want to examine. Set this parameter to NULL if you use an absolute URL to the page. Examples:




vtiGetBookmarkList("http://www.tvp.com/idn/idnfp.htm", NULL);




vtiGetBookmarkList("idn/idnfp.htm", "http://www.tvp.com");

Return Value

The procedure returns a list of bookmarks in the specified page. Items in the list are separated by the newline character \n.

Usage

Visual C++:




CSTRING vtiGetBookmarkList(LPCTSTR szPageUrl, LPCTSTR szWebUrl);

Visual Basic:




vtiGetBookmarkList(PageUrl as String, WebUrl as String) as String

vtiGetTopPageUrl


The vtiGetTopPageUrl procedure returns the full URL of the active page in the FrontPage Editor. You can use the Return Value from this call in other Editor automation calls that take the pszPageUrl parameter.

Parameters

None.

Return Value

The complete URL to the active page in the FrontPage Editor.

Usage

Visual C++:




BSTR vtiGetTopPageUrl();

Visual Basic:




vtiGetTopPageUrl as String

vtiInsertHTML


The vtiInsertHTML procedure inserts HTML at the insertion point in the active page. Because this procedure is designed to be very simple, it only accepts a single parameter.

Parameters

HTML: a string containing the HTML to insert into the active page in the FrontPage Editor.

Return Value

The procedure returns a value of 1 if the insert was successful and a zero if the insert fails.

Usage

Visual C++:




long vtiInsertHTML(LPCTSTR pszHTML);

Visual Basic:




vtiInsertHTML(HTML as String) as Long

vtiInsertFile


The vtiInsertFile procedure inserts the specified file at the insertion point in the specified page. This is equivalent to the File command on the FrontPage Editor’s Insert menu. The FrontPage Editor handles the file based on the file extension and converts the file if necessary. The type of the file is inferred from the file extension.

Parameters

PageUrl: the absolute or relative URL to the page in which you want to insert the file.

WebURL: the URL of the FrontPage web that contains the page you are updating. Set this parameter to NULL if you use an absolute URL to the page.

File: the name of the file you are inserting into the page. This file must be on the local file system and is referenced with the standard file path, such as C:\MyDocs\Output\Update.txt.

Return Value

The procedure returns a value of 1 if the file was successfully inserted and 0 if the file does not exist.

Usage

Visual C++:




long vtiInsertFile(LPCTSTR pszPageUrl, LPCTSTR pszWebUrl, LPCTSTR pszFile);

Visual Basic:




vtiInsertFile(PageUrl as String, WebUrl as string, File as String) as Long

vtiInsertImage


The vtiInsertImage procedure inserts the specified mage at the insertion point in the specified page. This is equivalent to the Image command on the FrontPage Editor’s Insert menu. The FrontPage Editor handles the image based on the extension and converts the image if necessary and possible. The image type is inferred from the file extension.

Parameters


PageUrl: the absolute or relative URL to the page in which you want to insert the image.

WebURL: the URL of the FrontPage Web that contains the page you are updating. Set this parameter to NULL if you use an absolute URL to the page.

File: the name of the image file you are inserting into the page. The image file must be on the local file system and is referenced with the standard file path, such as C:\MyDocs\Images\CoolWave.bmp.

Return Value

The procedure returns a value of 1 if the file was successfully inserted and a zero if the file does not exist.

Usage

Visual C++:




long vtiInsertImage(LPCTSTR pszPageUrl, LPCTSTR pszWebUrl, LPCTSTR pszFile);

Visual Basic:




vtiInsertImage(PageUrl as String, WebUrl as String, File as String) as Long

vtiListOpenDocs


The vtiListOpenDocs procedure is used to get a list of all documents currently open in the FrontPage Editor.

Parameters

None.

Return Value

The procedure returns a list of absolute PageUrls for pages currently open in the FrontPage Editor. Items in the list are separated by the newline character \n such as "file:///D|/MyWebs/index.htm\nhttp://www.tvp.com/writing/index.htm\n".

Usage

Visual C++:




CSTRING vtiListOpenDocs();

Visual Basic:




vtiListOpenDocs as String

vtiNewWebPage


The vtiNewWebPage procedure tells the FrontPage Editor to create a new Web page.

Parameters

URL: the name the FrontPage Editor will use if the user saves the file into a Web. Values for this parameter can reference subdirectories.

WebURL: the URL of the Web to which the file should be saved as a full hypertext reference. This means the WebURL includes everything from the http:// to the subdirectory for the Web. You can use the FrontPage Explorer vtiGetWebURL procedure to set this parameter. Examples: http://www.your_company.com and http://www.your_company.com/sampweb.

WebTitle: the title of the web to which the file should be saved. You can use the FrontPage Explorer vtiGetWebTitle procedure to set this parameter. Example: Internet Resource Web.

Return Value

This procedure returns a pointer to the document. After you call this procedure, you should release the object to avoid problems that could arise if the user changes the environment.

Usage

Visual C++:




LPDISPATCH vtiNewWebPage(LPCTSTR szURL, LPCTSTR szWebURL, LPCTSTR szWebTitle);

Visual Basic:




vtiNewWebPage(URL as String, WebURL as String, WebTitle as String) as Object

vtiOpenWebPage


The vtiOpenWebPage procedure tells the FrontPage Editor to open a file on the user's file system.


NOTE

To open an existing page from the current Web or the Internet, use the FrontPage Explorer vtiEditWebPage procedure.



Parameters

FileName: the full path to the file on the user's file system. Example: C:\FrontPage\newpage.htm.

URL: the name the FrontPage Editor uses if the user saves the file into a Web. Values for this parameter can reference subdirectories.

WebURL: the URL of the Web the file should be saved to as a full hypertext reference. This means the WebURL includes everything from the http:// to the subdirectory for the Web. You can use the FrontPage Explorer vtiGetWebURL procedure to set this parameter. Examples: http://www.your_company.com and http://www.your_company.com/sampweb.

WebTitle: the title of the Web to which the file should be saved. You can use the FrontPage Explorer vtiGetWebTitle procedure to set this parameter. Example: Internet Resource Web.

Return Value

This procedure returns a pointer to the document. After you call this procedure, you should release the object to avoid problems that could arise if the user changes the environment.

Usage

Visual C++:




LPDISPATCH vtiOpenWebPage(LPCTSTR szFileName, LPCTSTR szURL,



¬LPCTSTR szWebURL, LPCTSTR szWebTitle);

Visual Basic:




vtiOpenWebPage(FileName as String, URL as String, WebURL as String,



¬WebTitle as String) as Object

vtiPaste


The vtiPaste procedure pastes the contents of the Windows clipboard into the active page. This procedure is the same as the Paste command in the FrontPage Editor's Edit menu.

Parameters

None.

Return Value

None.

Usage

Visual C++:




void vtiPaste();

Visual Basic:




vtiPaste

vtiQueryWebPage


The vtiQueryWebPage procedure checks to see if a page is currently being edited in the FrontPage Editor.

Parameters

URL: the name of the file you are querying about. Values for this parameter can reference subdirectories. Examples: newpage.htm, _private\header.htm.

WebURL: the URL of the Web the file came from, which is set as a full hypertext reference. This means the returned string includes everything from the http:// to the subdirectory for the Web. You can use the FrontPage Explorer vtiGetWebURL procedure to set this parameter. Examples: http://www.your_company.com and http://www.your_company.com/sampweb.

Return Value

The procedure returns the value of 1 to indicate success and the value of 0 to indicate failure.

Usage

Visual C++:




long vtiQueryWebPage(LPCTSTR szURL, LPCTSTR szWebURL);

Visual Basic:




vtiQueryWebPage(URL as String, WebURL as String) as Long

vtiQuit


The vtiQuit procedure is the same as choosing Exit from the FrontPage Editor's File menu.

Parameters

None.

Return Value

None.

Usage

Visual C++:




void vtiQuit();

Visual Basic:




vtiQuit

vtiRefreshDocument


The vtiRefreshDocument procedure refreshes a page by reloading it into the FrontPage Editor. Be careful with this procedure; the page is loaded in its original state, which means that any unsaved changes are overwritten.

Parameters

PageUrl: the absolute or relative URL to the page you want to refresh.

WebURL: the URL of the FrontPage web that contains the page you want to refresh. Set this parameter to NULL if you use an absolute URL to the page. Examples:




vtiRefreshDocument("http://www.tvp.com/idn/idnfp.htm", NULL);




vtiRefreshDocument("idn/idnfp.htm", "http://www.tvp.com");

Return Value

None.

Usage

Visual C++:




void vtiRefreshDocument(LPCTSTR szPageUrl, LPCTSTR szWebUrl);

Visual Basic:




vtiRefreshDocument (PageUrl as String, WebUrl as String)

vtiScrollToBookmark


The vtiScrollToBookmark procedure scrolls the FrontPage Editor's display window to the specified bookmark.

Parameters

PageUrl: the absolute or relative URL to the page you want to examine.

WebURL: the URL of the FrontPage Web that contains the page you want to examine. Set this parameter to NULL if you use an absolute URL to the page.

Bookmark: the name of the bookmark to which you want to scroll.

Return Value

The procedure returns a value of 1 if the bookmark was found and was scrolled to. If the procedure fails to find the specified bookmark, a value of 0 is returned.

Usage

Visual C++:




long vtiScrollToBookmark(LPCTSTR pszPageUrl, LPCTSTR pszWebUrl, 




¬LPCTSTR pszBookmark);

Visual Basic:




vtiScrollToBookmark(PageUrl as String, WebUrl as String, 




¬Bookmark as String) as Long

Using ActiveX Control Automation With the Frontpage To Do List


The FrontPage To Do List also has an OLE interface. You will use this interface to access and update task lists. This section highlights the commands used in the interface.

vtiAddTask


The vtiAddTask procedure is used to add new tasks to the To Do List. Each task you assign must reference a particular document and have a name and priority.

Parameters

TaskName: The name of the task to be performed, which can be a word or phrase. Examples: Task 01, Banner Creation Reminder, and Pages Needs Image.

Priority: The priority of the task, entered as an integer value from 1-3, where 1 is for high priority tasks, 2 is for medium priority tasks, and 3 is for low priority tasks. Example: 1.

CreatedBy: The name of the person or template that created the task. Example: Internet Resource Wizard.

URL: The page or file to which the task refers. Values for this parameter can reference subdirectories. Valid subdirectories for most Webs include cgi-bin, images, and _private. Examples: newpage.htm, images\banner.gif.

Cookie: An additional identifier. Although this parameter is usually used for a specific bookmark within the referenced page, it can be used for other purposes if necessary. Example: "#bookmark".

Comment: A description of the task to be performed, which is usually 1-2 sentences in length. Example: Insert a banner that is appropriate for your Web.

Return Value

The procedure returns a value other than zero if the call succeeds, and 0 if the call does not succeed.

Usage

Visual C++:




BOOL vtiAddTask(LPCTSTR TaskName, short Priority, LPCTSTR CreatedBy,



¬LPCTSTR URL, LPCTSTR Cookie, LPCTSTR Comment);

Visual Basic:




vtiAddTask(TaskName as String, Priority as Integer, CreatedBy as String,



¬URL as String, Cookie as String, Comment as String) as Integer

vtiAddTaskAskUser


Like the vtiAddTask procedure, the vtiAddTaskAskUser is used to add tasks to the To Do List. Unlike vtiAddTask procedure, this procedure enables the user to assign the task to a different user.

Parameters

TaskName: The name of the task to be performed, which can be a word or phrase. Examples: Task 01, Banner Creation Reminder, and Pages Needs Image.

Priority: The priority of the task, entered as an integer value from 1-3 where 1 is for high priority tasks, 2 is for medium priority tasks, and 3 is for low priority tasks. Example: 1.

CreatedBy: The name of the person or template that created the task. Example: Internet Resource Wizard.

URL: The page or file to which the task refers. Values for this parameter can reference subdirectories. Valid subdirectories for most Webs include cgi-bin, images, and _private. Examples: newpage.htm, images\banner.gif.

Cookie: An additional identifier. Although this parameter is usually used for a specific bookmark within the referenced page, it can be used for other purposes if necessary. Example: #bookmark.

Comment: A description of the task to be performed, which is usually 1-2 sentences in length. Example: Insert a banner that is appropriate for your Web.

Return Value

The procedure returns a value other than zero if the call succeeds, and 0 if the call does not succeed.

Usage

Visual C++:




BOOL vtiAddTaskAskUser(LPCTSTR TaskName, short Priority, LPCTSTR CreatedBy,



LPCTSTR URL, LPCTSTR Cookie, LPCTSTR Comment);

Visual Basic:




vtiAddTaskAskUser(TaskName as String, Priority as Integer,



CreatedBy as String, URL as String, Cookie as String, Comment as String) as Integer

vtiCompletedTaskByUrl


The vtiCompletedTaskByUrl procedure is used to remove accomplished tasks from the To Do List. This is done by marking the first task that matches a specified URL and Cookie as completed, then removing it from the list of active tasks.

Parameters

URL: The page or file the accomplished task relates to, which is expressed using a relative path. Values for this parameter can reference subdirectories. Valid subdirectories for most Webs include cgi-bin, images, and _private. Examples: newpage.htm, images\banner.gif.

Cookie: An additional identifier set to remove only a task related to a specific bookmark within the referenced page. Example: #bookmark.

Return Value

The procedure returns a value other than zero if the call succeeds, and 0 if the call does not succeed.

Usage

Visual C++:




BOOL vtiCompletedTaskByUrl(LPCTSTR url, LPCTSTR cookie);

Visual Basic:




vtiCompletedTaskByUrl(URL as String, Cookie as String) as Integer

vtiGetActiveCount


The vtiGetActiveCount procedure obtains the number of tasks currently in the To Do List.

Parameters

None

Return Value

The procedure returns the number of active tasks.

Usage

Visual C++:




long vtiGetActiveCount();

Visual Basic:




vtiGetActiveCount as Long

vtiHide


The vtiHide procedure closes the To Do List dialog box.

Parameters

None

Return Value

None

Usage

Visual C++:




void vtiHide();

Visual Basic:




vtiHide

vtiShow


The vtiShow procedure displays the To Do List dialog box.

Parameters

None

Return Value

None

Usage

Visual C++:




void vtiShow();

Visual Basic:




vtiShow

vtiWorkedOnTaskByUrl


The vtiWorkedOnTaskByUrl procedure specifies that the current user has worked on a task but has not completed it.

Parameters

URL: The page or file to which the task relates, which is expressed using a relative path. Values for this parameter can reference subdirectories. Valid subdirectories for most Webs include cgi-bin, images, and _private. Examples: newpage.htm, images\banner.gif.

Cookie: An additional identifier set to reference a specific bookmark within the page. Example: #bookmark.

Return Value

The procedure returns a value other than zero if the call succeeds, and 0 if the call does not succeed.

Usage

Visual C++:




BOOL vtiWorkedOnTaskByUrl(LPCTSTR url, LPCTSTR cookie);

Visual Basic:




vtiWorkedOnTaskByUrl(URL as String, Cookie as String) as Integer

Previous Page Page Top TOC Next Page