home *** CD-ROM | disk | FTP | other *** search
/ Tricks of the Windows Gam…ming Gurus (2nd Edition) / Disc2.iso / vc98 / include / intshcut.h < prev    next >
C/C++ Source or Header  |  1998-04-25  |  18KB  |  499 lines
  1.  
  2. /*
  3.  * intshcut.h - Internet Shortcut interface definitions.
  4.  *
  5.  * Copyright 1995 - 1998 Microsoft Corporation.  All rights reserved.
  6.  */
  7.  
  8.  
  9. #ifndef __INTSHCUT_H__
  10. #define __INTSHCUT_H__
  11.  
  12. /* Headers
  13.  **********/
  14.  
  15. #include <isguids.h>
  16.  
  17.  
  18. #ifdef __cplusplus
  19. extern "C" {                        /* Assume C declarations for C++. */
  20. #endif   /* __cplusplus */
  21.  
  22.  
  23. /* Constants
  24.  ************/
  25.  
  26. /* Define API decoration for direct import of DLL functions. */
  27.  
  28. #ifdef _INTSHCUT_
  29. #define INTSHCUTAPI
  30. #else
  31. #define INTSHCUTAPI                 DECLSPEC_IMPORT
  32. #endif
  33.  
  34. /* HRESULTs */
  35.  
  36. //
  37. // MessageId: E_FLAGS
  38. //
  39. // MessageText:
  40. //
  41. //  The flag combination is invalid.
  42. //
  43. #define E_FLAGS                     MAKE_SCODE(SEVERITY_ERROR, FACILITY_ITF, 0x1000)
  44.  
  45. //
  46. // MessageId: IS_E_EXEC_FAILED
  47. //
  48. // MessageText:
  49. //
  50. //  The URL's protocol handler failed to run.
  51. //
  52. #define IS_E_EXEC_FAILED            MAKE_SCODE(SEVERITY_ERROR, FACILITY_ITF, 0x2002)
  53.  
  54. //
  55. // MessageId: URL_E_INVALID_SYNTAX
  56. //
  57. // MessageText:
  58. //
  59. //  The URL's syntax is invalid.
  60. //
  61. #define URL_E_INVALID_SYNTAX        MAKE_SCODE(SEVERITY_ERROR, FACILITY_ITF, 0x1001)
  62.  
  63. //
  64. // MessageId: URL_E_UNREGISTERED_PROTOCOL
  65. //
  66. // MessageText:
  67. //
  68. //  The URL's protocol does not have a registered protocol handler.
  69. //
  70. #define URL_E_UNREGISTERED_PROTOCOL MAKE_SCODE(SEVERITY_ERROR, FACILITY_ITF, 0x1002)
  71.  
  72.  
  73. /* Interfaces
  74.  *************/
  75.  
  76. //
  77. // Input flags for IUniformResourceLocator::SetURL().
  78. //
  79. typedef enum iurl_seturl_flags
  80. {
  81.    IURL_SETURL_FL_GUESS_PROTOCOL        = 0x0001,     // Guess protocol if missing
  82.    IURL_SETURL_FL_USE_DEFAULT_PROTOCOL  = 0x0002,     // Use default protocol if missing
  83. }
  84. IURL_SETURL_FLAGS;
  85.  
  86.  
  87. //
  88. // Input flags for IUniformResourceLocator()::InvokeCommand().
  89. //
  90. typedef enum iurl_invokecommand_flags
  91. {
  92.    IURL_INVOKECOMMAND_FL_ALLOW_UI                  = 0x0001,
  93.    IURL_INVOKECOMMAND_FL_USE_DEFAULT_VERB          = 0x0002,    // Ignore pcszVerb
  94. }
  95. IURL_INVOKECOMMAND_FLAGS;
  96.  
  97.  
  98. //
  99. // Command info for IUniformResourceLocator::InvokeCommand().
  100. //
  101.  
  102. typedef struct urlinvokecommandinfoA
  103. {
  104.    DWORD  dwcbSize;          // Size of structure
  105.    DWORD  dwFlags;           // Bit field of IURL_INVOKECOMMAND_FLAGS
  106.    HWND   hwndParent;        // Parent window.  Valid only if IURL_INVOKECOMMAND_FL_ALLOW_UI is set.
  107.    LPCSTR pcszVerb;          // Verb to invoke.  Ignored if IURL_INVOKECOMMAND_FL_USE_DEFAULT_VERB is set.
  108. }
  109. URLINVOKECOMMANDINFOA;
  110. typedef URLINVOKECOMMANDINFOA *PURLINVOKECOMMANDINFOA;
  111. typedef const URLINVOKECOMMANDINFOA CURLINVOKECOMMANDINFOA;
  112. typedef const URLINVOKECOMMANDINFOA *PCURLINVOKECOMMANDINFOA;
  113.  
  114. typedef struct urlinvokecommandinfoW
  115. {
  116.    DWORD   dwcbSize;          // Size of structure
  117.    DWORD   dwFlags;           // Bit field of IURL_INVOKECOMMAND_FLAGS
  118.    HWND    hwndParent;        // Parent window.  Valid only if IURL_INVOKECOMMAND_FL_ALLOW_UI is set.
  119.    LPCWSTR pcszVerb;          // Verb to invoke.  Ignored if IURL_INVOKECOMMAND_FL_USE_DEFAULT_VERB is set.
  120. }
  121. URLINVOKECOMMANDINFOW;
  122. typedef URLINVOKECOMMANDINFOW *PURLINVOKECOMMANDINFOW;
  123. typedef const URLINVOKECOMMANDINFOW CURLINVOKECOMMANDINFOW;
  124. typedef const URLINVOKECOMMANDINFOW *PCURLINVOKECOMMANDINFOW;
  125.  
  126. #ifdef UNICODE
  127. #define URLINVOKECOMMANDINFO            URLINVOKECOMMANDINFOW
  128. #define PURLINVOKECOMMANDINFO           PURLINVOKECOMMANDINFOW
  129. #define CURLINVOKECOMMANDINFO           CURLINVOKECOMMANDINFOW
  130. #define PCURLINVOKECOMMANDINFO          PCURLINVOKECOMMANDINFOW
  131. #else
  132. #define URLINVOKECOMMANDINFO            URLINVOKECOMMANDINFOA
  133. #define PURLINVOKECOMMANDINFO           PURLINVOKECOMMANDINFOA
  134. #define CURLINVOKECOMMANDINFO           CURLINVOKECOMMANDINFOA
  135. #define PCURLINVOKECOMMANDINFO          PCURLINVOKECOMMANDINFOA
  136. #endif
  137.  
  138.  
  139. //===========================================================================
  140. //
  141. // IUniformResourceLocator interface
  142. //
  143. // [OverView]
  144. //
  145. //  Provides access to Internet Shortcuts.
  146. //
  147. // [Member functions]
  148. //
  149. // IUniformResourceLocator::SetURL
  150. //
  151. //   This member function sets an object's URL.
  152. //
  153. //   The dwInFlags parameter specifies the behavior:
  154. //
  155. //  IURL_SETURL_FL_GUESS_PROTOCOL: The protocol scheme is guessed and added
  156. //   to the URL, if it is not specified in pcszURL.
  157. //
  158. //  IURL_SETURL_FL_USE_DEFAULT_PROTOCOL: The default protocol scheme is added
  159. //   to the URL, if it is not specified in pcszURL.
  160. //
  161. //   The function returns S_OK if the object's URL is set successfully.
  162. //  Otherwise, an error code is returned:
  163. //
  164. //  E_OUTOFMEMORY:  There is not enough memory to complete the operation.
  165. //
  166. //  IS_E_EXEC_FAILED:  The URL's protocol handler failed to run.
  167. //
  168. //  URL_E_INVALID_SYNTAX:  The URL's syntax is invalid.
  169. //
  170. //  URL_E_UNREGISTERED_PROTOCOL:  The URL's protocol does not have a
  171. //   registered protocol handler.
  172. //
  173. //
  174. // IUniformResourceLocator::GetURL
  175. //
  176. //   This member function retrieves an object's URL.  The ppszURL is a
  177. //  pointer to a PSTR to be filled in which a pointer to the object's
  178. //  URL.  When finished, this string should be freed using IMalloc::Free().
  179. //
  180. //   The function returns S_OK if the object's URL was retrieved
  181. //  successfully.  If the object does not have a URL associated with it,
  182. //  then S_FALSE is returned and *ppszURL is set to NULL.  Otherwise, an
  183. //  error code is returned:
  184. //
  185. //  E_OUTOFMEMORY:  There is not enough memory to complete the operation.
  186. //
  187. //  IS_E_EXEC_FAILED:  The URL's protocol handler failed to run.
  188. //
  189. //  URL_E_INVALID_SYNTAX:  The URL's syntax is invalid.
  190. //
  191. //  URL_E_UNREGISTERED_PROTOCOL:  The URL's protocol does not have a
  192. //   registered protocol handler.
  193. //
  194. //
  195. // IUniformResourceLocator::InvokeCommand
  196. //
  197. //   This member function invokes a command on an object's URL.  The purlici
  198. //  parameter is a pointer to a URLINVOKECOMMANDINFO structure which
  199. //  describes the command to be invoked.
  200. //
  201. //   The function returns S_OK if the object's URL was opened successfully.
  202. //  If the object does not have a URL associated with it, the function
  203. //  returns S_FALSE.  Otherwise, an error code is returned:
  204. //
  205. //  E_OUTOFMEMORY:  There is not enough memory to complete the operation.
  206. //
  207. //  IS_E_EXEC_FAILED:  The URL's protocol handler failed to run.
  208. //
  209. //  URL_E_INVALID_SYNTAX:  The URL's syntax is invalid.
  210. //
  211. //  URL_E_UNREGISTERED_PROTOCOL:  The URL's protocol does not have a
  212. //   registered protocol handler.
  213. //
  214. //===========================================================================
  215.  
  216. #undef  INTERFACE
  217. #define INTERFACE IUniformResourceLocatorA
  218.  
  219. DECLARE_INTERFACE_(IUniformResourceLocatorA, IUnknown)
  220. {
  221.    /* IUnknown methods */
  222.  
  223.    STDMETHOD(QueryInterface)(THIS_
  224.                              REFIID riid,
  225.                              PVOID *ppvObject) PURE;
  226.    STDMETHOD_(ULONG, AddRef)(THIS) PURE;
  227.    STDMETHOD_(ULONG, Release)(THIS) PURE;
  228.  
  229.    /* IUniformResourceLocator methods */
  230.  
  231.    STDMETHOD(SetURL)(THIS_
  232.                      LPCSTR pcszURL,
  233.                      DWORD dwInFlags) PURE;
  234.  
  235.    STDMETHOD(GetURL)(THIS_
  236.                      LPSTR *ppszURL) PURE;
  237.  
  238.    STDMETHOD(InvokeCommand)(THIS_
  239.                             PURLINVOKECOMMANDINFOA purlici) PURE;
  240. };
  241.  
  242. #undef  INTERFACE
  243. #define INTERFACE IUniformResourceLocatorW
  244.  
  245. DECLARE_INTERFACE_(IUniformResourceLocatorW, IUnknown)
  246. {
  247.    /* IUnknown methods */
  248.  
  249.    STDMETHOD(QueryInterface)(THIS_
  250.                              REFIID riid,
  251.                              PVOID *ppvObject) PURE;
  252.    STDMETHOD_(ULONG, AddRef)(THIS) PURE;
  253.    STDMETHOD_(ULONG, Release)(THIS) PURE;
  254.  
  255.    /* IUniformResourceLocator methods */
  256.  
  257.    STDMETHOD(SetURL)(THIS_
  258.                      LPCWSTR pcszURL,
  259.                      DWORD dwInFlags) PURE;
  260.  
  261.    STDMETHOD(GetURL)(THIS_
  262.                      LPWSTR *ppszURL) PURE;
  263.  
  264.    STDMETHOD(InvokeCommand)(THIS_
  265.                             PURLINVOKECOMMANDINFOW purlici) PURE;
  266. };
  267.  
  268. #ifdef UNICODE
  269. #define IUniformResourceLocator         IUniformResourceLocatorW
  270. #define IUniformResourceLocatorVtbl     IUniformResourceLocatorWVtbl
  271. #else
  272. #define IUniformResourceLocator         IUniformResourceLocatorA
  273. #define IUniformResourceLocatorVtbl     IUniformResourceLocatorAVtbl
  274. #endif
  275.  
  276. typedef IUniformResourceLocator *PIUniformResourceLocator;
  277. typedef const IUniformResourceLocator CIUniformResourceLocator;
  278. typedef const IUniformResourceLocator *PCIUniformResourceLocator;
  279.  
  280.  
  281. /* Prototypes
  282.  *************/
  283.  
  284. //
  285. // Input flags for TranslateURL().
  286. //
  287. typedef enum translateurl_in_flags
  288. {
  289.    TRANSLATEURL_FL_GUESS_PROTOCOL         = 0x0001,     // Guess protocol if missing
  290.    TRANSLATEURL_FL_USE_DEFAULT_PROTOCOL   = 0x0002,     // Use default protocol if missing
  291. }
  292. TRANSLATEURL_IN_FLAGS;
  293.  
  294.  
  295. //
  296. //   TranslateURL().  This function applies common translations to a URL
  297. //  string, creating a new URL string.
  298. //
  299. //   This function does not perform any validation on the syntax of the input
  300. //  URL string.  A successful return value does not indicate that the input
  301. //  or output URL strings are valid URLS.
  302. //
  303. //   The function returns S_OK if the URL string is translated successfully
  304. //  and *ppszTranslatedURL points to the translated URL string.  S_FALSE
  305. //  is returned if the URL string did not require translation.  An error
  306. //  code is returned if an error occurs.
  307. //
  308. //  Parameters:
  309. //   pcszURL -- A pointer to the URL string to be translated.
  310. //   dwInFlags -- A bit field of TRANSLATEURL_IN_FLAGS.
  311. //   ppszTranslatedURL -- A pointer to the newly created, translated URL
  312. //     string, if any.  *ppszTranslatedURL is only valid if S_OK is returned.
  313. //     If valid, *ppszTranslatedURL should be freed by calling LocalFree().
  314. //     *ppszTranslatedURL is NULL on error.
  315. //
  316.  
  317. INTSHCUTAPI HRESULT WINAPI TranslateURLA(PCSTR pcszURL,
  318.                                          DWORD dwInFlags,
  319.                                          PSTR *ppszTranslatedURL);
  320. INTSHCUTAPI HRESULT WINAPI TranslateURLW(PCWSTR pcszURL,
  321.                                          DWORD dwInFlags,
  322.                                          PWSTR UNALIGNED *ppszTranslatedURL);
  323. #ifdef UNICODE
  324. #define TranslateURL             TranslateURLW
  325. #else
  326. #define TranslateURL             TranslateURLA
  327. #endif   /* UNICODE */
  328.  
  329.  
  330. //
  331. // Input flags for URLAssociationDialog().
  332. //
  333. typedef enum urlassociationdialog_in_flags
  334. {
  335.    URLASSOCDLG_FL_USE_DEFAULT_NAME        = 0x0001,
  336.    URLASSOCDLG_FL_REGISTER_ASSOC          = 0x0002,
  337. }
  338. URLASSOCIATIONDIALOG_IN_FLAGS;
  339.  
  340.  
  341. //
  342. //   URLAssocationDialog().  This function invokes the unregistered URL
  343. //  protocol dialog box, providing a standard ui for choosing the handler for
  344. //  an unregistered URL protocol.
  345. //
  346. //  The functions returns S_OK if the application is registered with the
  347. //  URL protocol.  S_FALSE is returned if nothing is registered (a one-time
  348. //  execution via the selected application is requested).
  349. //
  350. //  Parameters:
  351. //   hwndParent -- A handle to the window to be used as the parent
  352. //   dwInFlags -- A bit field of URLASSOCIATIONDIALOG_IN_FLAGS.  The
  353. //                flags are:
  354. //
  355. //                  URLASSOCDLG_FL_USE_DEFAULT_NAME: Use the default Internet
  356. //                   Shortcut file name.  Ignore pcszFile.
  357. //
  358. //                  URLASSOCDLG_FL_REGISTER_ASSOC: The application
  359. //                   selected is to be registered as the handler for URLs
  360. //                   of pcszURL's protocol.  An application is only
  361. //                   registered if this flag is set, and the user indicates
  362. //                   that a persistent association is to be made.
  363. //
  364. //   pcszFile -- The name of the Internet Shortcut file whose URL's protocol
  365. //               requires a protocol handler.  Before a verb, like "open", can
  366. //               be invoked on an Internet Shortcut, a protocol handler must be
  367. //               registered for its URL protocol.  If
  368. //               URLASSOCDLG_FL_USE_DEFAULT_NAME is set in dwInFlags, pcszFile
  369. //               is ignored, and a default Internet Shortcut file name is used.
  370. //               pcszFile is only used for ui.
  371. //   pcszURL -- The URL whose unregistered protocol requires a handler.
  372. //   pszAppBuf -- A buffer to be filled in on success with the path
  373. //                of the application selected by the user.  pszAppBuf's
  374. //                buffer is filled in with the empty string on failure.
  375. //   ucAppBufLen -- The length of pszAppBuf's buffer in characters.
  376. //
  377.  
  378. INTSHCUTAPI HRESULT WINAPI URLAssociationDialogA(HWND hwndParent,
  379.                                                  DWORD dwInFlags,
  380.                                                  PCSTR pcszFile,
  381.                                                  PCSTR pcszURL,
  382.                                                  PSTR pszAppBuf,
  383.                                                  UINT ucAppBufLen);
  384. INTSHCUTAPI HRESULT WINAPI URLAssociationDialogW(HWND hwndParent,
  385.                                                  DWORD dwInFlags,
  386.                                                  PCWSTR pcszFile,
  387.                                                  PCWSTR pcszURL,
  388.                                                  PWSTR pszAppBuf,
  389.                                                  UINT ucAppBufLen);
  390. #ifdef UNICODE
  391. #define URLAssociationDialog     URLAssociationDialogW
  392. #else
  393. #define URLAssociationDialog     URLAssociationDialogA
  394. #endif  /* UNICODE */
  395.  
  396.  
  397. //
  398. // Input flags for MIMEAssocationDialog().
  399. //
  400. typedef enum mimeassociationdialog_in_flags
  401. {
  402.    MIMEASSOCDLG_FL_REGISTER_ASSOC         = 0x0001,
  403. }
  404. MIMEASSOCIATIONDIALOG_IN_FLAGS;
  405.  
  406.  
  407. //
  408. //   MIMEAssociationDialog().  Invokes the unregistered MIME content
  409. //  type dialog box.
  410. //
  411. //   This function does not perform any validation on the syntax of the
  412. //  input content type string.  A successful return value does not indicate
  413. //  that the input MIME content type string is a valid content type.
  414. //
  415. //   The function returns S_OK if the MIME content type is associated
  416. //  with the extension.  The extension is associated as the default
  417. //  extension for the content type.  S_FALSE is returned if nothing is
  418. //  registered.  Otherwise, the function returns one of the following
  419. //  errors:
  420. //
  421. //  E_ABORT -- The user cancelled the operation.
  422. //  E_FLAGS -- The flag combination passed in dwFlags is invalid.
  423. //  E_OUTOFMEMORY -- Not enough memory to complete the operation.
  424. //  E_POINTER -- One of the input pointers is invalid.
  425. //
  426. //  Parameters:
  427. //   hwndParent -- A handle to the window to be used as the parent
  428. //                 window of any posted child windows.
  429. //   dwInFlags -- A bit field of MIMEASSOCIATIONDIALOG_IN_FLAGS.  The
  430. //                flags are:
  431. //
  432. //              MIMEASSOCDLG_FL_REGISTER_ASSOC: If set, the application
  433. //               selected is to be registered as the handler for files of
  434. //               the given MIME type.  If clear, no association is to be
  435. //               registered.  An application is only registered if this
  436. //               flag is set, and the user indicates that a persistent
  437. //               association is to be made.  Registration is only possible
  438. //               if pcszFile contains an extension.
  439. //
  440. //   pcszFile -- A pointer to a string indicating the name of the file
  441. //               containing data of pcszMIMEContentType's content type.
  442. //   pcszMIMEContentType -- A pointer to a string indicating the content
  443. //                          type for which an application is sought.
  444. //   pszAppBuf -- A buffer to be filled in on success with the path of
  445. //                the application selected by the user.  pszAppBuf's buffer
  446. //                is filled in with the empty string on failure.
  447. //   ucAppBufLen -- The length of pszAppBuf's buffer in characters.
  448. //
  449.  
  450. INTSHCUTAPI HRESULT WINAPI MIMEAssociationDialogA(HWND hwndParent,
  451.                                                   DWORD dwInFlags,
  452.                                                   PCSTR pcszFile,
  453.                                                   PCSTR pcszMIMEContentType,
  454.                                                   PSTR pszAppBuf,
  455.                                                   UINT ucAppBufLen);
  456. INTSHCUTAPI HRESULT WINAPI MIMEAssociationDialogW(HWND hwndParent,
  457.                                                   DWORD dwInFlags,
  458.                                                   PCWSTR pcszFile,
  459.                                                   PCWSTR pcszMIMEContentType,
  460.                                                   PWSTR pszAppBuf,
  461.                                                   UINT ucAppBufLen);
  462. #ifdef UNICODE
  463. #define MIMEAssociationDialog    MIMEAssociationDialogW
  464. #else
  465. #define MIMEAssociationDialog    MIMEAssociationDialogA
  466. #endif  /* UNICODE */
  467.  
  468.  
  469. //
  470. //   InetIsOffline().  This function determines if the user wants to be
  471. //  "offline" (get all information from the cache).  The dwFlags must be
  472. //  0.
  473. //
  474. //   The function returns TRUE to indicate that the local system is not
  475. //  currently connected to the Internet.  The function returns FALSE to
  476. //  indicate that either the local system is connected to the Internet,
  477. //  or no attempt has yet been made to connect the local system to the
  478. //  Internet.  Applications that wish to support an off-line mode should
  479. //  do so if InetIsOffline() returns TRUE.
  480. //
  481. //   Off-line mode begins when the user has been prompted to dial-in to
  482. //  an Internet providor, but canceled the attempt.
  483. //
  484. INTSHCUTAPI
  485. BOOL
  486. WINAPI
  487. InetIsOffline(
  488.     DWORD dwFlags);
  489.  
  490.  
  491. #ifdef __cplusplus
  492. }                                   /* End of extern "C" {. */
  493. #endif   /* __cplusplus */
  494.  
  495.  
  496. #endif   /* ! __INTSHCUT_H__ */
  497.  
  498.  
  499.