Internet Shortcuts API Reference

Internet Shortcuts API Reference


This topic explains the Internet Shortcuts API for managing "shortcuts" to URL locations.

arrowy.gifIUniformResourceLocator Interface

arrowy.gifInternet Shortcut Global Functions

arrowy.gifInternet Shortcut Enumerated Types

arrowy.gifInternet Shortcut Structures

IUniformResourceLocator Interface

This section provides information about the following IUniformResourceLocator interface methods:

IUniformResourceLocator::GetURL

HRESULT GetURL(
    LPSTR *ppszURL
);

Retrieves an object's uniform resource locator (URL).

ppszURL
Address of an LPSTR that will be filled in with a pointer to the object's URL. Because this method allocates memory for the string, you must instantiate an IMalloc interface and free the memory using IMalloc::Free when it is no longer needed. The following code fragment provides an example of how this can be done.
//  START CODE FRAGMENT
{
    // In this example, pURL is a global IUniformResourceLocator pointer.
    LPSTR lpTemp;

    hres = pURL->GetURL(&lpTemp); 
    if (SUCCEEDED(hres)){
        IMalloc* pMalloc;
        hres = SHGetMalloc(&pMalloc); 
        if (SUCCEEDED(hres)){
            pMalloc->Free(lpTemp);
            pMalloc->Release();
        }
    }
}
//  END CODE FRAGMENT

IUniformResourceLocator::InvokeCommand

HRESULT InvokeCommand(
    PURLINVOKECOMMANDINFO pURLCommandInfo;
);

Runs a command on an object's URL.

pURLCommandInfo
Address of a URLINVOKECOMMANDINFO structure that contains command information for the function.

IUniformResourceLocator::SetURL

HRESULT SetURL(
    LPCSTR pcszURL,
    DWORD dwInFlags
);

Sets an object's URL.

pcszURL
Address of a zero-terminated string that contains the URL to set. The protocol scheme may be included as part of the URL.
dwInFlags
Flag value that specifies the behavior for setting the protocol scheme. This field can contain one of the following values:
IURL_SETURL_FL_GUESS_PROTOCOL If the protocol scheme is not specified in pcszURL, the system automatically chooses a scheme and adds it to the URL.
IURL_SETURL_FL_USE_DEFAULT_PROTOCOL If the protocol scheme is not specified in pcszURL, the system adds the default protocol scheme to the URL.

Internet Shortcut Global Functions

This section contains information about the following Internet Shortcut global functions:

InetIsOffline

BOOL InetIsOffline (
    DWORD dwFlags
);

Determines whether the system is connected to the Internet.

dwFlags
Input flags for the function. This must be set to zero.

MIMEAssociationDialog

HRESULT WINAPI MIMEAssociationDialog (
    HWND    hwndParent,
    DWORD   dwInFlags,
    LPCSTR  pcszFile,
    LPCSTR  pcszMIMEContentType,
    LPSTR   pszAppBuf,
    UINT    ucAppBufLen
);

Runs the unregistered MIME content type dialog box.

hwndParent
Handle to the parent window of any posted child windows.
dwInFlags
Bit flag value that specifies if an association is to be registered. The bit flag is the value MIMEASSOCDLG_FL_REGISTER_ASSOC (0x0001). If this bit is set, the selected application is registered as the handler for the given MIME type. If this bit is clear, no association is registered.

An application is registered only if this flag is set and the user indicates that a persistent association is to be made.

Registration is impossible if the string at pcszFile does not contain an extension.

pcszFile
Address of a null-terminated string that contains the name of the target file. This file must conform to the content type described by the pcszMIMEContentType parameter.
pcszMIMEContentType
Address of a null-terminated string that contains the unregistered content type.
pszAppBuf
Address of a buffer that receives the path of the application specified by the user.
ucAppBufLen
Size of pszAppBuf, in characters.

Note This function does not validate the syntax of the input content type string at pcszMIMEContentType. A successful return value does not indicate that the specified MIME content type is valid.

