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