|
|
/*
* intshcut.h - Internet Shortcut interface definitions. * * Copyright (c) Microsoft Corporation. All rights reserved. */
#ifndef __INTSHCUT_H__
#define __INTSHCUT_H__
/* Headers
**********/
#include <isguids.h>
#ifdef __cplusplus
extern "C" { /* Assume C declarations for C++. */#endif /* __cplusplus */
/* Constants
************/
/* Define API decoration for direct import of DLL functions. */
#ifdef _INTSHCUT_
#define INTSHCUTAPI
#else
#define INTSHCUTAPI DECLSPEC_IMPORT
#endif
/* HRESULTs */
//
// MessageId: E_FLAGS
//
// MessageText:
//
// The flag combination is invalid.
//
#define E_FLAGS MAKE_SCODE(SEVERITY_ERROR, FACILITY_ITF, 0x1000)
//
// MessageId: IS_E_EXEC_FAILED
//
// MessageText:
//
// The URL's protocol handler failed to run.
//
#define IS_E_EXEC_FAILED MAKE_SCODE(SEVERITY_ERROR, FACILITY_ITF, 0x2002)
//
// MessageId: URL_E_INVALID_SYNTAX
//
// MessageText:
//
// The URL's syntax is invalid.
//
#define URL_E_INVALID_SYNTAX MAKE_SCODE(SEVERITY_ERROR, FACILITY_ITF, 0x1001)
//
// MessageId: URL_E_UNREGISTERED_PROTOCOL
//
// MessageText:
//
// The URL's protocol does not have a registered protocol handler.
//
#define URL_E_UNREGISTERED_PROTOCOL MAKE_SCODE(SEVERITY_ERROR, FACILITY_ITF, 0x1002)
/* Interfaces
*************/
//
// Input flags for IUniformResourceLocator::SetURL().
//
typedef enum iurl_seturl_flags{ IURL_SETURL_FL_GUESS_PROTOCOL = 0x0001, // Guess protocol if missing
IURL_SETURL_FL_USE_DEFAULT_PROTOCOL = 0x0002, // Use default protocol if missing
}IURL_SETURL_FLAGS;
//
// Input flags for IUniformResourceLocator()::InvokeCommand().
//
typedef enum iurl_invokecommand_flags{ IURL_INVOKECOMMAND_FL_ALLOW_UI = 0x0001, IURL_INVOKECOMMAND_FL_USE_DEFAULT_VERB = 0x0002, // Ignore pcszVerb
IURL_INVOKECOMMAND_FL_DDEWAIT = 0x0004, // pass DDEWAIT to ShellExec
}IURL_INVOKECOMMAND_FLAGS;
//
// Command info for IUniformResourceLocator::InvokeCommand().
//
typedef struct urlinvokecommandinfoA{ DWORD dwcbSize; // Size of structure
DWORD dwFlags; // Bit field of IURL_INVOKECOMMAND_FLAGS
HWND hwndParent; // Parent window. Valid only if IURL_INVOKECOMMAND_FL_ALLOW_UI is set.
LPCSTR pcszVerb; // Verb to invoke. Ignored if IURL_INVOKECOMMAND_FL_USE_DEFAULT_VERB is set.
}URLINVOKECOMMANDINFOA;typedef URLINVOKECOMMANDINFOA *PURLINVOKECOMMANDINFOA;typedef const URLINVOKECOMMANDINFOA CURLINVOKECOMMANDINFOA;typedef const URLINVOKECOMMANDINFOA *PCURLINVOKECOMMANDINFOA;
typedef struct urlinvokecommandinfoW{ DWORD dwcbSize; // Size of structure
DWORD dwFlags; // Bit field of IURL_INVOKECOMMAND_FLAGS
HWND hwndParent; // Parent window. Valid only if IURL_INVOKECOMMAND_FL_ALLOW_UI is set.
LPCWSTR pcszVerb; // Verb to invoke. Ignored if IURL_INVOKECOMMAND_FL_USE_DEFAULT_VERB is set.
}URLINVOKECOMMANDINFOW;typedef URLINVOKECOMMANDINFOW *PURLINVOKECOMMANDINFOW;typedef const URLINVOKECOMMANDINFOW CURLINVOKECOMMANDINFOW;typedef const URLINVOKECOMMANDINFOW *PCURLINVOKECOMMANDINFOW;
#ifdef UNICODE
#define URLINVOKECOMMANDINFO URLINVOKECOMMANDINFOW
#define PURLINVOKECOMMANDINFO PURLINVOKECOMMANDINFOW
#define CURLINVOKECOMMANDINFO CURLINVOKECOMMANDINFOW
#define PCURLINVOKECOMMANDINFO PCURLINVOKECOMMANDINFOW
#else
#define URLINVOKECOMMANDINFO URLINVOKECOMMANDINFOA
#define PURLINVOKECOMMANDINFO PURLINVOKECOMMANDINFOA
#define CURLINVOKECOMMANDINFO CURLINVOKECOMMANDINFOA
#define PCURLINVOKECOMMANDINFO PCURLINVOKECOMMANDINFOA
#endif
//===========================================================================
//
// IUniformResourceLocator interface
//
// [OverView]
//
// Provides access to Internet Shortcuts.
//
// [Member functions]
//
// IUniformResourceLocator::SetURL
//
// This member function sets an object's URL.
//
// The dwInFlags parameter specifies the behavior:
//
// IURL_SETURL_FL_GUESS_PROTOCOL: The protocol scheme is guessed and added
// to the URL, if it is not specified in pcszURL.
//
// IURL_SETURL_FL_USE_DEFAULT_PROTOCOL: The default protocol scheme is added
// to the URL, if it is not specified in pcszURL.
//
// The function returns S_OK if the object's URL is set successfully.
// Otherwise, an error code is returned:
//
// E_OUTOFMEMORY: There is not enough memory to complete the operation.
//
// IS_E_EXEC_FAILED: The URL's protocol handler failed to run.
//
// URL_E_INVALID_SYNTAX: The URL's syntax is invalid.
//
// URL_E_UNREGISTERED_PROTOCOL: The URL's protocol does not have a
// registered protocol handler.
//
//
// IUniformResourceLocator::GetURL
//
// This member function retrieves an object's URL. The ppszURL is a
// pointer to a PSTR to be filled in which a pointer to the object's
// URL. When finished, this string should be freed using IMalloc::Free().
//
// The function returns S_OK if the object's URL was retrieved
// successfully. If the object does not have a URL associated with it,
// then S_FALSE is returned and *ppszURL is set to NULL. Otherwise, an
// error code is returned:
//
// E_OUTOFMEMORY: There is not enough memory to complete the operation.
//
// IS_E_EXEC_FAILED: The URL's protocol handler failed to run.
//
// URL_E_INVALID_SYNTAX: The URL's syntax is invalid.
//
// URL_E_UNREGISTERED_PROTOCOL: The URL's protocol does not have a
// registered protocol handler.
//
//
// IUniformResourceLocator::InvokeCommand
//
// This member function invokes a command on an object's URL. The purlici
// parameter is a pointer to a URLINVOKECOMMANDINFO structure which
// describes the command to be invoked.
//
// The function returns S_OK if the object's URL was opened successfully.
// If the object does not have a URL associated with it, the function
// returns S_FALSE. Otherwise, an error code is returned:
//
// E_OUTOFMEMORY: There is not enough memory to complete the operation.
//
// IS_E_EXEC_FAILED: The URL's protocol handler failed to run.
//
// URL_E_INVALID_SYNTAX: The URL's syntax is invalid.
//
// URL_E_UNREGISTERED_PROTOCOL: The URL's protocol does not have a
// registered protocol handler.
//
//===========================================================================
#undef INTERFACE
#define INTERFACE IUniformResourceLocatorA
DECLARE_INTERFACE_(IUniformResourceLocatorA, IUnknown){ /* IUnknown methods */
STDMETHOD(QueryInterface)(THIS_ REFIID riid, PVOID *ppvObject) PURE; STDMETHOD_(ULONG, AddRef)(THIS) PURE; STDMETHOD_(ULONG, Release)(THIS) PURE;
/* IUniformResourceLocator methods */
STDMETHOD(SetURL)(THIS_ LPCSTR pcszURL, DWORD dwInFlags) PURE;
STDMETHOD(GetURL)(THIS_ LPSTR *ppszURL) PURE;
STDMETHOD(InvokeCommand)(THIS_ PURLINVOKECOMMANDINFOA purlici) PURE;};
#undef INTERFACE
#define INTERFACE IUniformResourceLocatorW
DECLARE_INTERFACE_(IUniformResourceLocatorW, IUnknown){ /* IUnknown methods */
STDMETHOD(QueryInterface)(THIS_ REFIID riid, PVOID *ppvObject) PURE; STDMETHOD_(ULONG, AddRef)(THIS) PURE; STDMETHOD_(ULONG, Release)(THIS) PURE;
/* IUniformResourceLocator methods */
STDMETHOD(SetURL)(THIS_ LPCWSTR pcszURL, DWORD dwInFlags) PURE;
STDMETHOD(GetURL)(THIS_ LPWSTR *ppszURL) PURE;
STDMETHOD(InvokeCommand)(THIS_ PURLINVOKECOMMANDINFOW purlici) PURE;};
#ifdef UNICODE
#define IUniformResourceLocator IUniformResourceLocatorW
#define IUniformResourceLocatorVtbl IUniformResourceLocatorWVtbl
#else
#define IUniformResourceLocator IUniformResourceLocatorA
#define IUniformResourceLocatorVtbl IUniformResourceLocatorAVtbl
#endif
typedef IUniformResourceLocator *PIUniformResourceLocator;typedef const IUniformResourceLocator CIUniformResourceLocator;typedef const IUniformResourceLocator *PCIUniformResourceLocator;
/* Prototypes
*************/
//
// Input flags for TranslateURL().
//
typedef enum translateurl_in_flags{ TRANSLATEURL_FL_GUESS_PROTOCOL = 0x0001, // Guess protocol if missing
TRANSLATEURL_FL_USE_DEFAULT_PROTOCOL = 0x0002, // Use default protocol if missing
}TRANSLATEURL_IN_FLAGS;
//
// TranslateURL(). This function applies common translations to a URL
// string, creating a new URL string.
//
// This function does not perform any validation on the syntax of the input
// URL string. A successful return value does not indicate that the input
// or output URL strings are valid URLS.
//
// The function returns S_OK if the URL string is translated successfully
// and *ppszTranslatedURL points to the translated URL string. S_FALSE
// is returned if the URL string did not require translation. An error
// code is returned if an error occurs.
//
// Parameters:
// pcszURL -- A pointer to the URL string to be translated.
// dwInFlags -- A bit field of TRANSLATEURL_IN_FLAGS.
// ppszTranslatedURL -- A pointer to the newly created, translated URL
// string, if any. *ppszTranslatedURL is only valid if S_OK is returned.
// If valid, *ppszTranslatedURL should be freed by calling LocalFree().
// *ppszTranslatedURL is NULL on error.
//
INTSHCUTAPI HRESULT WINAPI TranslateURLA(PCSTR pcszURL, DWORD dwInFlags, PSTR *ppszTranslatedURL);INTSHCUTAPI HRESULT WINAPI TranslateURLW(PCWSTR pcszURL, DWORD dwInFlags, PWSTR UNALIGNED *ppszTranslatedURL);#ifdef UNICODE
#define TranslateURL TranslateURLW
#else
#define TranslateURL TranslateURLA
#endif /* UNICODE */
//
// Input flags for URLAssociationDialog().
//
typedef enum urlassociationdialog_in_flags{ URLASSOCDLG_FL_USE_DEFAULT_NAME = 0x0001, URLASSOCDLG_FL_REGISTER_ASSOC = 0x0002}URLASSOCIATIONDIALOG_IN_FLAGS;
//
// URLAssocationDialog(). This function invokes the unregistered URL
// protocol dialog box, providing a standard ui for choosing the handler for
// an unregistered URL protocol.
//
// The functions returns S_OK if the application is registered with the
// URL protocol. S_FALSE is returned if nothing is registered (a one-time
// execution via the selected application is requested).
//
// Parameters:
// hwndParent -- A handle to the window to be used as the parent
// dwInFlags -- A bit field of URLASSOCIATIONDIALOG_IN_FLAGS. The
// flags are:
//
// URLASSOCDLG_FL_USE_DEFAULT_NAME: Use the default Internet
// Shortcut file name. Ignore pcszFile.
//
// URLASSOCDLG_FL_REGISTER_ASSOC: The application
// selected is to be registered as the handler for URLs
// of pcszURL's protocol. An application is only
// registered if this flag is set, and the user indicates
// that a persistent association is to be made.
//
// pcszFile -- The name of the Internet Shortcut file whose URL's protocol
// requires a protocol handler. Before a verb, like "open", can
// be invoked on an Internet Shortcut, a protocol handler must be
// registered for its URL protocol. If
// URLASSOCDLG_FL_USE_DEFAULT_NAME is set in dwInFlags, pcszFile
// is ignored, and a default Internet Shortcut file name is used.
// pcszFile is only used for ui.
// pcszURL -- The URL whose unregistered protocol requires a handler.
// pszAppBuf -- A buffer to be filled in on success with the path
// of the application selected by the user. pszAppBuf's
// buffer is filled in with the empty string on failure.
// ucAppBufLen -- The length of pszAppBuf's buffer in characters.
//
INTSHCUTAPI HRESULT WINAPI URLAssociationDialogA(HWND hwndParent, DWORD dwInFlags, PCSTR pcszFile, PCSTR pcszURL, PSTR pszAppBuf, UINT ucAppBufLen);INTSHCUTAPI HRESULT WINAPI URLAssociationDialogW(HWND hwndParent, DWORD dwInFlags, PCWSTR pcszFile, PCWSTR pcszURL, PWSTR pszAppBuf, UINT ucAppBufLen);#ifdef UNICODE
#define URLAssociationDialog URLAssociationDialogW
#else
#define URLAssociationDialog URLAssociationDialogA
#endif /* UNICODE */
//
// Input flags for MIMEAssocationDialog().
//
typedef enum mimeassociationdialog_in_flags{ MIMEASSOCDLG_FL_REGISTER_ASSOC = 0x0001}MIMEASSOCIATIONDIALOG_IN_FLAGS;
//
// MIMEAssociationDialog(). Invokes the unregistered MIME content
// type dialog box.
//
// This function does not perform any validation on the syntax of the
// input content type string. A successful return value does not indicate
// that the input MIME content type string is a valid content type.
//
// The function returns S_OK if the MIME content type is associated
// with the extension. The extension is associated as the default
// extension for the content type. S_FALSE is returned if nothing is
// registered. Otherwise, the function returns one of the following
// errors:
//
// E_ABORT -- The user cancelled the operation.
// E_FLAGS -- The flag combination passed in dwFlags is invalid.
// E_OUTOFMEMORY -- Not enough memory to complete the operation.
// E_POINTER -- One of the input pointers is invalid.
//
// Parameters:
// hwndParent -- A handle to the window to be used as the parent
// window of any posted child windows.
// dwInFlags -- A bit field of MIMEASSOCIATIONDIALOG_IN_FLAGS. The
// flags are:
//
// MIMEASSOCDLG_FL_REGISTER_ASSOC: If set, the application
// selected is to be registered as the handler for files of
// the given MIME type. If clear, no association is to be
// registered. An application is only registered if this
// flag is set, and the user indicates that a persistent
// association is to be made. Registration is only possible
// if pcszFile contains an extension.
//
// pcszFile -- A pointer to a string indicating the name of the file
// containing data of pcszMIMEContentType's content type.
// pcszMIMEContentType -- A pointer to a string indicating the content
// type for which an application is sought.
// pszAppBuf -- A buffer to be filled in on success with the path of
// the application selected by the user. pszAppBuf's buffer
// is filled in with the empty string on failure.
// ucAppBufLen -- The length of pszAppBuf's buffer in characters.
//
INTSHCUTAPI HRESULT WINAPI MIMEAssociationDialogA(HWND hwndParent, DWORD dwInFlags, PCSTR pcszFile, PCSTR pcszMIMEContentType, PSTR pszAppBuf, UINT ucAppBufLen);INTSHCUTAPI HRESULT WINAPI MIMEAssociationDialogW(HWND hwndParent, DWORD dwInFlags, PCWSTR pcszFile, PCWSTR pcszMIMEContentType, PWSTR pszAppBuf, UINT ucAppBufLen);#ifdef UNICODE
#define MIMEAssociationDialog MIMEAssociationDialogW
#else
#define MIMEAssociationDialog MIMEAssociationDialogA
#endif /* UNICODE */
//
// InetIsOffline(). This function determines if the user wants to be
// "offline" (get all information from the cache). The dwFlags must be
// 0.
//
// The function returns TRUE to indicate that the local system is not
// currently connected to the Internet. The function returns FALSE to
// indicate that either the local system is connected to the Internet,
// or no attempt has yet been made to connect the local system to the
// Internet. Applications that wish to support an off-line mode should
// do so if InetIsOffline() returns TRUE.
//
// Off-line mode begins when the user has been prompted to dial-in to
// an Internet providor, but canceled the attempt.
//
INTSHCUTAPIBOOLWINAPIInetIsOffline( DWORD dwFlags);
#ifdef __cplusplus
} /* End of extern "C" {. */#endif /* __cplusplus */
#endif /* ! __INTSHCUT_H__ */
|