TranslateURL

HRESULT WINAPI TranslateURL(
    LPCSTR pcszURL,
    DWORD dwInFlags,
    LPSTR *ppszTranslatedURL
);

Applies common translations to a given URL string, creating a new URL string.

pcszURL
Address of the URL string to be translated.
dwInFlags
Bit flags that specify how the URL string is to be translated. This value can be a combination of the following:
TRANSLATEURL_FL_GUESS_PROTOCOL If the protocol scheme is not specified in the pcszURL parameter to TranslateURL, the system automatically chooses a scheme and adds it to the URL.
TRANSLATEURL_FL_USE_DEFAULT_PROTOCOL If the protocol scheme is not specified in the pcszURL parameter to TranslateURL, the system adds the default protocol to the URL.
ppszTranslatedURL
Pointer variable that receives the pointer to the newly created, translated URL string, if any. The *ppszTranslatedURL parameter is valid only if the function returns S_OK.

This function does not validate the input URL string. A successful return value does not indicate that the URL strings are valid URLs.

URLAssociationDialog

HRESULT WINAPI URLAssociationDialog(
    HWND hwndParent,
    DWORD dwInFlags,
    LPCSTR pcszFile,
    LPCSTR pcszURL,
    LPSTR pszAppBuf,
    UINT ucAppBufLen
);

Invokes the unregistered URL protocol dialog box. This dialog box allows the user to select an application to associate with a previously unknown protocol.

hwndParent
Handle to the parent window.
dwInFlags
Bit flags that specify the behavior of the function. This value can be a combination of the following:
URLASSOCDLG_FL_USE_DEFAULT_NAME Use the default file name (that is, "Internet Shortcut").
URLASSOCDLG_FL_REGISTER_ASSOC Register the selected application as the handler for the protocol specified in pcszURL. The application is registered only if this flag is set and the user indicates that a persistent association is desired.
pcszFile
Address of a constant zero-terminated string that contains the file name to associate with the URL's protocol.
pcszURL
Address of a constant zero-terminated string that contains the URL with an unknown protocol.
pszAppBuf
Address of a buffer that receives the path of the application specified by the user.
ucAppBufLen
The size of pszAppBuf, in characters.

Internet Shortcut Enumerated Types

This section contains information on the following Internet Shortcut enumerated types:

IURL_SETURL_FLAGS

typedef enum iurl_seturl_flags{
    IURL_SETURL_FL_GUESS_PROTOCOL         = 0x0001,
    IURL_SETURL_FL_USE_DEFAULT_PROTOCOL   = 0x0002
}  IURL_SETURL_FLAGS;

The following enumerated values are used with the IUniformResourceLocator::SetURL method. They are passed in as the dwInFlags parameter.

IURL_SETURL_FL_GUESS_PROTOCOL
If the protocol scheme is not specified in the pcszURL parameter to IUniformResourceLocator::SetURL, the system automatically chooses a scheme and adds it to the URL.
IURL_SETURL_FL_USE_DEFAULT_PROTOCOL
If the protocol scheme is not specified in the pcszURL parameter to IUniformResourceLocator::SetURL, the system adds the default protocol to the URL.

IURL_SETURL_INVOKECOMMAND_FLAGS

typedef enum iurl_invokecommand_flags{
    IURL_INVOKECOMMAND_FL_ALLOW_UI           = 0x0001,
    IURL_INVOKECOMMAND_FL_USE_DEFAULT_VERB   = 0x0002,
}  IURL_INVOKECOMMAND_FLAGS;

The following enumerated values are used in the dwFlags member of the URLINVOKECOMMANDINFO structure.

IURL_INVOKECOMMAND_FL_ALLOW_UI
If this bit is set, interaction with the user is allowed and the hwndParent member of the URLINVOKECOMMANDINFO structure is valid. If this bit is clear, interaction with the user is not allowed and the hwndParent member is ignored.
IURL_INVOKECOMMAND_FL_USE_DEFAULT_VERB
If this bit is set, the default verb for the Internet Shortcut's protocol is to be used and the pcszVerb member of the URLINVOKECOMMANDINFO structure is ignored. If this bit is clear, the verb is specified by pcszVerb.

