Functions

Functions


This section describes the functions included in monikers, URLs, security zones, and pluggable protocols.
CoGetClassObjectFromURL
CoInternetCombineUrl
CoInternetCompareUrl
CoInternetCreateSecurityManager
CoInternetCreateZoneManager
CoInternetGetProtocolFlags
CoInternetGetSecurityURL
CoInternetGetSession
CoInternetParseUrl
CoInternetQueryInfo
CopyBindInfo
CopyStgMedium
CreateAsyncBindCtx
CreateAsyncBindCtxEx
CreateFormatEnumerator
CreateURLBinding
CreateURLMoniker
FindMediaType
FindMediaTypeClass
FindMimeFromData
GetClassURL
IsAsyncMoniker
IsValidURL
MkParseDisplayNameEx
ObtainUserAgentString
RegisterBindStatusCallback
RegisterFormatEnumerator
RegisterMediaTypeClass
RegisterMediaTypes
ReleaseBindInfo
RevokeBindStatusCallback
RevokeFormatEnumerator
URLDownloadToCacheFile
URLDownloadToFile
UrlMkGetSessionOption
UrlMkSetSessionOption
URLOpenBlockingStream
URLOpenPullStream
URLOpenStream

CoGetClassObjectFromURL

STDAPI CoGetClassObjectFromURL(
    [in] REFCLSID rclsid,
    [in] LPCWSTR szCodeURL,
    [in] DWORD dwFileVersionMS,
    [in] DWORD dwFileVersionLS,
    [in] LPCWSTR szContentType,
    [in] LPBINDCTX pBindCtx,
    [in] DWORD dwClsContext,
    [in] LPVOID pvReserved,
    [in] REFIID riid,
    [out] VOID ppv * *
);

Returns a factory object for a given CLSID.

rclsid
CLSID of the ActiveX™ object to be installed. If the value is CLSID_NULL, szContentType is used to determine the CLSID.
szCodeURL
URL pointing to the code for the ActiveX object.
dwFileVersionMS
Major version number for the object to be installed. If this value and the value for dwFileVersionLS are both 0xFFFFFFFF, it is assumed that the latest version of the code is always desired. This means that Internet Component Download will always attempt to download new code.
dwFileVersionLS
Minor version number for the object to be installed. If this value and the value for dwFileVersionMS are both 0xFFFFFFFF, it is assumed that the latest version of the code is always desired. This means that Internet Component Download will always attempt to download new code.
szContentType
MIME type to be understood by the installed ActiveX object. If rclsid is CLSID_NULL, this string is used to determine the CLSID of the object to be installed. Note that this parameter is useful only when trying to download a viewer for a particular media type, when the MIME type of media is known but the CLSID is not.
pBindCtx
Bind context to use for downloading/installing component code. Register IBindStatusCallback in this bind context to receive callbacks during the download and installation process.
dwClsContext
Values taken from the CLSCTX enumeration specifying the execution context for the class object.
pvReserved
Reserved. Must be set to NULL.
riid
Interface to obtain on the factory object. Usually, this interface is IClassFactory.
ppv
Upon return for synchronous calls, the pointer in which to store the interface pointer.

If no CLSID is specified (CLSID_NULL), this function chooses the appropriate CLSID for interpreting the Internet mail extensions (MIME) type specified in szContentType. If the desired object is installed on the system, it is instantiated. Otherwise, the necessary code is downloaded and installed from the location specified in szCodeURL.

CoInternetCombineUrl

STDAPI CoInternetCombineUrl(
    LPCWSTR pwzBaseUrl,
    LPCWSTR pwzRelativeUrl,
    DWORD dwCombineFlags,
    LPWSTR pwzResult,
    DWORD cchResult,
    DWORD *pcchResult,
    DWORD dwReserved
);

Combines a base and relative URL into a full URL.

pwzBaseUrl
String value containing the base URL.
pwzRelativeUrl
String value containing the relative URL.
dwCombineFlags
Double-word value that controls the combining process.
pwzResult
String variable where the full URL will be stored.
cchResult
Double-word value that contains the size of the buffer.
pcchResult
Address of a double-word value to store the size of the information stored in the buffer.
dwReserved
Reserved. Must be set to zero.

CoInternetCompareUrl

