/**************************************************************************** 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 := ://[/][?][#] // authority := [[:]@][:] // path := [/[fileleaf]] // fileleaf := [.] // // opaque url := :[?][#] // // 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