/LIBS/Extensions/inc/office10/msourl.h
C++ Header | 646 lines | 310 code | 68 blank | 268 comment | 4 complexity | 73b5a992a63d4823857476ff2b825016 MD5 | raw file
Possible License(s): Apache-2.0, LGPL-2.0
- /****************************************************************************
- msourl.h
-
- Owner: SeanMc
- Copyright (c) 1999 Microsoft Corporation
-
- MSO's url handling interfaces.
- ****************************************************************************/
-
- #pragma once
-
- #ifndef MSOURL_H
- #define MSOURL_H
-
- #ifndef CONST_METHOD
- // to declare const methods in C++
- #if defined(__cplusplus) && !defined(CINTERFACE)
- #define CONST_METHOD const
- #else
- #define CONST_METHOD
- #endif
- #endif
-
- #include "wininet.h"
- #include "msobp.h"
-
- // list of schemes recognized via MsoUrl
- typedef enum
- {
- urlsNil = -1,
- urlsHttp, // "http"
- urlsHttps, // "https"
- urlsFtp, // "ftp"
- urlsFile, // "file"
- urlsCid, // "cid"
- urlsMailto, // "mailto"
- urlsJavascript, // "javascript"
- urlsOutlook, // "outlook"
- urlsODMA, // "::ODMA\"
- urlsMhtmlCompound, // "mhtml:X!Y"
- urlsThismessage, // "thismessage"
- urlsRes, // "res"
- urlsMk, // "mk"
- urlsUnknown
- } MSOURLSCHEME;
-
-
- // list of relativities understood via MsoUrl
- typedef enum
- {
- urlrNil = -1,
- urlrOpaque, // EXAMPLE: "mailto:someone@somewhere.com"
- urlrAbsolute, // EXAMPLE: "http://mumble.com/woo.hoo"
- urlrServer, // EXAMPLE: "/foo/bar/woo.hoo"
- urlrPage // EXAMPLE: "../foo/bar/woo.hoo"
- } MSOURLRELATIVITY;
-
-
- /* URLC (Url Component) flags, passed to IMsoUrl::HrGetCustomForm & IMsoUrl::FComponentsAreEqual. */
- #define msofurlcScheme 0x0001
- #define msofurlcUserName 0x0002
- #define msofurlcPassword 0x0004
- #define msofurlcServer 0x0008
- #define msofurlcPort 0x0010
- #define msofurlcDir 0x0020
- #define msofurlcFileName 0x0040
- #define msofurlcFileExt 0x0080
- #define msofurlcQuery 0x0100
- #define msofurlcFragment 0x0200
- #define msofurlcMhtml 0x0400
-
- #define msofurlcAuthority (msofurlcUserName | msofurlcPassword | msofurlcServer | msofurlcPort)
- #define msofurlcFileLeaf (msofurlcFileName | msofurlcFileExt)
- #define msofurlcPath (msofurlcDir | msofurlcFileLeaf)
- #define msofurlcComplete (msofurlcScheme | msofurlcAuthority | msofurlcPath | msofurlcQuery | msofurlcFragment | msofurlcMhtml)
-
- /* URL flags, passed to IMsoUrl::HrSetFromUser[Rgwch]. */
- #define msofurlNoFragment 0x00000001 // don't treat the '#' character as a fragment delimiter
- #define msofurlStripEncapsulatingDelims 0x00000002 // strip off quotes or angle brackets encapsulating the url (if present)
- #define msofurlConvertDriveMappedUNC 0x00000004 // convert drive mapped UNCs to pure UNC form
- #define msofurlConvertToShortFileName 0x00000008 // convert any local paths to 8.3 form
- #define msofurlConvertToLongFileName 0x00000010 // convert any local paths to long filename form
- #define msofurlEscapeSingleQuotes 0x00000020 // escape any single quotes found in the url
- #define msofurlEscapeAllPercents 0x00000040 // escape all percents (normally percents in %HH sequences are not escaped)
- #define msofurlStripLeadingWhitespace 0x00000080 // strip off leading whitespace (if present)
- #define msofurlStripTrailingWhitespace 0x00000100 // strip off trailing whitespace (if present)
- // if present with msofurlStripEncapsulatingDelims, strips both inside and outside delims
- #define msofurlApplyGuessScheme 0x00000200 // apply best guess scheme if none exists on the url
- #define msofurlApplyDefaultScheme 0x00000400 // apply the default scheme if none exists on the url
- #define msofurlCaseInsensitivePath 0x00000800 // use case-insensitive comparisons on the path component
- #define msofurlEnsureTrailingPathSep 0x00001000 // ensure the path component includes a trailing slash (indicating it is a directory)
- #define msofurlRemoveTrailingPathSep 0x00002000 // ensure the path component does not have a trailing slash (indicating a file leaf or empty path)
- #define msofurlAllowInvertedLocalSep 0x00004000 // let "x:/" map to { scheme:"file", path:"x:\" }, rather than { scheme:"x", path:"/" }
- // also applies the same logic to "//server/share"
- #define msofurlDontChangeSlashTypes 0x00008000 // don't change /'s to \'s or vice-versa
- #define msofurlNoEscape 0x00010000 // don't escape this url internally
- #define msofurlEnsureValidAuthority 0x00020000 // ensure the authority component is valid if present (non-empty)
- #define msofurlNoQuery 0x00040000 // don't treat the '?' character as a query delimiter
- #define msofurlEnsureBalancedQuotes 0x00080000 // ensure no unbalanced quotes at the beginning/end of the URL
- // use with caution: these may be valid in some cases
- #define msofurlEscapeAllReservedChars 0x00100000 // escape all reserved characters (any in ";/:@&=+$,") use with care -- creates very odd urls!
- #define msofurlDetectASPLinks 0x00200000 // client wants ASP links detected
-
- /* URLDF flags, passed to IMsoUrl::HrGetDisplayForm. */
- #define msofurldfUnescapeHighAnsi 0x0001 // unescape high-ANSI entities (use with extreme caution!)
- #define msofurldfUseLocalPathForm 0x0002 // use the local path form for local urls (return what HrGetLocalPath would return if the url is local)
- #define msofurldfDoNotUnescapeHash 0x0004 // do not unescape the hash character (leave it "%23" instead)
- #define msofurldfDoNotUnescapeLowAnsi 0x0008 // do not unescape low-ANSI entities (use with extreme caution!)
-
- /* URLCF flags, passed to IMsoUrl::HrGetCustomForm. */
- #define msofurlcfDisplay 0x0001 // get the display form
- #define msofurlcf3SlashFileSyntax 0x0002 // use the 3 slash file: syntax
- #define msofurlcfUseHideExtShellSetting 0x0004 // use the OS shell setting to hide extensions to include ext in leaf
- #define msofurlcfUseLocalPathForm 0x0008 // use the local path form for local urls (return what HrGetLocalPath would return if the url is local)
-
- /* URLE flags, passed to IMsoUrl::FExists. */
- #define msofurleCheckServers 0x0001 // validate against the server (if not set then server based paths return FALSE)
- #define msofurleFolder 0x0002 // verify that path points to a folder
- #define msofurleBrowsable 0x0004 // verify that path points to a browsable folder (requires msofurleFolder)
- #define msofurleAllowUI 0x0008 // allow UI to be raised (such as the password authentication dialog)
-
- /* URLU flags, passed to IMsoUrl::HrUpload. */
- #define msofurluAlertIfExist 0x0001
- #define msofurluFailIfExist 0x0002
-
- /* URLD flags, passed to IMsoUrl::HrDownload. */
- #define msofurldUseCachedVersion 0x0001 // if it already exists in the cache, use it (otherwise download it)
-
-
- /////////////////////////////////////////////////////////////////////////////////
- //
- // Basic url definitions:
- //
- // hierarchichal url := <scheme>://<authority>[/<path>][?<query>][#<fragment>]
- // authority := [<username>[:<password>]@]<server>[:<port>]
- // path := <dir>[/[fileleaf]]
- // fileleaf := <filename>[.<fileext>]
- //
- // opaque url := <scheme>:<path>[?<query>][#<fragment>]
- //
- // NOTE: every url always has a path (& dir) component (but it may be the empty string)
- //
- /////////////////////////////////////////////////////////////////////////////////
- //
- // Mhtml url definitions:
- //
- // Only-File form: mhtml:X - where X is an absolute hierarchichal url.
- // Compound form: mhtml:X!Y - where X is like above, Y is a CID or CLOC (Content-Location)
- //
- // NOTE: We do not return Only-File forms for these types of url's, since this can
- // expose a bug in IE which causes these files to be loaded with the wrong codepage.
- // NOTE: We only use the mhtml: prefix when we have a compound mhtml url (restating above).
- // Therefore Only-File url's become normal url's when accessed via url methods.
- //
- // We fixup REL url's with mhtml url's by doing the following:
- // mhtml:X + REL ==> mhtml:X!REL <- Only-File becomes a compound mhtml url
- // mhtml:X!Y + REL ==> mhtml:X!(Y+REL) <- here, Y+REL is the proper combination of these url's as single entities
- //
- /////////////////////////////////////////////////////////////////////////////////
-
- /* IMsoUrl (iurl) */
- #undef INTERFACE
- #define INTERFACE IMsoUrl
- DECLARE_INTERFACE_(IMsoUrl, IUnknown)
- {
- // ----- IUnknown methods
-
- MSOMETHOD (QueryInterface) (THIS_ REFIID riid, VOID **ppvObj) PURE;
- MSOMETHOD_(ULONG, AddRef) (THIS) PURE;
- MSOMETHOD_(ULONG, Release) (THIS) PURE;
-
- // ----- IMsoUrl methods
-
- /* FDebugMessage method */
- MSODEBUGMETHOD
-
- // is the URL valid? (was it set properly?)
- MSOMETHOD_(BOOL, FValid) (THIS) CONST_METHOD PURE;
-
- // set methods
- //
- // HrSetFromUser - use when you have a url from an external source other than another
- // MsoUrl (for instance from user typing or pasting in from some external source
- // or a url read in from an html file). Param grfurl allows the user to specify
- // special behavior (such as msofurlNoFragment specifying to interpreting the url
- // as having no fragment). Default grfurl is 0.
- // HrSetFromUserRgwch - same as HrSetFromUser but takes a rgwch & cch instead of wz.
- // HrSetFromCanonicalUrl - use only when you have a canonical url retrieved from
- // another MsoUrl. Primarily only used internally, or maybe when writing out a
- // url to a cache in the registry for example. When in doubt, use HrSetFromUser
- // (which does more robustifying and canonicalizing on the input url).
- //
- // NOTE: each set method also has a param cp which is the codepage context of the
- // url (i.e. the codepage of the html source file or CP_ACP for something pasted
- // or the document codepage for something typed in by the user).
- // NOTE: each set method also has a param piurlBase which is a url which represent the
- // base for resolving this url. Urls which are absolute or opaque may safely pass
- // in NULL for the base. Relative url's should however always have a valid base. If
- // a relative url is created without a base, the HrResolve method will assert.
- MSOMETHOD (HrSetFromUser) (THIS_ const WCHAR *wzUrl, DWORD cp, const IMsoUrl *piurlBase, DWORD grfurl) PURE;
- MSOMETHOD (HrSetFromUserRgwch) (THIS_ const WCHAR *rgwchUrl, int cchUrl, DWORD cp, const IMsoUrl *piurlBase, DWORD grfurl) PURE;
- MSOMETHOD (HrSetFromCanonicalUrl) (THIS_ const WCHAR *wzUrl, DWORD cp, const IMsoUrl *piurlBase) PURE;
-
- // lock/unlock methods
- //
- // Use these when you use methods returning LPCWSTR's to ensure the data is not changed
- // while you are accessing it. These methods ensure that no updates are done to the
- // url while you are using it's data. If you don't want to use this, use the methods
- // which copy the url data to a buffer instead (which don't require buffer locking).
- MSOMETHOD_(void, Lock) (THIS) CONST_METHOD PURE;
- MSOMETHOD_(void, Unlock) (THIS) CONST_METHOD PURE;
-
- // get url methods
- //
- // HrGetDisplayForm - use to get the unescaped "friendly" form of a url for displaying to
- // the user (i.e. spaces in the url are actually spaces instead of %20s).
- // HrGetCanonicalForm - use to get the canonical form of the url. This is the standard
- // form of the url.
- // HrGetCustomForm - use to get a url with or without certain components. For instance,
- // use this when you want to get a url without a fragment (if it has one) -- you would
- // pass in grfurlc as (msofurlcComplete & ~msofurlcFragment). Note, this returns the
- // components with their associated delimiters (unlike the component access methods below).
- //
- // NOTE: the HrGet methods all take in a WCHAR buffer wzBuf, whose size is passed in as
- // the input value of pcchBuf. The length of the url put in wzBuf is returned as the
- // output value of pcchBuf. If NULL is passed in for wzBuf, then the requisite size
- // of wzBuf is returned in pcchBuf. In all cases (input/output) pcchBuf is the actual
- // count of characters in wzBuf not including the NULL termination character. So if
- // you query with NULL, you should alloc (*pcchBuf + 1) characters for wzBuf. If wzBuf
- // is NULL and the function succeeds, S_FALSE is returned. If wzBuf is non-NULL and
- // the function succeeds, S_OK is returned.
- //
- // CpGetCodePage - use to retrieve the codepage context of this url.
- // WzCanonicalForm - returns the same value as HrGetCanonicalForm but returns an LPCWSTR
- // pointer to the internal buffer rather than putting it in a user specified buffer.
- // Useful in certain scenarios. Url must be locked while this function is called and
- // while the return value is in use. Returns NULL on error.
- // CchCanonicalForm - returns the count of characters of the url returned by
- // WzCanonicalForm.
- MSOMETHOD (HrGetDisplayForm) (THIS_ WCHAR *wzBuf, int *pcchBuf, DWORD grfurldf) CONST_METHOD PURE;
- MSOMETHOD (HrGetCanonicalForm) (THIS_ WCHAR *wzBuf, int *pcchBuf) CONST_METHOD PURE;
- MSOMETHOD (HrGetCustomForm) (THIS_ DWORD grfurlc, WCHAR *wzBuf, int *pcchBuf, DWORD grfurlcf) CONST_METHOD PURE;
- MSOMETHOD_(DWORD, CpGetCodePage) (THIS) CONST_METHOD PURE;
- MSOMETHOD_(LPCWSTR, WzCanonicalForm) (THIS) CONST_METHOD PURE;
- MSOMETHOD_(int, CchCanonicalForm) (THIS) CONST_METHOD PURE;
-
- // component accessor methods
- //
- // Note: see "Basic url definition" comment above for component definitions.
- //
- // UrlsGetScheme - returns the scheme specified in this url as an MSOURLSCHEME.
- // HrGetScheme - returns the scheme string (without ':' delimiter).
- // HrGetAuthority - returns the authority string
- // (with all subcomponent delimiters but without initial '/' delimiters).
- // HrGetUserName - returns the username string (without '@' delimiter).
- // HrGetPassword - returns the password string (without ':' delimiter).
- // HrGetServer - returns the server string.
- // HrGetPort - returns the port string (without ':' delimiter).
- // HrGetPath - returns the path string (with the initial '/' delimiter if this
- // is a hierarchical url). This may validly return the empty string.
- // (Path contains Dir & FileLeaf).
- // HrGetDir - returns the dir string (with the initial '/' delimiter if this
- // is a hierarchical url). This may validly return the empty string.
- // HrGetFileLeaf - returns the file leaf string (without '/' delimeter).
- // (FileLeaf contains FileName & FileExt).
- // HrGetFileName - returns the file name string (without '/' delimeter).
- // HrGetFileExt - returns the file ext string (without '.' delimiter).
- // HrGetQuery - returns the query string (without '?' delimiter).
- // HrGetFragment - returns the fragment string (without '#' delimiter).
- // (Fragment is also known as Bookmark).
- //
- // NOTE: see HrGet url note above for usage of the HrGet component methods.
- //
- // RgwchScheme - same as HrGetScheme but returns a pointer to the scheme component.
- // RgwchAuthority - same
- // RgwchUserName - same
- // RgwchPassword - same
- // RgwchServer - same
- // RgwchPort - same
- // RgwchPath - same
- // RgwchDir - same
- // RgwchFileLeaf - same
- // RgwchFileName - same
- // RgwchFileExt - same
- // RgwchQuery - same
- // RgwchFragment - same
- //
- // NOTE: the Rgwch returning functions all return NULL if the component does not
- // exist. Param pcch is an output parameter which will contain the length of
- // the returned rgwch pointer. These are not NULL terminated!
- MSOMETHOD_(MSOURLSCHEME, UrlsGetScheme) (THIS) CONST_METHOD PURE;
- MSOMETHOD (HrGetScheme) (THIS_ WCHAR *wzBuf, int *pcchBuf) CONST_METHOD PURE;
- MSOMETHOD (HrGetAuthority) (THIS_ WCHAR *wzBuf, int *pcchBuf) CONST_METHOD PURE;
- MSOMETHOD (HrGetUserName) (THIS_ WCHAR *wzBuf, int *pcchBuf) CONST_METHOD PURE;
- MSOMETHOD (HrGetPassword) (THIS_ WCHAR *wzBuf, int *pcchBuf) CONST_METHOD PURE;
- MSOMETHOD (HrGetServer) (THIS_ WCHAR *wzBuf, int *pcchBuf) CONST_METHOD PURE;
- MSOMETHOD (HrGetPort) (THIS_ WCHAR *wzBuf, int *pcchBuf) CONST_METHOD PURE;
- MSOMETHOD (HrGetPath) (THIS_ WCHAR *wzBuf, int *pcchBuf) CONST_METHOD PURE;
- MSOMETHOD (HrGetDir) (THIS_ WCHAR *wzBuf, int *pcchBuf) CONST_METHOD PURE;
- MSOMETHOD (HrGetFileLeaf) (THIS_ WCHAR *wzBuf, int *pcchBuf) CONST_METHOD PURE;
- MSOMETHOD (HrGetFileName) (THIS_ WCHAR *wzBuf, int *pcchBuf) CONST_METHOD PURE;
- MSOMETHOD (HrGetFileExt) (THIS_ WCHAR *wzBuf, int *pcchBuf) CONST_METHOD PURE;
- MSOMETHOD (HrGetQuery) (THIS_ WCHAR *wzBuf, int *pcchBuf) CONST_METHOD PURE;
- MSOMETHOD (HrGetFragment) (THIS_ WCHAR *wzBuf, int *pcchBuf) CONST_METHOD PURE;
- MSOMETHOD_(LPCWSTR, RgwchScheme) (THIS_ int *pcch) CONST_METHOD PURE;
- MSOMETHOD_(LPCWSTR, RgwchAuthority) (THIS_ int *pcch) CONST_METHOD PURE;
- MSOMETHOD_(LPCWSTR, RgwchUserName) (THIS_ int *pcch) CONST_METHOD PURE;
- MSOMETHOD_(LPCWSTR, RgwchPassword) (THIS_ int *pcch) CONST_METHOD PURE;
- MSOMETHOD_(LPCWSTR, RgwchServer) (THIS_ int *pcch) CONST_METHOD PURE;
- MSOMETHOD_(LPCWSTR, RgwchPort) (THIS_ int *pcch) CONST_METHOD PURE;
- MSOMETHOD_(LPCWSTR, RgwchPath) (THIS_ int *pcch) CONST_METHOD PURE;
- MSOMETHOD_(LPCWSTR, RgwchDir) (THIS_ int *pcch) CONST_METHOD PURE;
- MSOMETHOD_(LPCWSTR, RgwchFileLeaf) (THIS_ int *pcch) CONST_METHOD PURE;
- MSOMETHOD_(LPCWSTR, RgwchFileName) (THIS_ int *pcch) CONST_METHOD PURE;
- MSOMETHOD_(LPCWSTR, RgwchFileExt) (THIS_ int *pcch) CONST_METHOD PURE;
- MSOMETHOD_(LPCWSTR, RgwchQuery) (THIS_ int *pcch) CONST_METHOD PURE;
- MSOMETHOD_(LPCWSTR, RgwchFragment) (THIS_ int *pcch) CONST_METHOD PURE;
-
- // helper functions for file management
- //
- // FIsHttp - does the url point to a http or https address?
- // FIsFtp - does the url point to a ftp address?
- // FIsLocal - does the url point to a dos addressable file address
- // (local drive, mapped drive or UNC drive)?
- // FIsUNC - does the url point to a UNC file address?
- // FIsODMA - does the url point to an ODMA path identifier?
- MSOMETHOD_(BOOL, FIsHttp) (THIS) CONST_METHOD PURE;
- MSOMETHOD_(BOOL, FIsFtp) (THIS) CONST_METHOD PURE;
- MSOMETHOD_(BOOL, FIsLocal) (THIS) CONST_METHOD PURE;
- MSOMETHOD_(BOOL, FIsUNC) (THIS) CONST_METHOD PURE;
- MSOMETHOD_(BOOL, FIsODMA) (THIS) CONST_METHOD PURE;
-
- // local path accessor methods (only work for file: url's)
- //
- // HrGetLocalPath - returns the dos path form of the file: url. Returns error
- // if the url is not a file: url. Behaves the same as HrGet url methods.
- // WzLocalPath - returns a pointer to the dos path form of the file: url. Returns NULL
- // if the url is not a file: url. Behaves the same as WzCanonicalForm.
- // CchLocalPath - returns the count of characters of the dos path returned by
- // WzLocalPath.
- //
- // EXAMPLE 1: "file://c:/mumble/woo.hoo" yields "c:\mumble\woo.hoo".
- // EXAMPLE 2: "file://server/share/mumble/woo.hoo" yields "\\server\share\mumble\woo.hoo".
- MSOMETHOD (HrGetLocalPath) (THIS_ WCHAR *wzBuf, int *pcchBuf) CONST_METHOD PURE;
- MSOMETHOD_(LPCWSTR, WzLocalPath) (THIS) CONST_METHOD PURE;
- MSOMETHOD_(int, CchLocalPath) (THIS) CONST_METHOD PURE;
-
- // FIsEqual - returns TRUE iff the given url is equivalent to this url.
- // (Equivalent to calling FComponentsAreEqual with grfurlc as msofurlcComplete).
- MSOMETHOD_(BOOL, FIsEqual) (THIS_ const IMsoUrl *piurl) CONST_METHOD PURE;
-
- // FComponentsAreEqual - returns TRUE iff the components specifed in grfurlc are equivalent
- // in this url and the given url.
- MSOMETHOD_(BOOL, FComponentsAreEqual) (THIS_ DWORD grfurlc, const IMsoUrl *piurl) CONST_METHOD PURE;
-
- // FSubsumes - returns TRUE iff this url's folder location is a direct
- // hierarchical ancestor of piurl. If two url's subsume each other, they point to
- // the same folder location!
- //
- // EXAMPLE 1: "http://mumble/woo/blah.htm" subsumes "http://mumble/woo/hoo/wunder.bar".
- // EXAMPLE 2: "http://mumble/woo/hoo/wunder.bar" does not subsume "http://mumble/woo/blah.htm".
- // EXAMPLE 3: "http://mumble/woo/blah.htm" does not subsume "ftp://foobarbaz/woo/hoo/wunder.bar".
- // EXAMPLE 4: "http://mumble/woo/hoo/blah.htm" does not subsume "http://mumble/woo/zoo/foo.gif".
- MSOMETHOD_(BOOL, FSubsumes) (THIS_ const IMsoUrl *piurl) CONST_METHOD PURE;
-
- // UrlrGetRelativity - returns the relativity of this url as an MSOURLRELATIVITY.
- MSOMETHOD_(MSOURLRELATIVITY, UrlrGetRelativity) (THIS) CONST_METHOD PURE;
-
- // HrSetRelativity - updates the relativity of this url. Returns S_OK when the
- // url is successfully updated or S_FALSE if the requested url cannot be set
- // because the base url's server or scheme is different. Returns error codes
- // for other failures.
- MSOMETHOD (HrSetRelativity) (THIS_ MSOURLRELATIVITY urlr) PURE;
-
- // HrResolve - resolves this relative url to a full path (by combining it with its base),
- // creates a new url and returns it in ppiurlAbsolute. On success,
- // *ppiurlAbsolute must be Released by the client when done. Calling this on an
- // absolute or opaque url is valid.
- //
- // EXAMPLE 1: this url "foo.bar" combined with base "http://woohoo/sub/hub/spiffy.htm"
- // yields resolved path "http://woohoo/sub/hub/foo.bar".
- // EXAMPLE 2: this url "/foo.bar" combined with base "http://woohoo/sub/hub/spiffy.htm"
- // yields resolved path "http://woohoo/foo.bar".
- // EXAMPLE 3: this url "../foo.bar" combined with base "http://woohoo/sub/hub/spiffy.htm"
- // yields resolved path "http://woohoo/sub/foo.bar".
- MSOMETHOD (HrResolve) (THIS_ IMsoUrl **ppiurlAbsolute) CONST_METHOD PURE;
-
- // HrRebase - rebase this url with a different base url (i.e. link fixup).
- // If the new base url is on a different server this just makes the url absolute.
- // Otherwise it maintains the current relativity state and constructs a new
- // relative url pointing at the same target location. If the relativity state
- // was not maintainable, it returns S_FALSE on success.
- //
- // EXAMPLE 1: this url "foo.bar" with old base "http://woohoo/sub/hub/spiffy.htm"
- // rebased with new base "http://woohoo/sub/spiffy.htm"
- // yields this url "hub/foo.bar".
- // EXAMPLE 2: this url "../foo.bar" with old base "http://woohoo/sub/hub/spiffy.htm"
- // rebased with new base "http://woohoo/sub/spiffy.htm"
- // yields this url "foo.bar".
- // EXAMPLE 3: this url "/foo.bar" with old base "http://woohoo/sub/hub/spiffy.htm"
- // rebased with new base "http://woohoo/sub/spiffy.htm"
- // yields this url "/foo.bar".
- // EXAMPLE 4: this url "foo.bar" with old base "http://woohoo/sub/hub/spiffy.htm"
- // rebased with new base "http://mumble/spiffy.htm"
- // yields this url "http://woohoo/sub/hub/foo.bar".
- MSOMETHOD (HrRebase) (THIS_ const IMsoUrl *piurlBase) PURE;
-
- // HrDownload - downloads this url for local data access. On success, returns the
- // local path to the downloaded file in wzBuf. The size of wzBuf is the
- // input value of pcchBuf, the length of the path put into wzBuf is the
- // output value of pcchBuf. The grfurld param is a set of flags used to
- // control the download (default is 0).
- MSOMETHOD (HrDownload) (THIS_ WCHAR *wzBuf, int *pcchBuf, DWORD grfurld) CONST_METHOD PURE;
-
- // HrUpload - uploads the file specified in wzFile to the location specified
- // by this url. The grfurlu param is a set of flags used to control the
- // upload (default is 0).
- // Returns:
- // S_OK if the file was uploaded successfuly
- // S_FALSE if the user cancel the operation (for example, he/she doesn't
- // want to overwrite an existing file)
- // E_FAIL generic failure
- MSOMETHOD (HrUpload) (THIS_ const WCHAR *wzFile, DWORD grfurlu) CONST_METHOD PURE;
-
- // HrDelete - deletes the file specified by this url.
- MSOMETHOD (HrDelete) (THIS) CONST_METHOD PURE;
-
- // FExists - returns TRUE iff the file exists. Param grfurle determines
- // which kind of validation to perform (default is 0 which means do not
- // check web servers (i.e. http/ftp) & returns FALSE if this url points
- // to a web server location - to validate against web servers pass the
- // msofurleCheckServers flag).
- MSOMETHOD_(BOOL, FExists) (THIS_ DWORD grfurle) CONST_METHOD PURE;
-
- // HrGetBase - returns the base url of this url in ppiurlBase.
- // Caller must release the returned url when done.
- MSOMETHOD (HrGetBase) (THIS_ const IMsoUrl **ppiurlBase) CONST_METHOD PURE;
-
- // FIsMhtml - does the url point to an mhtml file, and in the form "mhtml:X[!Y]" ?
- MSOMETHOD_(BOOL, FIsMhtml) (THIS) CONST_METHOD PURE;
-
- // Returns the reference to the bodypart this mhtml url is referring to
- MSOMETHOD_(LPCWSTR, WzMhtmlBodypart) (THIS) CONST_METHOD PURE;
-
- // Returns the cch of the reference to the bodypart this mhtml url is referring to
- MSOMETHOD_(int, CchMhtmlBodypart) (THIS) CONST_METHOD PURE;
-
- MSOMETHOD_(BPSC, BpscBulletProof) (THIS_ MSOBPCB *pmsobpcb) PURE;
-
- MSOMETHOD_(ULONG, Free) (THIS) PURE;
- };
-
-
- #ifndef __cplusplus
- // IMsoUrl wrapper/convenience functions for C clients
- #define IMsoUrl_QueryInterface(this, riid, ppvObj) \
- ( (this)->lpVtbl->QueryInterface(this, riid, ppvObj) )
- #define IMsoUrl_AddRef(this) \
- ( (this)->lpVtbl->AddRef(this) )
- #define IMsoUrl_Release(this) \
- ( (this)->lpVtbl->Free(this) )
- #define IMsoUrl_FValid(this) \
- ( (this)->lpVtbl->FValid(this) )
- #define IMsoUrl_HrSetFromUser(this, wzUrl, cp, piurlBase, grfurl) \
- ( (this)->lpVtbl->HrSetFromUser(this, wzUrl, cp, piurlBase, grfurl) )
- #define IMsoUrl_HrSetFromUserRgwch(this, rgwchUrl, cchUrl, cp, piurlBase, grfurl) \
- ( (this)->lpVtbl->HrSetFromUserRgwch(this, rgwchUrl, cchUrl, cp, piurlBase, grfurl) )
- #define IMsoUrl_HrSetFromCanonicalUrl(this, wzUrl, cp, piurlBase) \
- ( (this)->lpVtbl->HrSetFromCanonicalUrl(this, wzUrl, cp, piurlBase) )
- #define IMsoUrl_Lock(this) \
- ( (this)->lpVtbl->Lock(this) )
- #define IMsoUrl_Unlock(this) \
- ( (this)->lpVtbl->Unlock(this) )
- #define IMsoUrl_HrGetDisplayForm(this, wzBuf, pcchBuf, grfurldf) \
- ( (this)->lpVtbl->HrGetDisplayForm(this, wzBuf, pcchBuf, grfurldf) )
- #define IMsoUrl_HrGetCanonicalForm(this, wzBuf, pcchBuf) \
- ( (this)->lpVtbl->HrGetCanonicalForm(this, wzBuf, pcchBuf) )
- #define IMsoUrl_HrGetCustomForm(this, grfurlc, wzBuf, pcchBuf, grfurlcf) \
- ( (this)->lpVtbl->HrGetCustomForm(this, grfurlc, wzBuf, pcchBuf, grfurlcf) )
- #define IMsoUrl_CpGetCodePage(this) \
- ( (this)->lpVtbl->CpGetCodePage(this) )
- #define IMsoUrl_WzCanonicalForm(this) \
- ( (this)->lpVtbl->WzCanonicalForm(this) )
- #define IMsoUrl_CchCanonicalForm(this) \
- ( (this)->lpVtbl->CchCanonicalForm(this) )
- #define IMsoUrl_UrlsGetScheme(this) \
- ( (this)->lpVtbl->UrlsGetScheme(this) )
- #define IMsoUrl_HrGetScheme(this, wzBuf, pcchBuf) \
- ( (this)->lpVtbl->HrGetScheme(this, wzBuf, pcchBuf) )
- #define IMsoUrl_HrGetAuthority(this, wzBuf, pcchBuf) \
- ( (this)->lpVtbl->HrGetAuthority(this, wzBuf, pcchBuf) )
- #define IMsoUrl_HrGetUserName(this, wzBuf, pcchBuf) \
- ( (this)->lpVtbl->HrGetUserName(this, wzBuf, pcchBuf) )
- #define IMsoUrl_HrGetPassword(this, wzBuf, pcchBuf) \
- ( (this)->lpVtbl->HrGetPassword(this, wzBuf, pcchBuf) )
- #define IMsoUrl_HrGetServer(this, wzBuf, pcchBuf) \
- ( (this)->lpVtbl->HrGetServer(this, wzBuf, pcchBuf) )
- #define IMsoUrl_HrGetPort(this, wzBuf, pcchBuf) \
- ( (this)->lpVtbl->HrGetPort(this, wzBuf, pcchBuf) )
- #define IMsoUrl_HrGetPath(this, wzBuf, pcchBuf) \
- ( (this)->lpVtbl->HrGetPath(this, wzBuf, pcchBuf) )
- #define IMsoUrl_HrGetDir(this, wzBuf, pcchBuf) \
- ( (this)->lpVtbl->HrGetDir(this, wzBuf, pcchBuf) )
- #define IMsoUrl_HrGetFileLeaf(this, wzBuf, pcchBuf) \
- ( (this)->lpVtbl->HrGetFileLeaf(this, wzBuf, pcchBuf) )
- #define IMsoUrl_HrGetFileName(this, wzBuf, pcchBuf) \
- ( (this)->lpVtbl->HrGetFileName(this, wzBuf, pcchBuf) )
- #define IMsoUrl_HrGetFileExt(this, wzBuf, pcchBuf) \
- ( (this)->lpVtbl->HrGetFileExt(this, wzBuf, pcchBuf) )
- #define IMsoUrl_HrGetQuery(this, wzBuf, pcchBuf) \
- ( (this)->lpVtbl->HrGetQuery(this, wzBuf, pcchBuf) )
- #define IMsoUrl_HrGetFragment(this, wzBuf, pcchBuf) \
- ( (this)->lpVtbl->HrGetFragment(this, wzBuf, pcchBuf) )
- #define IMsoUrl_RgwchScheme(this, pcch) \
- ( (this)->lpVtbl->RgwchScheme(this, pcch) )
- #define IMsoUrl_RgwchAuthority(this, pcch) \
- ( (this)->lpVtbl->RgwchAuthority(this, pcch) )
- #define IMsoUrl_RgwchUserName(this, pcch) \
- ( (this)->lpVtbl->RgwchUserName(this, pcch) )
- #define IMsoUrl_RgwchPassword(this, pcch) \
- ( (this)->lpVtbl->RgwchPassword(this, pcch) )
- #define IMsoUrl_RgwchServer(this, pcch) \
- ( (this)->lpVtbl->RgwchServer(this, pcch) )
- #define IMsoUrl_RgwchPort(this, pcch) \
- ( (this)->lpVtbl->RgwchPort(this, pcch) )
- #define IMsoUrl_RgwchPath(this, pcch) \
- ( (this)->lpVtbl->RgwchPath(this, pcch) )
- #define IMsoUrl_RgwchFileLeaf(this, pcch) \
- ( (this)->lpVtbl->RgwchFileLeaf(this, pcch) )
- #define IMsoUrl_RgwchFileExt(this, pcch) \
- ( (this)->lpVtbl->RgwchFileExt(this, pcch) )
- #define IMsoUrl_RgwchQuery(this, pcch) \
- ( (this)->lpVtbl->RgwchQuery(this, pcch) )
- #define IMsoUrl_RgwchFragment(this, pcch) \
- ( (this)->lpVtbl->RgwchFragment(this, pcch) )
- #define IMsoUrl_FIsHttp(this) \
- ( (this)->lpVtbl->FIsHttp(this) )
- #define IMsoUrl_FIsFtp(this) \
- ( (this)->lpVtbl->FIsFtp(this) )
- #define IMsoUrl_FIsLocal(this) \
- ( (this)->lpVtbl->FIsLocal(this) )
- #define IMsoUrl_FIsUNC(this) \
- ( (this)->lpVtbl->FIsUNC(this) )
- #define IMsoUrl_FIsODMA(this) \
- ( (this)->lpVtbl->FIsODMA(this) )
- #define IMsoUrl_HrGetLocalPath(this, wzBuf, pcchBuf) \
- ( (this)->lpVtbl->HrGetLocalPath(this, wzBuf, pcchBuf) )
- #define IMsoUrl_WzLocalPath(this) \
- ( (this)->lpVtbl->WzLocalPath(this) )
- #define IMsoUrl_CchLocalPath(this) \
- ( (this)->lpVtbl->CchLocalPath(this) )
- #define IMsoUrl_FIsEqual(this, piurl) \
- ( (this)->lpVtbl->FIsEqual(this, piurl) )
- #define IMsoUrl_FComponentsAreEqual(this, grfurlc, piurl) \
- ( (this)->lpVtbl->FComponentsAreEqual(this, grfurlc, piurl) )
- #define IMsoUrl_FSubsumes(this, piurl) \
- ( (this)->lpVtbl->FSubsumes(this, piurl) )
- #define IMsoUrl_UrlrGetRelativity(this) \
- ( (this)->lpVtbl->UrlrGetRelativity(this) )
- #define IMsoUrl_HrSetRelativity(this, urlr) \
- ( (this)->lpVtbl->HrSetRelativity(this, urlr) )
- #define IMsoUrl_HrResolve(this, ppiurlAbsolute) \
- ( (this)->lpVtbl->HrResolve(this, ppiurlAbsolute) )
- #define IMsoUrl_HrRebase(this, piurlBase) \
- ( (this)->lpVtbl->HrRebase(this, piurlBase) )
- #define IMsoUrl_HrDownload(this, wzBuf, pcchBuf, grfurld) \
- ( (this)->lpVtbl->HrDownload(this, wzBuf, pcchBuf, grfurld) )
- #define IMsoUrl_HrUpload(this, wzFile, grfurlu) \
- ( (this)->lpVtbl->HrUpload(this, wzFile, grfurlu) )
- #define IMsoUrl_HrDelete(this) \
- ( (this)->lpVtbl->HrDelete(this) )
- #define IMsoUrl_FExists(this, grfurle) \
- ( (this)->lpVtbl->FExists(this, grfurle) )
- #define IMsoUrl_HrGetBase(this, ppiurlBase) \
- ( (this)->lpVtbl->HrGetBase(this, ppiurlBase) )
- #define IMsoUrl_FIsMhtml(this) \
- ( (this)->lpVtbl->FIsMhtml(this) )
- #define IMsoUrl_WzMhtmlBodypart(this) \
- ( (this)->lpVtbl->WzMhtmlBodypart(this) )
- #define IMsoUrl_CchMhtmlBodypart(this) \
- ( (this)->lpVtbl->CchMhtmlBodypart(this) )
- #endif // __cplusplus
-
-
- // Url Creation APIs
- //
- // MsoHrCreateUrl - creates an unset url in ppiurl.
- // MsoHrCreateUrlFromUser - same as calling MsoHrCreateUrl
- // followed by IMsoUrl::HrSetFromUser.
- // MsoHrCreateUrlFromUserRgwch - same as calling MsoHrCreateUrl
- // followed by IMsoUrl::HrSetFromUserRgwch.
- // MsoHrCreateUrlFromCanonicalUrl - same as calling MsoHrCreateUrl
- // followed by IMsoUrl::HrSetFromCanonicalUrl.
- // MsoHrCloneUrl - creates a new copy of the given url
- MSOAPI_(HRESULT) MsoHrCreateUrl(interface IMsoUrl **ppiurl);
- MSOAPI_(HRESULT) MsoHrCreateUrlFromUser(interface IMsoUrl **ppiurl,
- const WCHAR *wzUrl, DWORD cp, const IMsoUrl *piurlBase, DWORD grfurl);
- MSOAPI_(HRESULT) MsoHrCreateUrlFromUserRgwch(interface IMsoUrl **ppiurl,
- const WCHAR *wzUrl, int cchUrl, DWORD cp, const IMsoUrl *piurlBase, DWORD grfurl);
- MSOAPIX_(HRESULT) MsoHrCreateUrlFromCanonicalUrl(interface IMsoUrl **ppiurl,
- const WCHAR *wzUrl, DWORD cp, const IMsoUrl *piurlBase);
- MSOAPI_(HRESULT) MsoHrCloneUrl(interface IMsoUrl **ppiurl, const IMsoUrl *piurl);
-
-
- // Some useful path manipulation APIs
- //
- // MsoFIsPathSep - returns TRUE iff the character is a recognized path separator
- // MsoRgwchPathSepIndex - returns a ptr to the first path sep character
- // MsoRgwchPathSepIndexRight - returns a ptr to the last path sep character
- __inline MsoFIsPathSep(WCHAR wch) { return wch == L'/' || wch == L'\\'; };
- MSOAPIX_(WCHAR*) MsoRgwchPathSepIndex(const WCHAR *rgwch, int cch);
- MSOAPI_(WCHAR*) MsoRgwchPathSepIndexRight(const WCHAR *rgwch, int cch);
-
- MSOAPIX_(BOOL) MsoFWzIsResUrl(const WCHAR *wzURL);
-
- // Path buffer constants
- #define MSO_MAX_PATH INTERNET_MAX_URL_LENGTH
- #define MSO_CB_MAX_PATH (MSO_MAX_PATH*sizeof(WCHAR))
- #define MSO_MAX_URL_PATH INTERNET_MAX_URL_LENGTH
- #define MSO_CB_MAX_URL_PATH (MSO_MAX_URL_PATH*sizeof(WCHAR))
- #define MSO_MAX_LOCAL_PATH MAX_PATH
- #define MSO_CB_MAX_LOCAL_PATH (MSO_MAX_LOCAL_PATH*sizeof(WCHAR))
-
-
- //////////////////////////////////////////////////////////////////////////
- //
- // OPEN ISSUES:
- //
- // 1. We don't handle default ports in the equivalence comparison.
- // 2. We don't handle "http://server.com" & "http://www.server.com"
- // equivalence correctly.
- //
- //////////////////////////////////////////////////////////////////////////
-
- #endif // MSOURL_H
-
-
-
-
-
-
-
-
-
-
-