Internet Shortcut Global Functions

Internet Shortcut Global Functions Overview

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

InetIsOffline

BOOL InetIsOffline (
 DWORD dwFlags
);

This function determines whether or not the system is connected to the Internet

The function returns TRUE if the local system in not currently connected to the Internet. The function returns FALSE if the local system is connected to the Internet or if no attempt has yet been made to connect 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
);

This function invokes the unregistered MIME content type dialog box.

The function returns S_OK if the content type was successfully associated with the extension. In this case, the extension is associated as the default for the content type and pcszAppBuf points to the string that contains the path of the specified application. The function returns S_FALSE if nothing was registered. Otherwise, the return value will be one of the following.

Value	Meaning
E_ABORT	The user canceled the operation.
E_FLAGS	The flag combination passed in dwFlags is invalid.
E_OUTOFMEMORY	There was insufficient memory available to complete the operation.
E_POINTER	One of the input pointers is invalid.

hwndParent

The handle to the parent window of any posted child windows.

dwInFlags

Bit flag value that specifies the 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 will be registered as the handler for the given MIME type. If this bit is clear, no association will be registered.

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

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

pcszFile

Pointer to 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

Pointer to a null-terminated string that contains the unregistered content type.

pszAppBuf

Pointer to a buffer that will receive the path of the application specified by the user.

ucAppBufLen

The size of pcszAppBuf, 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
);

This function applies common translations to a given URL string, creating a new URL string.

The function returns S_OK upon success, and S_FALSE if the URL did not require translation. If an error occurs, the function returns a value that will be one of the following.

Value Meaning
E_FLAGS The flag combination passed in dwFlags is invalid.
E_OUTOFMEMORY There was insufficient memory to complete the operation.
E_POINTER One of the input pointers was invalid.

pcszURL

Pointer to 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 will automatically choose a scheme and add it to the URL.
TRANSLATEURL_FL_USE_DEFAULT_PROTOCOL: If the protocol scheme is not specified in the pcszURL parameter to TranslateURL, the system will add the default protocol to the URL.

ppszTranslatedURL

Pointer variable that will receive the pointer to the newly created, translated URL string, if any. *ppszTranslatedURL 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
);

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

This function returns S_OK if the application is registered with the URL protocol. The function returns S_FALSE if nothing is registered. For example, the function returns S_FALSE when the user elects to perform a one-time execution via the selected application.

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.

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

pcszFile

Pointer to a const zero-terminated string that contains the file name to associate with the URL's protocol.

pcszURL

Pointer to a const zero-terminated string that contains the URL with an unknown protocol.

pszAppBuf

Pointer to a buffer that will receive the path of the application specified by the user.

ucAppBufLen

The size of pcszAppBuf, in characters.