AddFavorite method

Artikel
05/02/2017

Prompts the user with a dialog box to add the specified URL to the Favorites list.

This method is not supported for Windows apps using JavaScript.

Syntax

HRESULT retVal = object.AddFavorite(URL, Title);

Parameters

URL [in]
Type: BSTR

A BSTR that specifies the URL of the favorite to add to the Favorites list.
Title [in, optional]
Type: VARIANT

A pointer to a VARIANT of type VT_BSTR that specifies the suggested title to use in the Favorites list. The user can change the title in the Add Favorite dialog box. If Title is not specified, URL is used as the title of the favorite.

Return value

Type: HRESULT

If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

Standards information

There are no standards that apply here.

Remarks

Calling the IShellUIHelper::AddFavorite method prompts the user with the same dialog box that is displayed when the user selects Add to Favorites from the Favorites menu.

The URL parameter must specify a valid URL using HTTP, Secure Hypertext Transfer Protocol (HTTPS), or File Transfer Protocol (FTP) protocols only. Calling the IShellUIHelper::AddFavorite method with a file:// or javascript: URL returns E_ACCESSDENIED.

Because the Title parameter is used as a file name when storing the favorite, it cannot contain characters that have been reserved by the file system. If present, the following characters are removed from Title before the Add a Favorite dialog box appears.

backslash (\)
apostrophe (*)
question mark (?)
double quotation mark (")
less than sign (<)
greater than sign (>)
pipe (|)

Additionally, slash marks (/) in Title are converted to hyphens (-), and leading and trailing spaces are trimmed. If no suitable characters are found in Title, the URL of the favorite is used instead.

If the favorites are stored on a drive that does not support long file names, only one dot (.) is allowed. Additionally, the title is trimmed to 8.3 and spaces are converted to hyphens.

This method is not supported in HTML Applications (HTAs).

Windows Internet Explorer 8 and later. For security reasons, the IShellUIHelper::AddFavorite method must be called as a response to a user-initiated action, such a mouse click. If called from a different context, such as the onload event of the body element, the IShellUIHelper::AddFavorite method fails silently.

Freigeben über