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