STDAPI CoInternetCompareUrl(
    [in] LPCWSTR pwzUrl1,
    [in] LPCWSTR pwzUrl2,
    [in] DWORD dwCompareFlags
);

Compares two URLs and determines if they are equal.

pwzUrl1
String value that contains the first URL.
pwzUrl2
String value that contains the second URL.
dwCompareFlags
Double-word value that controls how the comparison should be done. Set to TRUE to ignore slashes, FALSE otherwise.

CoInternetCreateSecurityManager

Obsolete. Do not use.

CoInternetCreateZoneManager

Obsolete. Do not use.

CoInternetGetProtocolFlags

STDAPI CoInternetGetProtocolFlags(
    LPCWSTR pwzUrl,
    DWORD *pdwFlags,
    DWORD dwReserved
);

Retrieves the protocol flags for a specified URL.

pwzUrl
String value containing the URL.
pdwFlags
Address of a double-word value that contains the protocol flags.
dwReserved
Reserved. Must be set to zero.

CoInternetGetSecurityURL

HRESULT CoInternetGetSecurityURL(
    LPCWSTR pwzUrl,
    LPWSTR *ppwzSecUrl,
    PSUACTION psuAction,
    DWORD dwReserved
);

Retrieves the security URL for the specified URL.

pwzUrl
String value that contains the URL.
ppwzSecUrl
Address of the string value that contains the security URL.
psuAction
PSUACTION value that determines what information is returned.
dwReserved
Reserved. Must be set to zero.

CoInternetGetSession

STDAPI CoInternetGetSession(
    DWORD dwSessionMode,
    IInternetSession **ppIInternetSession,
    DWORD dwReserved
);

Creates a session that allows temporary asynchronous pluggable protocols to be implemented and returns the IInternetSession interface of the session.

dwSessionMode
Reserved. Must be set to zero.
ppIInternetSession
Address of the pointer to the IInternetSession interface.
dwReserved
Reserved. Must be set to zero.

CoInternetParseUrl

STDAPI CoInternetParseUrl(
    LPCWSTR pwzUrl,
    PARSEACTION ParseAction,
    DWORD dwFlags,
    LPWSTR pszResult,
    DWORD cchResult,
    DWORD *pcchResult,
    DWORD dwReserved
);

Parses URLs. (This is a helper API.)

pwzUrl
String value containing the URL to parse.
ParseAction
PARSEACTION value that determines the information to be parsed from the URL.
dwFlags
Double-word value that controls the parsing operation.
pwzResult
String value that contains the information parsed from the URL.
cchResult
Double-word value that contains the size of the buffer.
pcchResult
Address of a double-word value that contains the size of the information stored in the buffer.
dwReserved
Reserved. Must be set to zero.

CoInternetQueryInfo

STDAPI CoInternetQueryInfo(
    LPCWSTR pwzUrl,
    QUERYOPTION QueryOption,
    DWORD dwQueryFlags,
    LPVOID pvBuffer,
    DWORD cbBuffer,
    DWORD *pcbBuffer,
    DWORD dwReserved
);

Retrieves information related to the specified URL.

pwzUrl
String value containing the URL.
QueryOption
QUERYOPTION value that indicates what option to query.
dwQueryFlags
Double-word value containing the query flags.
pvBuffer
Address of the buffer where the information will be stored.
cbBuffer
Double-word value containing the size of the buffer.
pcbBuffer
Address of a double-word variable where the size of the requested information will be stored.
dwReserved
Reserved. Must be set to zero.

CopyBindInfo

HRESULT CopyBindInfo(
    const BINDINFO *pcbiSrc,
    BINDINFO *pcbiDest
);

Copies the given BINDINFO structure.

pcbiSrc
Address of the BINDINFO structure to be copied.
pbiDest
Address of the BINDINFO structure to store the copy.

CopyStgMedium

HRESULT CopyStgMedium(
    const STGMEDIUM *pcstrgmedSrc,
    STGMEDIUM *pstgmedDest
);

Copy the given STGMEDIUM structure.

pcstgmedSrc
Address of the STGMEDIUM structure to copy.
pstgmedDest
Address of the STGMEDIUM structure to store the copy in.

CreateAsyncBindCtx

HRESULT CreateAsyncBindCtx(
    [in] DWORD dwReserved,
    [in] IBindStatusCallback *pbsc,
    [in] IEnumFORMATETC *penumfmtetc,
    [out] IBindCtx **ppbc
);