MIMEASSOCIATIONDIALOG_IN_FLAGS

typedef enum mimeassociationdialog_in_flags{
    MIMEASSOCDLG_FL_REGISTER_ASSOC     = 0x0001
} MIMEASSOCIATIONDIALOG_IN_FLAGS;

The following enumerated value is used with the MIMEAssociationDialog function to determine how it executes.

MIMEASSOCDLG_FL_REGISTER_ASSOC
If this bit is set, the selected application is registered as the handler for the given MIME type. If this bit is clear, no association is registered.

An application is registered only if this flag is set and the user indicates that a persistent association is to be made.

TRANSLATEURL_IN_FLAGS

typedef enum translateurl_in_flags {
    TRANSLATEURL_FL_GUESS_PROTOCOL         = 0x0001,
    TRANSLATEURL_FL_USE_DEFAULT_PROTOCOL   = 0x0002,
} TRANSLATEURL_IN_FLAGS;

The following enumerated values are used with the TranslateURL function to determine how it will execute.

TRANSLATEURL_FL_GUESS_PROTOCOL
If the protocol scheme is not specified in the pcszURL parameter to TranslateURL, the system automatically chooses a scheme and adds it to the URL.
TRANSLATEURL_FL_USE_DEFAULT_PROTOCOL
If the protocol scheme is not specified in the pcszURL parameter to TranslateURL, the system adds the default protocol to the URL.

URLASSOCIATIONDIALOG_IN_FLAGS

typedef enum urlassociationdialog_in_flags {
    URLASSOCDLG_FL_USE_DEFAULT_NAME  = 0x0001,
    URLASSOCDLG_FL_REGISTER_ASSOC    = 0x0002
} URLASSOCIATIONDIALOG_IN_FLAGS;

The following enumerated values are used with the URLAssociationDialog function to determine how it executes.

URLASSOCDLG_FL_USE_DEFAULT_NAME
Use the default file name (that is, "Internet Shortcut").
URLASSOCDLG_FL_REGISTER_ASSOC
Register the selected application as the handler for the protocol specified in the pcszURL parameter of URLAssociationDialog. The application is registered only if this flag is set and the user indicates that a persistent association is desired.

Internet Shortcut Structures

This section provides information about the following Internet Shortcut structure:

URLINVOKECOMMANDINFO

typedef struct  {
    DWORD    dwcbSize;
    DWORD    dwFlags;
    HWND     hwndParent;
    LPCSTR  pcszVerb;
} URLINVOKECOMMANDINFO, *PURLINVOKECOMMANDINFO;

Contains information for use with the IUniformResourceLocator::InvokeCommand method.

dwcbSize
Size of this structure, in bytes.
dwFlags
Flag value that specifies how the IUniformResourceLocator::InvokeCommand method will execute. This value can be a combination of the following:
IURL_INVOKECOMMAND_FL_ALLOW_UI
Interaction with the user is allowed and the hwndParent member of this structure is valid. If this is not set, interaction with the user is not allowed and the hwndParent member is ignored.
IURL_INVOKECOMMAND_FL_USE_DEFAULT_VERB
Default verb for the Internet Shortcut's protocol is to be used and the pcszVerb member is ignored. If this bit is not set, the verb is specified by pcszVerb.
hwndParent
Handle to the parent window. If dwFlags is set to IURL_INVOKECOMMAND_FL_USE_DEFAULT_VERB, this member is ignored.
pcszVerb
Address of a zero-terminated string that contains the verb to be invoked by IUniformResourceLocator::InvokeCommand. If dwFlags is set to IURL_INVOKECOMMAND_FL_USE_DEFAULT_VERB, this member is ignored.

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