URL Open Stream Functions

URL Open Stream (UOS) functions are ActiveX™ extensions to the Win32 API. They combine the familiarity of C-style programming with the power of COM. Yet using UOS functions requires knowledge of no more than two COM interfaces, IStream and IBindStatusCallback. UOS functions work equally well inside an ActiveX framework (for example, a component, a document or frame window, a subcomponent, or a scriptable object) or in a generic Internet context.

Every UOS function works in the same basic way: the caller implements an IBindStatusCallback interface (optional in some cases), then calls the function. The URLOpenStream and URLOpenPullStream functions require the caller to be on a thread that has a message loop (GetMessage/DispatchMessage). In the case of an ActiveX component, a message loop is a given if one of these functions is called from the main thread. For a stand-alone application without a user interface, a message loop is still necessary to use these functions.

With the UOS functions, you can:

• Download a URL to a file with a single function call. You can optionally get progress notifications in the background.
• Create a blocking-type stream (see Asynchronous Storage) with a single function that will block when you call ISequentialStream::Read. You can optionally get progress notifications in the background.
• Hook into the ActiveX client framework, if you like, simply by passing your this pointer.
• Configure callbacks using either the push or pull model (see Asynchronous Monikers).

URL open stream functions use services from URL Monikers and WinInet, providing all the caching and thread-synchronization features of those components. In addition, if your code is in an ActiveX container, the UOS functions handle all the host binding operations, automatically doing the right things to ensure an efficient and successful download. That is, these functions will determine whether your code is hosted within a container that supports the IBindHost interface and will use this interface if it is present. Otherwise, they will work without it.