Creates an asynchronous bind context for use with asynchronous monikers.

dwReserved
Reserved for future use; must be zero.
pbsc
Address of the IBindStatusCallback interface used for receiving data availability and progress notification.
penumfmtetc
Address of the IEnumFORMATETC interface that can be used to enumerate formats for format negotiation during binding. This parameter can be NULL, in which case the calling application is not interested in format negotiation during binding, and the default format of the object will be bound to it.
ppbc
Indirect pointer to the IBindCtx interface for the new bind context.

This function automatically registers the IBindStatusCallback and the IEnumFORMATETC interfaces with the bind context. If the client does not want to receive certain notifications, it can choose to implement those callback methods as empty function stubs (returning E_NOTIMPL), and they should not be called.

The RegisterBindStatusCallback function can also be used to register callback interfaces in the bind context.

See also IBindStatusCallback, RegisterBindStatusCallback

CreateAsyncBindCtxEx

STDAPI CreateAsyncBindCtxEx(
    IBindCtx *pbc,
    DWORD dwOptions,
    IBindStatusCallback *pBSCb,
    IEnumFORMATETC *pEnum,
    IBindCtx **ppBC,
    DWORD reserved
);

Creates an asynchronous bind context for use with asynchronous monikers.

pbc
Address of the IBindCtx interface.
dwOptions
Double-word value that contains the option values.
pBSCb
Address of the IBindStatusCallback interface.
pEnum
Address of the IEnumFORMATETC interface.
ppBC
Address of a pointer to the IBindCtx interface that is returned.
reserved
Reserved. Must be set to zero.

CreateFormatEnumerator

HRESULT CreateFormatEnumerator(
    [in] UINT cfmtetc,
    [in] FORMATETC *rgfmtetc,
    [out] IEnumFORMATETC **ppenumfmtetc
);

Creates an object that implements IEnumFORMATETC over a static array of FORMATETC structures.

cfmtetc
Number of FORMATETC structures in the static array specified by the rgfmtetc parameter. The cfmtetc parameter cannot be zero.
rgfmtetc
Address of a static array of FORMATETC structures.
ppenumfmtetc
Indirect pointer to the IEnumFORMATETC interface on the enumerator object.

See also RegisterFormatEnumerator, RevokeFormatEnumerator

CreateURLBinding

STDAPI CreateURLBinding(
    LPCWSTR lpszUrl,
    IBindCtx *pbc,
    IBinding **ppBdg
);

Creates an IBinding interface associated with the specified URL.

lpszUrl
String value that contains the URL.
pbc
Address of the IBindCtx interface associated with the URL.
ppBdg
Address of a pointer to the IBinding interface that is created.

CreateURLMoniker

HRESULT CreateURLMoniker(
    [in] IMoniker *pmkContext,
    [in] LPWSTR szURL,
    [out] IMoniker **ppmk
);

Creates a URL moniker from either a full URL string or from a base context URL moniker and a partial URL string.

pmkContext
Address of the IMoniker interface for the URL moniker to use as the base context when the szURL parameter is a partial URL string. The pmkContext parameter can be NULL.
szURL
Display name to be parsed.
ppmk
Indirect pointer to an IMoniker interface for the new URL moniker.

FindMediaType

STDAPI FindMediaType(
    LPCSTR rgszTypes,
    CLIPFORMAT *rgcfTypes
);

Retrieves the media type.

rgszTypes
String value that contains the media types.
rgcfTypes
Address of the CLIPFORMAT value.

FindMediaTypeClass

HRESULT FindMediaTypeClass(
    [in] LPBC pbc,
    [in] LPCSTR szType,
    [out] CLSID *pclsID,
    [in] DWORD dwReserved
);

Retrieves the CLSID for the specified media type.

pbc
Address of the bind context on which the media type is registered.
szType
String identifying the media types. This parameter cannot be NULL.
pclsID
Address of the CLSID corresponding to the specified media types in szType.
dwReserved
Reserved for future use; must be zero.

See also RegisterMediaTypeClass, RegisterMediaTypes

FindMimeFromData

FindMimeFromData(
    LPBC pBC,
    LPCWSTR pwzUrl,
    LPVOID pBuffer,
    DWORD cbSize,
    LPCWSTR pwzMimeProposed,
    DWORD dwMimeFlags,
    LPWSTR *ppwzMimeOut,
    DWORD dwReserved
);

Determines the MIME type from the data provided.

pBC
Address of the bind context. Can be set to NULL.
pwzUrl
String value that contains the URL of the data. Can be set to NULL if pBuffer contains the data to be sniffed.
pBuffer
Address of the buffer containing the data to be sniffed. Can be set to NULL if pwzUrl contains a valid URL.
cbSize
Double-word value that contains the size of the buffer.
pwzMimeProposed
String value containing the proposed MIME type. Can be set to NULL.
dwMimeFlags
Not currently defined. Must be set to zero.
ppwzMimeOut
Address of a string value containing the suggested MIME type.
dwReserved
Reserved. Must be set to zero.

GetClassURL

STDAPI GetClassURL(
    LPCWSTR szURL,
    CLSID *pClsID
);

Gets the class identification associated with the URL.

szURL
String that contains the URL.
pClsID
Address of the class identification associated with the URL.

IsAsyncMoniker

HRESULT IsAsyncMoniker(
    [in] IMoniker *pmk
);

Tests if a moniker supports asynchronous binding.

pmk
Address of the IMoniker interface on the moniker to be tested.

A moniker implementation indicates that it is asynchronous by supporting the IAsyncMoniker interface, an empty interface that is just an implementation of IUnknown. The IsAsyncMoniker function tests for support of IAsyncMoniker and also handles composite monikers correctly.

See also IAsyncMoniker

IsValidURL

HRESULT IsValidURL(
    [in] LPBC pBC,
    [in] LPCWSTR szURL,
    [in] DWORD dwReserved
);

Determines if a specified string is a valid URL.

pBC
Address of the IBindCtx interface. Optional and currently ignored. Should be set to NULL.
szURL
URL whose validity is to be checked. For the purposes of this function, a valid URL must specify an absolute path.
dwReserved
Reserved for future use. Must be set to zero.

Relative URLs are not considered valid by this function.

MkParseDisplayNameEx

HRESULT MkParseDisplayNameEx(
    [in] IBindCtx*pbc,
    [in] LPWSTR  szDisplayName,
    [out] ULONG *pcchEaten,
    [out] IMoniker **ppmk
);

Given a string, returns a moniker of the object that the string denotes.

pbc
Address of the bind context in which to accumulate bound objects.
szDisplayName
Display name to be parsed.
pcchEaten
Address of the number of characters of the display name that were successfully parsed. Most useful on syntax error, when a nonzero value is often returned and therefore a subsequent call to MkParseDisplayNameEx with the same pbc parameter and a shortened szDisplayName parameter should return a valid moniker.
ppmk
Indirect pointer to the resulting moniker.

See also IParseDisplayName

ObtainUserAgentString

HRESULT ObtainUserAgentString(
    DWORD dwOption,
    LPCSTR pcszUAOut,
    DWORD *cbSize
);

Retrieve the user agent string in use.

dwOption
Reserved. Must be set to zero.
pcszUAOut
String value that contains the user agent string currently being used.
cbSize
Address of a unsigned long integer value that contains the length of the string.

RegisterBindStatusCallback

HRESULT RegisterBindStatusCallback(
    [in] IBindCtx *pbc,
    [in] IBindStatusCallback *pbsc,
    [out] IBindStatusCallback **ppbscPrevious,
    [in] DWORD  dwReserved
);

Registers a callback interface with an existing bind context.

pbc
Address of the IBindCtx interface to receive callbacks from.
pbsc
Address of the IBindStatusCallback interface implementation to be registered.
ppbscPrevious
Address of a pointer to a previously registered instance of IBindStatusCallback.
dwReserved
Reserved for future use.

The IBindStatusCallback interface passed into the pbsc parameter will receive callbacks on any binding operations using the bind context passed into the pbc paramter.

Only the last IBindStatusCallback interface that was registered to a particular bind context will receive callbacks. The implementation of IBindStatusCallback could pass the callbacks it receives to the previously registered IBindStatusCallback interface using the address of a pointer in the ppbscPrevious paramter.

See also IBindStatusCallback, RevokeBindStatusCallback

RegisterFormatEnumerator

HRESULT RegisterFormatEnumerator(
    [in] LPBC pBC,
    [in] IEnumFORMATETC *pEFetc,
    [in] DWORD  reserved
);

Registers a FORMATETC enumerator object onto the given bind context.

pBC
Address of the IBindCtx interface for the bind context on which to register the enumerator.
pEFetc
Address of the IEnumFORMATETC interface for the enumerator to be registered.
reserved
Reserved. Must be set to zero.

The enumerator is used to determine what format types are preferred for the bind operation. Typically, the pEFetc parameter would be the pointer obtained through a call to CreateFormatEnumerator.

See also CreateFormatEnumerator, RevokeFormatEnumerator

RegisterMediaTypeClass

HRESULT RegisterMediaTypeClass(
    [in] LPBC pbc,
    [in] UINT ctypes,
    [in] LPCSTR  *rgszTypes,
    [in] CLSID  *rgclsID,
    [in] DWORD  dwReserved
);

Registers a mapping of media types to CLSIDs to override the default mapping specified in the registry. The new mapping is used in calls to IMoniker::BindToObject when binding objects in the specified bind context.

pbc
Address of the IBindCtx interface for the bind context in which the media types are to be registered.
ctypes
Number of media type strings in the rgszTypes array. This parameter cannot be zero.
rgszTypes
Address of an array of strings identifying the media types to be registered. None of these strings can be NULL.
rgclsID
Address of an array of CLSIDs corresponding to the media type strings in the rgszTypes array.
dwReserved
Reserved for future use; must be zero.

This function is primarily used by moniker clients calling IMoniker::BindToObject to override the default registry mapping between MIME types and CLSIDs. In most cases, the default mapping provided in the registry is used. However, a Web browser might want the CLSID for its HTML viewer to be associated with .txt files without changing the default registry association for text files. The override is used for all bind operations using the specified bind context.

See also RegisterMediaTypes

RegisterMediaTypes

HRESULT RegisterMediaTypes (
    [in] UINT  ctypes,
    [in] LPCSTR *rgszTypes,
    [out] CLIPFORMAT *rgcfTypes
);

Registers media type strings.

ctypes
Number of media type strings in the rgszTypes array. This parameter cannot be zero.
rgszTypes
Address of an array of strings identifying the media types to be registered. None of the strings in the array can be NULL. Can be one of the values in the following list.
Value Meaning
CF_NULL 0
SZ_URLCONTEXT (L"URL Context")
CFSTR_MIME_FRACTALS (TEXT("application/fractals"))
CFSTR_MIME_POSTSCRIPT (TEXT("application/postscript"))
CFSTR_MIME_RAWDATA (TEXT("application/octet"))
CFSTR_MIME_AIIF (TEXT("audio/aiif"))
CFSTR_MIME_BASICAUDIO (TEXT("audio/basic"))
CFSTR_MIME_WAV (TEXT("audio/wav"))
CFSTR_MIME_X_AIIF (TEXT("audio/x-aiif"))
CFSTR_MIME_X_REALAUDIO (TEXT("audio/x-pn-realaudio"))
CFSTR_MIME_X_WAV (TEXT("audio/x-wav"))
CFSTR_MIME_BMP (TEXT("image/bmp"))
CFSTR_MIME_GIF (TEXT("image/gif"))
CFSTR_MIME_JPEG (TEXT("image/jpeg"))
CFSTR_MIME_TIFF (TEXT("image/tiff"))
CFSTR_MIME_XBM (TEXT("image/xbm"))
CFSTR_MIME_X_BITMAP (TEXT("image/x-bitmap"))
CFSTR_MIME_HTML (TEXT("text/html"))
CFSTR_MIME_TEXT (TEXT("text/plain"))
CFSTR_MIME_AVI (TEXT("video/avi"))
CFSTR_MIME_MPEG (TEXT("video/mpeg"))
CFSTR_MIME_QUICKTIME TEXT("video/quicktime"))
CFSTR_MIME_X_MSVIDEO (TEXT("video/x-msvideo"))
CFSTR_MIME_X_SGI_MOVIE (TEXT("video/x-sgi-movie"))
rgcfTypes
Address of an array of the 32-bit values assigned to corresponding media types in rgszTypes.

See also RegisterMediaTypeClass

© 1997 Microsoft Corporation. All rights reserved. Terms of Use.