USOO6401099B1

(12) United States Patent (10) Patent No.: US 6,401,099 B1

KOppolu et al. (45) Date of Patent: *Jun. 4, 2002

(54) ASYNCHRONOUS BINDING OF NAMED 4,674,040 A 6/1987 Barker et al.

OBJECTS 4,739,477 A 4/1988 Barker et al.
4,815,029 A 3/1989 Barker et al.
(75) Inventors: Srinivasa R. Koppolu, Redmond; w 2- Y-12
3. A 8E. Brent st al
eace2, et a
Johann Posch, Merger, Island, Victor
Stone, Mercer Island; Antony S.
5,072,412.
5,187,786 A
A 12/1991
2
Henderson, Jr. et al.
O O 2- Y - /1993 Densmore et al.
Williams, Mercer Island, all of WA 5.191,645 A 3/1993 Carlucci et al.
(US)
(List continued on next page.)
(73) Assignee: Microsoft Corporation, Redmond, WA
(US) FOREIGN PATENT DOCUMENTS
(*) Notice: This patent issued on a continued pros- JP 3191429 8/1991
ecution application filed under 37 CFR OTHER PUBLICATIONS
1.53(d), and is subject to the twenty year
patent term provisions of 35 U.S.C. Pike, Rob et al., “Unix -The Legend Evolves.” Plan 9 from
154(a)(2). Bell Labs, Proceedings of the Summer 1990 UKUUG Con
- 0 ference Jul. 9-13, 1990, Royal Lancaster Hotel, London
Subject to any disclaimer, the term of this UK, ISBN: 0 9513181 79.
patent is extended or adjusted under 35
U.S.C. 154(b) by 0 days. (List continued on next page.)
(21) Appl. No.: 08/760,924 Primary Examiner Frantz Coby
(22) Filed
CC
Dec. 6, 1996
ec. 6,
(74) Attorney, Agent, or Firm-Klarquist Sparkman, LLP
57 ABSTRACT
(51) Int. Cl. ................................................ G06F 17/30 (57)
(52) U.S. Cl. ........................................ 707/103; 707/104 An object-oriented framework unifies retrieval and brows
(58) Field of Search ................................. 707/103,104, ing of data locally and from remote computer networks. The
707/200; 395/200.06, 701, 703, 200, 500; framework includes a class of monikers that operate on
370/249 behalf of a client program to asynchronously bind or retrieve
data referenced by a name without blocking execution of the
(56) References Cited client. This allows the client to provide responsive user
interaction including when remotely retrieving data.
U.S. PATENT DOCUMENTS
4,514,800 A 4/1985 Gruner et al. .............. 364/200 69 Claims, 9 Drawing Sheets

or TN-152 158 - SYSTEM 156

BMDCX -I
BC --
128 BIND CONTEX
138
134 t
PAK
- ASYNCRONOUS
MONKER
WONIKER
150 -

BND
SAUS BINDSTATUSCALLBACK
- || -
CALLBACK PARSEDISPLAYNAME BENING
--O--H
48 ignone
 US 6,401,099 B1
Page 2

U.S. PATENT DOCUMENTS Pike, Rob et al., “The Use of Name Spaces in Plan 9, ”
5,204,947 A 4/1993 Bernstein et al. Operating Systems Review, 27(2):72-76, Apr. 1993,
ISSN:O163-598O.
5,206.951 A 4/1993 Khoyi
5,237,680 A 8/1993 Adams et al. “NeXTSTEP General Reference, Vol. 1 .” NeXT Publica
5,249,275 A 9/1993 Srivastava tions, Addison-Wesley Publishing Co., 1992, pp. 1-3 to
5,274,803 A 12/1993 Dubin et al. 1-37, 2–5 to 2-16, 2-390 to 2-419, 2-503 to 2-507, 2-895
5,297.249 A 3/1994 Bernstein et al. to 2–896, 2-986 to 2-987, 2–1045 to 2-1046.
5,297.283 A 3/1994 Kelly, Jr. et al. Clapp, Doug, “The NeXT Application Kit, Part I: Non-Re
5,313,646 A 5/1994 Hendricks et al.
5,333,317 A 7/1994 Dann ......................... 707/100 sponsive Classes.” The NeXT Bible, Brady Books, N.Y.,
5,339.423 A 8/1994 Beitel et al. 1990, pp. 275-280.
5,339,424. A 8/1994 Fushimi Zdonik, Stanley B., “Object Management System Con
5,341,478 A 8/1994 Travis, Jr. et al. cepts,” Association for Computing Machinery, ACM #ACM
5,369,766 A 11/1994 Nakano et al. 0–89791-140–7/84/006/0013, 1984.
5,369,778 A 11/1994 San Soucie et al. Zdonik, Stanley Benjamin, Jr., “Object Management System
5,381547 A 1/1995 Flug et al. Concepts: Supporting Integrated Office WorkStation Appli
5,408,665 A 4/1995 Fitzgerald
5,410,688 A 4/1995 Willians et al. cation,” Doctoral Thesis Massachusetts Institute of Technol
5,440,744 A 8/1995 Jacobson et al. ogy, 1983.
5,446,842 A 8/1995 Schaeffer et al. Wolfgang, Herzner et al., “CDAM -Compound Doument
5,459,865 A 10/1995 Heninger et al. Access and Managment. An Object-Oriented Approach,”
5,481,722. A 1/1996 Skinner Multimedia, Systems, Interaction and Applications, Euro
5,517,655 A 5/1996 Collins et al. graphics Workshop, Apr. 1991, Stockholm, Sweden, pp.
5.535,389 A 7/1996 Elder et al. 17-36.
5,551,035 A 8/1996 Arnold et al.
5,572,643 A 11/1996 Judson Kobayashi, Masaaki et al., “An Update on BTRON-speci
5,577.252 A 11/1996 Nelson et al. .............. 395/670 fication OS Development," IEEE Proceedings of the 8th
5,581,686 A 12/1996 Koppolu et al. Tron Project Symposium, Cat. Nr. 91THO412-7, Nov. 1991,
5,634,121 A 5/1997 Tracz et al. Tokyo, Japan, pp. 132-140.
5,659,729 A 8/1997 Nielsen IBM, “Creating In-Line Objects Within an Integrated Edit
5,664,178 A 9/1997 Sinofsky ing Environment, IBM Technical Disclosure Bulletin,
5,706,501 A 1/1998 Horikiri et al. ............... 707/10
5,745,683 A 4/1998 Lee et al. ................ 395/2008 27(5):2962, Oct. 1984.
5,758,358. A 5/1998 Ebbo DiLascia, Paul et al., “Sweeper,” Microsoft Interactive
5,761,683 A 6/1998 Logan et al. DeveloperVol. 1, No. 1, Spring 1996, pp. 16-52.
5,764.984. A 6/1998 Loucks ....................... 395/682 Brown, Mark R., “Using Netscape 2, pp. 162-163,
5,778,372 A 7/1998 Cordell et al. 148-156, 718–719, 1993.
5,815,830 A 9/1998 Anthony
5,838,906 A 11/1998 Doyle et al. Mills Elinor, “Navigator Cookies Files Will Monitor Web
5,842,018 A 11/1998 Atkinson et al. User Activity,” Feb.2, 1996.
5,854,630 A 12/1998 Nielsen Berg, Al, “Cookies Nibble at Your Disk Drive,”0 Jul. 8,
5,963,964 A 10/1999 Nielsen 1996.
6,016,520 A 1/2000 Facq et al. Trupin, J., “The Visual Programmer Puts ActiveX Document
6,026,416 A 2/2000 Kanerva et al.
6,031,989 A 2/2000 Cordell Objects Through Their Paces.” Systems Journal, Jun. 1996.
OTHER PUBLICATIONS “Getting Results. With Microsoft Office for Windows 95,'pp.
109–112, Microsoft Corporation, 1996.
Peterson, Baird, “Unix Variants.” Unix Review U.S. Patent Application No. 08/761,709 filed December 6,
10(4):29-31, Apr. 1992. 1996, Koppolu et al.
U.S. Patent Jun. 4, 2002 Sheet 1 of 9 US 6,401,099 B1

09

'CIMVOGAEX) LO‘BN|IAOBIdC]
LE
(O "AVTdSIG)
U.S. Patent Jun. 4, 2002 Sheet 2 of 9 US 6,401,099 B1

FG 2
r
CCENT

Microsoft
.338 Eiga 1833.338E. is Stre
:: Silk:33:atisfig: S333,333.33.:li:).
fir, Liris

8&Itesay is also the start of the 3i: ifess: as:

isse R&iaissal: fist::te 3: Er . s

* if:SE: ISS.1:...igies. Sites, .53

Th: 100 inst list is singtjective srashat of the res: Sapular
Ers: 2 critis a
U.S. Patent Jun. 4, 2002 Sheet 3 of 9 US 6,401,099 B1

INSTANCE VIRTUAL
DATA FUNCTION
STRUCTURE TABLE METHOD O
90

92

METHOD 1

METHOD 2

88
U.S. Patent Jun. 4, 2002 Sheet 4 of 9 US 6,401,099 B1

FIG. 4

104 114

BNDCTX
BIND CONTEXT

MONKER
MONIKER
U.S. Patent Jun. 4, 2002 Sheet 5 of 9 US 6,401,099 B1

FIG. 5

CLENT
NAMED
OBJECT

MONIKER
MONIKER
U.S. Patent Jun. 4, 2002 Sheet 6 of 9 US 6,401,099 B1

FIG. 6

CLENT 158

BNDCTX
BIND CONTEX

. ASYNCHRONOUS
MONIKER
MONIKER

15O

BND
STATUS BNDSTATUSCALLBACK
CALLBACK PARSEDSPLAYNAME BNDING
BNDING

154

PERSISTMONIKER
NAMED OBJECT

17O
U.S. Patent Jun. 4, 2002 Sheet 7 of 9 US 6,401,099 B1

FIG. 7
CLIENT 204

BNDCTX
C

and context
REQUESTED
FORMATS URL MONIKER
MONIKER
ENUM
FORMATETC
162

TRANSPORT
BIND PROTOCOL
STATUS
CALLBACK

214
AUTHENTCATE
PROTOCOL
232 specific
HTTP- INTERFACES
NEGOTATE
208

PERSISTMONIKER
NAMED OBJECT

17O
U.S. Patent Jun. 4, 2002 Sheet 8 of 9 US 6,401,099 B1

STARTASYNCHRONOUS
FIG. 8A
250
GET BIND INFORMATION FROM BIND 252
CONTEXT

CHECK RUNNING OBJECT TABLE 253

254 255
OBJECTS YES
RUNNING7

NO RETRIEVE OBJECT

GET BND INFORMATION FROM

CLIENT'S BIND STATUS CALLBACK 256 N/

NTATE BINDING WITH TRANSPORT 257

PASS TRANSPORT'S BINDING TO

CLIENT WA BIND STATUSCALLBACK. 258
ONSTARTBINDING

RETURN MKS ASYNCHRONOUS -

AND NULL OBJECT POINTER FROM 259
MONIKER::BINDTOOBJECT
U.S. Patent Jun. 4, 2002 Sheet 9 of 9 US 6,401,099 B1

Q/ FIG. 8B
260 Ny
CREATE URL OBJECT BASED ON 261 264
CLSD

CAL OBJECTS
QUERY FOR PERSIST INTERFACE PERSISTMONIKER::LOAD
OF OBJECT

262 - 263 OBJECT CALLS

MONIKER::BNDTOSTORAGE
Sir SPECIFYING PREFERRED
PERSIST INTERFACE

OBJECT HAS CALL OBJECTS

PERSISTSTREAM2 PERSISTSTREAM::LOAD
268

OBJECT HAS PERSISTFLE CA OBJECTS

PERSISTFILE::LOAD
269

QUERY OBJECT FOR INTERFACE 270

RECQUESTED BY CLENT

RETURN RECRUESTED INTERFACE

POINTER TO CLIENT VA
BNDSTATUSCALLBACK. 271
ONOBJECTAVAILABLE

END ASYNCHRONOUS
BINDING
 US 6,401,099 B1
1 2
ASYNCHRONOUS BINDING OF NAMED moniker. The logic necessary to acceSS different data there
OBJECTS fore need not be hard coded into the client program. Instead,
the client need only include the code for interacting with
COPYRIGHT AUTHORIZATION monikers for the named objects. Further, each moniker
A portion of the disclosure of this patent document 5 exposes its binding function to clients through an interface.
contains material which is Subject to copyright protection. All monikerS Support a common interface Structure defined
The copyright owner has no objection to the facsimile by the monikers’ class. Since all monikerS Support the same
reproduction by anyone of the patent document or the patent interface, a client can interact with any moniker in the same
way using the same code. OLE monikers thus provide a
disclosure, as it appears in the Patent and Trademark Office general mechanism for a client program to access any
patent file or records, but otherwise reserves all copyright variety of data from any Source.
rights whatsoever. OLE monikers, however, have a drawback when used for
FIELD OF THE INVENTION retrieving data from a slow Source. The time to retrieve data
This invention relates generally to uniformly navigating from Some Sources (particularly from the Internet and other
15 remote Sources) is very slow relative to human response
or browsing data from a variety of Sources, and more time. (The Internet is a global network of cooperatively
particularly relates to methods and Systems for referencing interconnected computer networks, consisting of millions of
and retrieving data Stored in a computer. individual computers. A portion of the Internet referred to as
BACKGROUND AND SUMMARY OF THE the “world-wide web' consists of computers, also referred to
INVENTION as “sites,” which make multi-media documents in hyper-text
mark-up language (HTML) generally available for down
Previous techniques and mechanisms for navigating to loading or retrieval by individuals having a computer with
and retrieving data in a computer System have had signifi Internet access.) A typical personal computer user connects
cant drawbacks which pose obstacles to providing unified to the Internet with a 28.8 kbaud or slower modem device.
tools for browsing data Seamlessly and transparently from 25 The typical document accessed from the world wide web
all Sources (including local storage and remote networks). portion of the Internet, on the other hand, is Several tens of
Microsoft Corporation's Object Linking and Embedding kbytes in size, and often incorporates one or more pictures
(OLE) component Software technology provides a technique which also may be tens of kbytes in size. At the data transfer
for referencing and retrieving data in a computer System rate of the typical modem connection, Such typical data can
which uses Small objects referred to as monikers. An OLE take minutes to access from the Internet.
object is a Software component that may encapsulate both A drawback to using OLE monikers for retrieving data
code (i.e., functions or procedures comprising a sequence of from Such Sources is that OLE monikers block. More
program instructions) and data, and exposes its functionality Specifically, when a client calls a moniker's binding
(i.e., the code) to other programs and objects (referred to as function, the call does not return until the data retrieval
“clients”) through interfaces. An interface is a named set of 35 completes. During this time, execution of the client program
logically related functions. Each object is an instance of an (including its user interface) halts. In effect, the client's user
object type (referred to as a “class”) which defines the interface freezes and remains non-responsive to user input
Structure of interfaces that its objects Support. until the data access is complete. In the Microsoft Win
A moniker operates as a name for another object. It dowS(R) operating System, this condition of the client pro
encapsulates the name of the object together with functions 40 gram is indicated by changing the mouse cursor to an "hour
for retrieving the named object through a process referred to glass” icon when the client has the “focus” (i.e., the cursor
in OLE as “binding.” The binding process resolves or is positioned over the client’s window). Since the client is
dereferences a name of an object into a link or pointer to the blocked, it is unable to display a progress indicator (Such as
particular named object (which for OLE purposes is a a “% complete' bar graph or “estimated time remaining
pointer to an interface of the named object including loading 45 notification), or provide any control which the user can
the object from persistent storage, if needed). Thus, binding activate to cancel the data access. Since the client may
can be defined as a process of retrieving and linking to an remain non-responsive for a Substantial time while accessing
object referenced by a name. data with a moniker from a Slow Source, the user thus has no
The object named by a moniker can encapsulate any way of knowing whether the data is still being accessed or
desired data. The name, for example, can be a file name of 50 the client has “crashed' (i.e., become inoperative) due to
data Stored as a file on a computer's hard drive or on a shared Some error. As a result, OLE monikers provide a low quality
network drive. The name can even be a uniform resource of Service when used for retrieving data from Slow Sources.
locator (URL) identifying a document or other data residing A unified browsing environment is provided in the present
on the Internet. Further, the binding function in the moniker invention by an object-oriented framework and System hav
contains the code to perform all the Steps necessary to bind 55 ing objects, programming interfaces, object integration
to the data, including finding the code associated with the interfaces, and methods for Supporting unified retrieval of
particular data referenced by the name, instantiating an data from different Sources. The invention overcomes the
object to encapsulate the data with its associated code, and limitation in previous monikers of blocking execution of the
loading the data from its Storage Source into the object. Thus, moniker's client, and thus provides Source-transparent and
a client program can acceSS any data from any Source using 60 responsive browsing.
a moniker that names that data, including a document Stored According to one aspect of the invention, a computer
as a file on a computers hard drive, a particular piece of a programming platform includes monikers (referred to herein
document (Such as a particular cell of a spreadsheet), or even as "asynchronous monikers’) which access data asynchro
data from remote Sources Such as the Internet or on-line nously. When a client calls the binding method of an
Services. 65 asynchronous moniker, the asynchronous moniker returns
OLE monikers have the advantage that the code for control immediately to the client and completes the data
retrieving data resides outside the client program in the access as a separately executing task or thread (Sometimes
 US 6,401,099 B1
3 4
referred to as “background processing”). Alternatively, the 3. OLE Server and Document Object Overview
moniker retrieves data to Storage with an asynchronous 4. Moniker Overview
Storage object which allows asynchronous acceSS by the 5. Asynchronous Monikers
client to the data as it is retrieved to Storage. Thus, even 5.1 Asynchronous and Synchronous Binding Selection
where the data is remotely accessed from a Slow Source, the 5 5.2 Asynchronous and Synchronous Storage
client is able to maintain a responsive user interface, which 5.3 Data-pull and Data-push models
prevents the perception of poor and non-uniform perfor 5.4 The IBinding Interface
CC.
5.4.1 The IBinding: Abort Function
In the illustrated embodiment, the asynchronous moniker 5.4.2 The IBinding::Suspend Function
and the client provide interfaces through which they interact 5.4.3 The IBinding::Resume Function
while the data acceSS is performed. Through the client's 5.4.4 The IBinding::SetPriority Function
interface, the asynchronous moniker provides notifications 5.4.5 The IBinding::GetPriority Function
of the status of the data access to the client. The client thus 5.5 The IBindStatusCallback Interface
is able to display a progreSS indicator. Also, the client can 5.5.1. The BIND VERB Enumeration
call functions through the interface of the asynchronous 15 5.5.2 The BINDINFOF Enumeration
moniker to abort, Suspend, or resume the data access. 5.5.3 The BINDINFO Structure
The illustrated embodiment of the invention provides an 5.5.4 The BSCO OPTION Enumeration
asynchronous moniker (referred to herein as a “URL 5.5.5 The BINDF Enumeration
moniker”) which references data with an Internet URL, and 5.5.6 The BSCF Enumeration
provides asynchronous access to the data for the client. The 5.5.7 The BINDSTATUS Enumeration
URL moniker has the capability of parsing the URL it 5.5.8. The IBindStatusCallback: QueryInterface Func
contains, and utilizing an associated Internet transport pro tion
tocol to access the data it names from the Internet. The 5.5.9 The IBindStatusCallback::GetBindInfo Function
programming platform includes an application program 25 5.5.10 The IBindStatusCallback: OnStartBind ing
ming interface which utilizes this parsing capability to Function
provide an extensible Service for creating a moniker which 5.5.11 The IBindStatusCallback::GetPriority Function
uses an appropriate transport protocol for a given data 5.5.12 The IBindStatusCallback::OnProgress Function
reference. The programming platform also provides object 5.5.13 The IBindStatusCallback::OnDataAvailable
integration interfaces for the moniker's client to negotiate Function
acceptable media types with the data Source. 5.5.14 The IBindStatusCallback:OnObject Available
Additional features and advantages of the invention will Function
be made apparent from the following detailed description of 5.5.15 The IBindStatus Callback:: On LowReso urce
an illustrated embodiment which proceeds with reference to Function
the accompanying drawings. 35 5.5.16 The IBindStatusCallback: OnStopBind ing
Function
BRIEF DESCRIPTION OF THE DRAWINGS 5.6 The IPersistMoniker Interface
FIG. 1 is a block diagram of a computer System that may 5.6.1 The IPersistMoniker::IslDirty Function
be used to implement a method and apparatus embodying 5.6.2 The IPersistMoniker::Load Function
the invention for unified browsing. 40 5.6.3 The IPersistMoniker::Save Function
FIG. 2 is a diagram illustrating a browsing System includ 5.6.4 The IPersistMoniker:SaveCompleted
ing the computer of FIG. 1 for unified browsing according 5.6.5 The IPersistMoniker::GetCurMoniker Function
to an illustrated embodiment of the invention. 5.7 API Functions for Asynchronous Monikers
FIG. 3 is a block diagram of typical data Structures for an 5.7.1. The Create AsynchbindCtX API Function
object in the computer system of FIG. 1. 45 5.7.2 The RegisterBindStatusCallback API Function
5.7.3 The RevokeBindStatusCallback API Function
FIG. 4 is a block diagram of software components that 5.7.4 The ISAsyncMoniker API Function
Support binding to a named object using a moniker. 6. URL Monikers
FIG. 5 is a process flow diagram of a binding process 6.1 Media-type Negotiation with the URL Moniker
performed by the moniker of FIG. 4. 50 6.1.1 The RegisterMediaTypes API Function
FIG. 6 is a block diagram of Software components includ 6.1.2 The CreateEormat numerator API Function
ing an asynchronous moniker for unified browsing to data in 6.1.3 The RegisterFormat numerator API Function
the computer of FIG. 1 according to one illustrated embodi 6.1.4 The RevokeFormat numerator API Function
ment of the invention. 6.1.5 The CreateURLMoniker API Function
FIG. 7 is a block diagram of software components includ 55 6.2 URL Moniker Functions
ing a URL moniker for unified browsing in the computer of 6.2.1 The URL Moniker-IUnknown::QueryInterface
FIG. 1 of documents referenced by a URL from the Internet Function
according to another illustrated embodiment of the inven 6.2.2 The URL Moniker-IPersist::Get ClassID Function
tion. 6.2.3 The URL Moniker-IPersistStream::IslDirty Func
FIGS. 8A-8B are flow charts illustrating an asynchronous 60 tion
binding process performed in the asynchronous moniker of 6.2.4 The URL Moniker-IPersistStream::Load Func
FIG. 6 and URL moniker of FIG. 7. tion
6.2.5 The URL Moniker-IPersistStream::Save Function
DETAILED DESCRIPTION OF THE
6.2.6 The URL Moniker-IPersistStream::GetSize Max
ILLUSTRATED EMBODIMENTS
65 Function
1. Browser Overview 6.2.7 The URL Moniker-IMoniker:BindToobject
2. Object Overview Function
 US 6,401,099 B1
S 6
6.2.8 The URL Moniker-IMoniker:BindToStorage AS is familiar to those skilled in the art, the computer
Function System 20 further includes an operating System and at least
6.2.9 The URL Moniker-Moniker::Reduce Function one application program. The operating System is the Set of
6.2.10 The URL Moniker-IMoniker: ComposeWith Software which controls the computer System's operation
Function and the allocation of resources. The application program is
6.2.11 The URL Moniker-Moniker::Enum Function the Set of Software that performs a task desired by the user,
6.2.12 The URL Moniker-IMoniker::IsBqual Function using computer resources made available through the oper
6.2.13 The URL Moniker-IMoniker::Hash Function ating System. Both are resident in the illustrated memory
6.2.14 The URL Moniker-IMoniker::IsRunning Func system 26.
tion
6.2.15 The URL Moniker-IMoniker::GetTimeOfLas In accordance with the practices of perSons skilled in the
tChance Function art of computer programming, the present invention is
6.2.16 The URL Moniker-IMoniker::Inverse Function described below with reference to acts and symbolic repre
6.2.17 The URL Moniker-IMoniker::Common Prefix Sentations of operations that are performed by computer
With Function System 20, unless indicated otherwise. Such acts and opera
6.2.18 The URL Moniker-IMoniker::RelativePathT o 15 tions are Sometimes referred to as being computer-executed.
Function It will be appreciated that the acts and Symbolically repre
6.2.19 The URL Moniker-IMoniker::Get DisplayName sented operations include the manipulation by the CPU 24 of
Function electrical Signals representing data bits which causes a
6.2.20 The URL Moniker-IMoniker::ParselDisplay resulting transformation or reduction of the electrical Signal
Name Function representation, and the maintenance of data bits at memory
6.2.21 The URL Moniker-IMoniker::IsSystemMoniker locations in memory System 26 to thereby reconfigure or
Function otherwise alter the computer System's operation, as well as
6.3 Client Extension Services other processing of Signals. The memory locations where
6.4 The IAuthenticate interface data bits are maintained are physical locations that have
6.5 The IHttpNegotiate Interface 25 particular electrical, magnetic, or optical properties corre
6.5.1 The IHttpNegotiate::BeginningTransa ction sponding to the data bits.
Function 1. Browser Overview
6.5.2 The IHttpNegotiate::OnHeaders Available Func In a browsing environment 50 of an illustrated embodi
tion ment of the invention shown in FIG. 2, the computer 20 (also
6.5.3 The IHttpNegotiate:OnError Function shown in FIG. 1) runs software, referred to herein as a
1. Computer Overview “browser,” for unified browsing of electronic documents and
Referring to FIG. 1, an operating environment for an other data from local Sources (e.g., the Secondary storage 42
illustrated embodiment of the present invention is a com of FIG. 1) and from a remote computer network 52. The
puter System 20 with a computer 22 that comprises at least browser can be integrated with the operating System
one high speed processing unit (CPU) 24, in conjunction 35 Software, or can be a separate application Software. The
with a memory System 26, an input device 28, and an output illustrated browser is implemented by the Software as an
device 30. These elements are interconnected by at least one OLE object (described below).
bus structure 32. The illustrated remote computer network 52 is the
The illustrated CPU24 is of familiar design and includes Internet, which is described in the Background and Sum
an ALU 34 for performing computations, a collection of 40 mary of the Invention above. In the illustrated browsing
registers 36 for temporary Storage of data and instructions, environment 50, the computer 20 connects to the computer
and a control unit 38 for controlling operation of the system network 52 over a telephone line 54 with a modem 56. Other
20. The CPU 24 may be a processor having any of a variety physical connections to the computer network alternatively
of architectures including Alpha from Digital, MIPS from can be used, such as an ISDN, T1 or like high speed
MIPS Technology, NEC, IDT, Siemens, and others, x86 45 telephone line and modem, a television cable and modem, a
from Intel and others, including Cyrix, AMD, and Nexgen, Satellite link, an optical fiber link, an Ethernet or other local
and the PowerPC from IBM and Motorola. area network technology wire and adapter card, radio or
The memory System 26 generally includes high-Speed optical transmission devices, etc. The invention can alter
main memory 40 in the form of a medium such as random natively be embodied in a browsing environment for other
access memory (RAM) and read only memory (ROM) 50 public or private computer networks, Such as a computer
Semiconductor devices, and Secondary Storage 42 in the network of a commercial on-line Service or an internal
form of long term Storage mediums. Such as floppy disks, corporate local area network (LAN), an intranet, or like
hard disks, tape, CD-ROM, flash memory, etc. and other computer network.
devices that Store data using electrical, magnetic, optical or Documents for browsing with the illustrated browser can
other recording media. The main memory 40 also can 55 reside as files of a file System Stored in the computer's
include Video display memory for displaying images Secondary storage 42 (FIG. 1), or reside as resources at a
through a display device. Those skilled in the art will remote computer 58 (also referred to as a “site') connected
recognize that the memory 26 can comprise a variety of to the computer network 52, such as a world-wide web site
alternative components having a variety of Storage capaci on the Internet. The illustrated document 60 residing at the
ties. 60 site 58 conforms with HTML standards, and may include
The input and output devices 28, 30 also are familiar. The extensions and enhancements of HTML standards.
input device 28 can comprise a keyboard, a mouse, a However, the illustrated browser also can browse documents
physical transducer (e.g., a microphone), etc. The output having other data formats (e.g., Microsoft(R) Word
device 30 can comprise a display, a printer, a transducer documents, etc.) from the computer 20 or remote computer
(e.g., a speaker), etc. Some devices, Such as a network 65 58.
interface or a modem, can be used as input and/or output In conformance with HTML, the illustrated document 60
devices. can incorporate other additional information content 62,
 US 6,401,099 B1
7 8
Such as images, audio, Video, executable programs, etc. asSociated terminology is provided below before discussing
(hereafter simply “images”. 62), which also reside at the the details of the illustrated embodiment.
remote computer 58. The document 60 and images 62 An object is an instance of a programmer-defined type
preferably are Stored as files in a file System of the remote referred to as a class, which exhibits the characteristics of
computer 58. The document 60 incorporates the images 62 data encapsulation, polymorphism and inheritance. Data
using HTML tags that specify the location of files or other encapsulation refers to the combining of data (also referred
Internet resource containing the images on the Internet 52. to as properties of an object) with methods that operate on
When used for browsing documents, the illustrated the data (also referred to as member functions of an object)
browser displays the document in a window 68 or rectan into a unitary Software component (i.e., the object), Such that
gular area of the computer's display 30 allocated to the the object hides its internal composition, Structure and
browser by the operating system. The illustrated window 68 operation and exposes its functionality to client programs
comprises a frame 70, a document display area 72, and user that utilize the object only through one or more interfaces.
An interface of the object is a group of Semantically related
interface controls 74. The browser provides the document member functions of the object. In other words, the client
display area 72 for displaying the document. programs do not access the object's data directly, but must
The browser and other client applications within the 15
instead call functions on the object's interfaces to operate on
computer 20 preferably work with documents (which have the data.
data formats other than those native to the browser or client Polymorphism refers to the ability to view (i.e., interact
application) by encapsulating the document's data into an with) two similar objects through a common interface,
asSociated object, and integrating with the object using thereby eliminating the need to differentiate between two
pre-defined interfaces as described more fully below. These objects. Inheritance refers to the derivation of different
document objects include the code to work with the docu classes of objects from a base class, where the derived
ment's data, including code to display the document data in classes inherit the properties and characteristics of the base
the document display area 72. The browser thus operates as class (which for purposes of OLE are the interfaces of the
a host or container of document objects, by providing a base class).
window and frame which includes a document display area 25 OLE'S COM specification defines binary standards for
in which a hosted document object can display its document. objects and their interfaces which facilitate the integration of
Working with documents encapsulated as document objects Software components. According to the COM Specification,
allows full use of all the features described below. a typical object 80 is represented in the computer system 20
Alternatively, the browser or other client application can (FIG. 1) by an instance data structure 82, a virtual function
work with a document by launching an application program table 84, and member functions 86-88. The instance data
asSociated with the document, and causing the associated structure 82 contains a pointer 90 to the virtual function table
application program to load the document and perform a 84 and data 92 (also referred to as data members, or
Specified operation on the document. In the MicroSoft Win properties of the object). A pointer is a data value that holds
dowS(R) operating System, this is done by looking up the the address of an item in memory. The virtual function table
application program associated with the document's file 35 84 contains entries 96-98 for the member functions 86–88.
name extension in the System registry, (e.g., *.doc' for Each of the entries 96-98 contains a reference to the code
Microsoft(R) Word documents, “.Vsd” for Shapeware's 86-88 that implements the corresponding member function.
VISIO drawings, etc.) and a text String command for direct The pointer 90, the virtual function table 84, and the
ing the program to perform a desired operation. The appli member functions 86-88 implement an interface of the
cation program associated with a document also may be 40 object 80. Client programs interact with the object 80 by
identified in the Microsoft Windows(R operating system by obtaining a pointer (referred to as an interface pointer) to the
matching a bit pattern at Specific offset into the file as also pointer 90 of the virtual function table 84. OLE includes a
Specified in the System registry. The browser or other client type definition of an interface pointer which allows client
application patches the document's file name into the text programs to call member functions on the interface by name
String command, and invokes the operating System's shell 45 through the interface pointer and provides type checking on
execute Service to execute the command. Shell execute is a the functions arguments, as expressed in the following code
well known Windows(R operating system service which (in the C++ programming language):
issues a text String as a command to the operating System's pinterface->MemberFunction(...)
command interpreter (i.e., the “command.com” program in By convention, the interfaces of an object are illustrated
the WindowS(E) operating System). The text string generally 50 graphically as a plug-in jack as shown for the document
is in the form of an MS-DOS command, which specifies a object in FIG. 3. Also, Interfaces conventionally are given
path and file name of the associated application program's names beginning with a capital “I.” Objects can include
executable file, a flag for Specifying the desired operation, multiple interfaces which are implemented with one or more
and the document's path and file name. The command virtual function tables. The member function of an interface
interpreter responds by parsing the text String, loading the 55 is denoted as “InterfaceName::FunctionName.”
application program Specified in the text String, and passing The object 80 conforming to the COM specification
the flag and the document's path and file name as command exhibits data encapsulation by exposing its interfaces
line arguments into the application program. The application (Semantic groupings of its member functions) to client
program then “opens’ (i.e., loads) the document and per programs. The client programs interact with the object 80 by
forms the operation specified by the flag. 60 calling the member functions 86-88 on a particular interface
2. Object Overview of the object, but do not directly manipulate the object's
Referring to FIG. 2, the illustrated embodiment of the data. The object 80 also exhibits polymorphism and inher
invention utilizes objects which conform to the component itance in that the object 80 can provide interfaces in common
object model (COM) of Microsoft Corporation's OLE. For with a base class and other similar objects, So that client
a detailed discussion of OLE see Inside OLE, Second 65 programs can interact with each of the objects in the same
Edition by Kraig BrockSchmidt, Microsoft Press, Redmond, manner by calling member functions of the interface that the
Wash. 1995. A brief overview of objects in OLE and objects have in common.
 US 6,401,099 B1
10
3. OLE Server and Document Object Overview member function named “QueryInterface.” The QueryInter
Referring now to FIG. 5, the virtual function table 84 and face function can be called with an interface identifier as an
member functions 86–88 of the OLE object 80 are provided argument, and returns a pointer to the interface associated
by a server application program 100 which is stored in the with that interface identifier. By convention, the IUnknown
computer System 20 (FIG. 1) as an executable program file interface's member functions are included as part of each
(with a "...exe' file name extension) or as a dynamic link interface on an object. Thus, any interface pointer that the
library file (with a “.dll” file name extension). Dynamic link client obtains to an interface of the object 80 can be used to
library files are loaded, dynamically linked, and executed by
the WindowS(R) operating System in a Same process with a call the QueryInterface function.
client application program. Executable program files are
loaded by the operating System as a separately executing In a typical Situation, however, the only information that
process. In accordance with OLE, the server application 100 the client program 104 has to reference a particular docu
includes code for the virtual function table 84 (FIG. 3) and ment is a textual name, Such as a file name or an Internet
member functions 86-88 (FIG. 3) of the classes that it URL. In the case of a file name, the COM library provides
Supports, and also includes a class factory that generates the 15 API functions (e.g., “GetClassFile,” “ReadClassStg” and
instance data structure 82 (FIG. 3) for an object of the class. “ReadClassStm”) for obtaining a CLSID associated with the
A Server application can be written by a programmer to file. These functions, however, are Specific to document data
Support a particular class of object that contains any desired that is Stored as a file in a computer's local Storage.
data. For example, a programmer can write Server applica
tions which provide objects that contain the data of a 4. Moniker Overview
particular variety of computer document (e.g., document 60
of FIG. 2), Such as a text document, spreadsheet, drawing, With reference to FIGS. 4 and 5, the client program 104
etc., or that contain data for part of a computer document, also can gain access (i.e., a pointer to an interface) to the
Such as a range of spreadsheet cells, a paragraph of a text object 80 which encapsulates some desired data based on a
document, etc. These objects which contain document data 25 name that references the object using a moniker 120. The
are referred to herein as document objects. For example, moniker 120 generally is provided by the COM library of the
Software application programs Such as MicroSoft(E) Word can operating System 114. Alternatively, the moniker may be
be written as a Server application in which the application provided by the Server application associated with the object
program's documents are represented as OLE objects. A 80. The system 114 includes API functions which the client
Server application also can be written for representing the program 104 calls to have a moniker created for a given
HTML document 60 and images 62 (FIG.2) as OLE objects. name. In OLE, there are four Standard classes of monikers,
This allows other client programs 104 (such as the unified i.e., file moniker, item moniker, pointer moniker, and anti
browsing Software program illustrated in FIG. 2) and objects moniker, which are described more fully in the book, Inside
to interact with the document through interfaces of the OLE, Second edition, Supra. The API functions for creating
document object. 35
a moniker of these Standard moniker classes are Summarized
For the client program 104 to interact with the document in the following table:
object 80 provided by the server application 100, the server
application must first create the object (i.e., instantiate an TABLE 1.
object of a class Supported by the Server application) and the
client 104 must gain an interface pointer to the object 80. In 40 OLE Moniker APIs
OLE, the client program 104 realizes these events using
services provided by OLE and a set of standard object Function Description
interfaces defined by COM based on class and interface CreateFile Moniker(pszPath, Creates a file moniker, given any
identifiers assigned to the object's class and interfaces. More ppmk) portion of a path name in pszFile. The
Specifically, the Services are available to client programs as 45 portion can be as short as a drive letter
or as long as a complete path. The file
application programming interface (API) functions provided moniker converts pszPath to a standard
in the COM library, which is part of a component of the UNC path. Anything the operating
Windows(R operating system in a file named “OLE32.DLL.” system understands as a path is
In OLE, classes of objects are uniquely associated with class suitable for a file moniker.
CreateItemMoniker(pszDeli Creates an item moniker for which
identifiers (“CLSIDs"). Class identifiers are 128-bit globally 50
m, pSZItem, ppmk) pSZItem identifies the item's name and
unique identifiers (“GUID”) that the programmer creates pSZDelim identifies a delimiter string
with an OLE service named “CoCreateCUID' and assigns (usually a single character such as ),
to the respective classes. The interfaces of an object are which does not occur elsewhere in
associated with interface identifiers (“IIDs"). pszItem. This delimiter is used to prefix
the item's display name, allowing it to
In particular, the COM library provides an API function, 55 be combined with other items in the
“CoCreateInstance,” that the client program 104 can call to same string and parsed out of that
request creation of an object to encapsulate a particular string again.
CreatePointerMoniker(pIUnk Creates a pointer moniker to
documents data using a CLSID associated with the data. The nown, ppmk) encapsulate the pointer passed in
CoCreateInstance API function creates the object and pIUnknown. This makes any object
returns a pointer of the requested interface to the client 60 look like a moniker.
program. Create AntiMoniker(ppmk) Creates an anti-moniker, which needs
no extra information.
Once the client program 104 has obtained a first interface
pointer to the object 80, the client obtains pointers to other
desired interfaces of the object using the interface identifier
associated with the desired interface. COM defines several 65 For creating a moniker based on a user-provided name,
Standard interfaces generally Supported by OLE objects the system 114 also provides an OLE API function called
including the IUnknown interface. This interface includes a MkParsedisplayName, which has the following form:
 US 6,401,099 B1
11 12
read and write their State persistently as a data Stream or file
in the computer's Secondary storage 42 (FIG. 1). This means
that the moniker 120 also includes member functions to
HRESULT MkParseDisplayName(IBindCtx *pbc, LPCWSTR pszName,
ULONG *pchEaten, IMoniker **ppmk) support the IPersistStream interface, which allows the client
to store and load the moniker 120 from the secondary
Storage.
The MkParselDisplayName API function parses a text The member functions which the moniker 120 exposes
String (the parameter “pSZName”) into a moniker. The text through the IMoniker interface 124 include two functions,
String can have one of two initial patterns: a uniform naming BindToCbject and BindToStorage (herein collectively
convention (UNC) path name (a conventional file system referred to as BindToxxx), which the client 104 calls to bind
path name such as “c:\directory\file”), or the character “G” to the named object 80. The BindToCbject function per
followed by a program identifier (ProgID) of a server forms binding by instantiating the named object 80 in the
application. In the case of a UNC path name, the API memory 40 (FIG. 1) of the computer, and returns an inter
function creates a file moniker and calls the file moniker's face pointer of the named object 80 to the client 104. The
“ParselDisplayName” function (described below) to parse 15 BindToStorage function performs binding by instantiating
the text string. In the case of a text string with the “G” the named object 80 onto an OLE storage stream which is
character and ProgID, the API function creates an object Stored in the computer's Secondary Storage 42 (e.g., on the
based on a CLSID associated with the ProgID in the hard drive), rather than into the main memory 40. In the
operating System's registry database and calls a “ParSeDis browsing environment 50 illustrated in FIG. 2 for example,
playName” member function on an “IParselDisplayName” the BindToStorage function is used to download a file such
interface of that object, which is defined as follows: as an image or Video clip directly onto hard disk Storage,
whereas the BindToCbject function is used to create an
instance of an object for an HTML document with code for
interface IParselDisplayName : IUnknown { Viewing the document.
HRESULT ParseDisplayName(IBindContext *pbc, 25 The IMoniker interface 124 also exposes the functions,
LPOLESTR pszDisplayName, ULONG Get DisplayName and ParselDisplayName, of the moniker
*pchEaten, IMoniker **ppmkOut); 120 to the client 104. The Get DisplayName function returns
a human-readable display name of the object 80 which the
client can display to the user, Such as in a list box control or
By effectively plugging in a new name-to-moniker parser in other user interface element. The display name is a text
this way, the MkParselDisplayName API can be extended to String that names the object 80, Such as a path and file name
create new classes of monikers. or an Internet URL. The ParselDisplayName function oper
The moniker 120 exposes a set of member functions to the ates in reverse, creating a moniker based on a text String
client 104 through an interface 124, designated IMoniker, provided by the client.
which is defined as follows: 35 Further details of the moniker's member functions are
described in Inside OLE, Second edition, Supra.
When calling most of the moniker's member functions,
interface IMoniker : public IPersistStream {
the client program 104 passes a pointer to a bind context 126
public: as a parameter of the call. The bind context 126 is an object
HRESULT BindToobject(IBindCtx *pbc, IMoniker *pmkToLeft, 40 which operates as a central repository of information used
REFIID ridResult, void *ppvResult); globally in the binding process, Such as a table of running
HRESULT BindToStorage(IBindCtx *pbc, IMoniker objects. The bind context 126 has an interface 128, desig
*pmkToLeft, REFIID rid, void **ppvObi); nated IBindCtX, which is defined as follows:
HRESULT Reduce(IBindCtx *pbc, DWORD
dwReduceHowFar, IMoniker **ppmkToLeft, IMoniker
**ppmkReduced); 45
RESULT ComposeWith(IMoniker *pmkRight, BOOL
fCnlyIfNotGeneric, IMoniker **ppmkcomposite); interface IBindCtx: IUnknown
RESULT Enum(BOOL fForward, IEnumMoniker {
**ppenumMoniker); HRESULT RegisterObjectBound (IUnknown *pUnk);
RESULT IsEqual(IMoniker *pmkOtherMoniker); HRESULT RevokeobjectBound(IUnknown punk);
RESULT Hash(DWORD *pdwHash); 50 HRESULT ReleaseBoundObjects(void);
RESULT IsRunning(IBindCtx *pbc, IMoniker *pmkToLeft, HRESULT SetBindOptions(BIND OPTS *pbindopts):
IMoniker *pmkNewlyRunning); HRESULT GetBindOptions(BIND OPTS *pbindopts):
RESULT GetTimeOf LastChange(IBindCtx *pbc, IMoniker HRESULT GetRunningObjectTable(IRunningObjectTable
*pmkToLeft, FILETIME *pFileTime); **ppROT):
RESULT Inverse(IMoniker **pmk); HRESULT RegisterObjectParam(LPOLESTR pszKey,
RESULT Common PrefixWith(IMoniker *pmkOther, IMoniker 55 IUnknown punk);
**ppmkPrefix); HRESULT GetObjectParam(LPOLESTR pszKey, IUnknown
RESULT RelativePathTo(IMoniker *pmkOther, IMoniker **ppUnk);
**ppmkRelPath); HRESULT EnumObectParam(IEnumString **ppEnum);
RESULT GetDisplayName(IBindCtx *pbc, IMoniker HRESULT RevokeobjectParam(LPOLESTR pszKey);
*pmkToLeft, LPOLESTR *ppszDisplayName);
RESULT ParseDisplayName(IBindCtx *pbc, IMoniker
*pmkToLeft, LPOLESTR *pszDisplayName, ULONG 60
*pchEaten, IMoniker **ppmkOut); The bind context 126 is provided by the system 114. The
HRESULT IssystemMoniker(DWORD *pdwMksys); client program 104 creates the bind context 126 by calling
a system API function, Create BindCtX. The client program
104 creates the bind context once, then passes a pointer to
AS indicated in the above interface definition, the IMon 65 the bind contexts IBindCtX interface in calls to the moniker
iker interface is derived from the IPersistStream interface, 120. This allows the moniker 120 to retrieve global infor
which is a well known OLE interface for objects that can mation stored in the bind context 126 by calling functions on
 US 6,401,099 B1
13 14
the IBindCtX interface. When called by the client to bind to 5. Asynchronous Monikers
the named object 80 for example, the moniker 120 can look In an illustrated embodiment of the invention shown in
in the running objects table of the bind context 126 to FIG. 6, a client program (hereafter "client”) 152 uses an
determine whether the object already exists. If the object asynchronous moniker 150 to asynchronously bind to a
exists, the moniker 120 can Simply return an interface named object 154. The asynchronous moniker 150 is an
pointer of the existing object to the client 104, and thus avoid instance of an asynchronous moniker class which is derived
creating the object again. Other uses of the bind context are from the moniker class and Supports the IMoniker interface
described in Inside OLE, Second edition, Supra. 124. Asynchronous binding effectively retrieves data from
FIG. 5 illustrates the operation of the moniker 120 per its Source as a background process which allows the client
forming the binding proceSS for the client program 104 to an 152 to continue execution. Since the client 152 is not
interface of the named object 80. In the illustrated example, blocked, the client's user interface remains responsive dur
the client program 104 uses the moniker 120 to bind to the ing the binding process. This is particularly useful for
object referenced by a name with code Such as the following: loading objects having data from slow Sources, Such as the
Internet and other remote networks with high latency and
15 slow data transfer connections. The client 152 thus is able to
HRESULT hir: more uniformly browse data from fast and Slow Sources
IBindCtx* pbc;
hr=CreatBindCtx(0,&pbc);
while maintaining the user perception of equivalent respon
Siveness and quality of Service.
IMoniker *pmk; Similar to the use of standard OLE monikers described
IObj1 *pObj: above, the client 152 creates an asynchronous bind context
GetMonikerSomehow(&pmk); 156, and the asynchronous moniker 150 by calling API
hr = pmk->BindToCbject(pbc.O.IID IObj1, &pObi);
if (hr==S OK): functions (specifically, the Create AsynclindCtX API func
pObj->SomeFunction.(...); tion and the MkParselDisplayNameEX API functions both
described below) provided by an operating System compo
25 nent 158 (specifically a component such as the COM library
In this example, the named object 80 exposes a member 114 of FIG. 4, which additionally implements the asynchro
function, SomeFunction, through an IObj1 interface 130, nous moniker API functions described below). The asyn
and includes a second interface 131, IObj2. With the above chronous bind context Supports IBindCtX interface 128 of
code, the client first creates the bind context 126 which will the bind context 126 (FIG. 4). The client 152 then calls the
be used later by the moniker 120 when binding to the named BindToCbject or BindToStorage function on the IMoniker
object 80. The client creates the bind context by calling the interface 124 of the asynchronous moniker 150 to initiate the
Create BindCtX API function of the system 114 as described asynchronous binding process.
above. The CreateBindCtX API function returns an interface The asynchronous binding process involves additional
pointer of the IBindCtX interface 128 to the client 104, communication or “handshaking” between the client 152
which the client stores as the pointer variable 134, pbc. 35 and asynchronous moniker 150 not performed in the syn
The client next creates the moniker 120 which names the chronous binding process by Standard OLE monikers (e.g.,
object 80 using a moniker creation API function of the the moniker 120). In the asynchronous binding process, the
System 114 as described above (e.g., asynchronous moniker 150 returns control immediately to
MKParselDisplayName). The client is returned an interface the client 152 from the client's call (e.g., call 140 of FIG. 5)
pointer of the IMoniker interface 124. In this example code, 40 to one of the asynchronous moniker's binding functions
the client stores this pointer to the IMoniker interface 124 of (e.g., BindToCbject and BindToStorage). After the call
the moniker 120 as a pointer variable 136, pmk. The client returns, instantiation of the named object 154 and loading of
104 then performs a call 140 to the BindToCbject function the object's data proceeds. Meanwhile, the client and asyn
on the IMoniker interface 124 of the moniker 120 to bind to chronous binding proceSS continue communicating So that
the named object 80. In the call 140, the client passes an 45 the client remains informed of the progreSS of loading the
interface identifier (IID IObj1) to request binding to a data and can interrupt or terminate loading of the data.
particular interface (the IObj1 interface 130) of the named This handshaking between the client 152 and the asyn
object 80. chronous binding proceSS is effected using two additional
In the moniker's BindToCbject function, the moniker 120 interfaces, an IBinding interface 160 and an IBindStatus
includes code which launches the object's Server application 50 Callback interface 162. In the illustrated embodiment of the
program 100, requests creation of the named object, and invention, the IBinding interface 160 is an interface of a
queries for a pointer to the interface requested by the client. binding object 164 which is provided by the asynchronous
The moniker 120 typically performs these steps with calls moniker 150. The client 152 implements a bind-status
142 to the GetClassFile and CoCreateInstance API functions callback object 166 which supports the IBindStatusCallback
described above, and to the QueryInterface member function 55 interface 162.
of the object 80 to query for the requested interface of the Prior to initiating the asynchronous binding process with
object as also described above. As a result, the object 80 is a call to the IMoniker interface 124 of the asynchronous
instantiated by its class factory in the server application 100, moniker 150, the client 152 registers its bind-status-callback
and returns (144) a pointer of the requested interface (the object 166 with the asynchronous bind context via the
IObj1 interface 130 in this example) of the named object 80 60 RegisterBindStatusCallback API function described more
to the moniker 120. The moniker 120, in turn, returns (146) fully below. When the client thereafter calls the IMon
the object's interface pointer to the client program 104. iker::BindToCbject or IMoniker::BindToStorage function as
Whereupon, the client program can directly call (148) mem shown in FIG. 5 and described above, the client 152 passes
ber functions on the interface of the named object 80. At this an interface pointer of the bind context's IBindCtX interface
point, the binding process is complete and the moniker 120 65 128 to the asynchronous moniker 150. In the IMon
is no longer needed by the client program 104 to access the iker::BindToxXx function, the asynchronous moniker 150
named object 80. looks up the client's bind-status-callback object 164, creates
 US 6,401,099 B1
15 16
the binding object 164, and hooks together the binding asynchronous moniker's IMoniker::BindToStorage
object 164 and the client's bind-status-callback object 166 function, and receiving asynchronous notifications. In the
by passing an interface pointer of the IBinding interface 160 data-pull model, the client 152 drives the bind operation.
to the bind-status-callback object 166 (with a call to the The asynchronous moniker 150 only provides data to the
bind-status-callback objects IBindStatusCallback: OnStart client 152 when the client reads the data. Specifically, this
Binding function described more fully below). The asyn means that beyond the asynchronous moniker's first call to
chronous moniker 150 then returns control to the client 152 the IBindStatus Callback:: On DataAvailable function
from the IMoniker::BindToxXX function, and allows the (described below), the asynchronous moniker 150 will not
binding object 164 to proceed with the binding process with provide any data to the client unless the client has consumed
the binding object 164 and bind-status-callback object 166 all of the data that is already available. Because the asyn
communicating directly. chronous moniker 150 only downloads data as it is
5.1 Asynchronous and Synchronous Binding Selection requested, the client nevertheless should read the data in a
In the illustrated embodiment, the client 152 can deter timely manner. In the case of downloading data from Inter
mine whether any particular moniker Supports asynchronous net for example, the bind operation may fail if the client 152
binding (i.e., is an asynchronous moniker) by calling an 15 waits too long before requesting more data.
ISAsyncMoniker API function (described below). The client On the other hand, in a data-push model, the asynchro
152 can further control whether the asynchronous moniker nous moniker 150 will drive the bind operation and con
150 performs binding asynchronously or synchronously by tinuously notifies the client whenever new data is available
setting a BINDF ASYNCHRONOUS flag when the asyn (i.e., by calling the client’s IBindStatusCallback::On
chronous moniker 150 calls an IBindStatusCallback::Get DataAvailable function). In such cases, the client 152 may
BindInfo function (described below) of the client's bind choose whether or not to read the data at any point during the
status-callback object 166 at the beginning of the bind bind operation, but the asynchronous moniker continues to
operation. drive the bind operation until completion.
When the client 152 specifies asynchronous binding, the 5.4 The IBinding Interface
asynchronous moniker 150 does not return an object or 25 The IBinding interface 160 is implemented by the asyn
storage pointer from the client's call to the IMoniker::Bind chronous moniker 150 on the binding object 164, which is
ToObject or IMoniker::BindToStorage function. Instead, the a separate object that the asynchronous moniker 150 creates
asynchronous moniker 150 returns the value, MS S on a per-bind operation basis. The IBinding interface 160
ASYNCHRONOUS, and a NULL pointer. The client 152 exposes member functions of the binding object 164 which
then waits to receive the requested object or Storage from the allow control of the bind operation performed by the binding
asynchronous moniker in a call to the client's IBindStatus object. The asynchronous moniker 164 provides the client
Callback::OnObject Available or IBindStatusCallback::On 152 with access to the IBinding interface 160 by passing a
DataAvailable function (described below). pointer of the IBinding interface to the client's bind-status
On the other hand, if the client does not set the BINDF callback object 166 via a call to the IBindStatusCallback
ASYNCHRONOUS flag, the asynchronous moniker syn 35 :: OnStartBinding function described below.
chronously binds the object or Storage, and returns the object The IBinding interface 160 is defined as follows:
or Storage from the client's call to the asynchronous moni
ker's IMoniker::BindToCbject or IMoniker::BindToStorage
function.
5.2 Asynchronous and Synchronous Storage 40 If--------------------------------------------------------------------------------------
If
In a call to the IBindStatusCallback: OnDataAvailable // Copyright (C) Microsoft Corporation, 1995-1996.
function (described below) during asynchronous binding to If
Storage, the asynchronous moniker 150 also may return an // Contents: IBinding interface definition
asynchronous Storage object. This asynchronous Storage If
If---------------------------------------------------------------------------------------
object Supports the IStream or IStorage interface (well 45 cpp quote(“#ifndef LPBINDING DEFINED)
known OLE interfaces), and its implementation of the cpp quote(“#define LPBINDING DEFINED)
functions in that interface allows access to Some of the data
object,
being bound while the binding is still in progreSS. The client uuid (79eac9c0-baf9-11ce-8c82-00aaOO4ba90b),
152 can choose between two modes for the asynchronous pointer default (unique)
Storage object: blocking and non-blocking. If data is not yet 50
available in the blocking mode (the default), the client's call interface IBinding: IUnknown
to the asynchronous Storage object blocks until the data {
typedefunique IBinding *LPBINDING:
arrives. In the non-blocking mode, the asynchronous Storage HRESULT Abort();
object returns an error value, E PENDING, to the client's HRESULT Suspend();
call when data is not yet available. In response, the client 55 HRESULT Resume();
waits for further notifications to its IBindStatusCallback HRESULT SetPriority(
in LONG nPriority);
:: On DataAvailable function before retrying the operation. HRESULT GetPriority(
The client 152 can choose between a synchronous out LONG * pnPriority);
(blocking) and asynchronous (non-blocking) storage by local HRESULT GetBindResult(
Out CLSID pclsidProtocol,
choosing whether or not to set the BIND F 60
Out DWORD *pdwResult,
ASYNCSTORAGE flag in the pgrfBINDF value which the Out LPOLESTR *pszResult,
client returns from the IBindStatusCallback::GetBindInfo in, out DWORD *pdwReserved);
function (described below) to the asynchronous moniker call as(GetBindResult)
150. HRESULT RemoteCietBindResult(
out CLSID pclsidProtocol,
5.3 Data-pull and Data-push Models 65 out DWORD *pdwResult,
The client 152 can choose between a data-pull and out LPOLESTR *pszResult,
data-push model for driving the asynchronous binding in the
 US 6,401,099 B1
17 18
-continued TABLE 4
in DWORD dwReserved); Return Values of the IBinding:Resume Function
cpp quote(“#endif) Argument Type Description
Returns S OK Success
S FALS The bind operation was not
5.4.1 The IBinding: Abort Function E previously suspended.
E FAIL The suspended bind operation
1O could not be resumed.
The IBinding::Abort member function permanently
aborts the bind operation. After aborting the bind operation,
the client may still receive Some notifications about the 5.4.4 The IBinding::SetPriority Function
binding. The IBinding::SetPriority function establishes the priority
15
for the bind operation according to an input parameter,
An aborted bind operation will result in a call to the nPriority. The priority values are taken from the Microsoft
IBindStatusCallback::OnStopBinding function (described Corporations Win32 thread priority APIs
below) with a corresponding error code. Alternatively, the (SetThreadPriority and GetThreadPriority). The final prior
aborted bind operation results in a failure of the client's call ity is determined from values gathered from all clients of the
to the IMoniker::BindToCbject/BindToStorage function in bind operation. The parameter and return values of the
the Situation where that call has not previously returned. At illustrated IBinding::SetPriority function are shown in the
this point the bind operation is officially complete and the following table.
client must release any pointers obtained during the binding.
TABLE 5
The return values of the illustrated IBinding::Abort func
tion are shown in the following table: 25 IBinding::SetPriority Function Parameters and Return
Values
TABLE 2 Argument Type Description
Return Values of the IBinding::Abort Function nPriority LONG A value indicating the priority to
establish for this binding relative to
Argument Type Description other bindings and the system.
Returns S OK Success.
Returns S OK Success E FAIL The priority could not be changed.
S FALS The bind operation was already
E aborted.
E FAIL The bind operation could not be 5.4.5 The IBinding::GetPriority Function
aborted. 35
The IBinding::GetPriority function retrieves the current
priority of the bind operation. The priority values are taken
from the Win32 thread priority APIs (SetThreadPriority and
5.4.2 The IBinding::Suspend Function GetThreadPriority). The parameters and return values of the
The IBinding::Suspend function suspends the bind opera 40 illustrated function are shown in the following table.
tion. The bind operation will be suspended until resumed by TABLE 5
a later call to the IBinding::Resume function or canceled by
a call to the IBinding::Abort function. After calling IBind IBinding::GetPriority Function Parameters and Return
ing::Suspend the client may still receive Some notifications Values
about the bind operation. 45
Argument Type Description
The return values of the illustrated IBinding::Suspend pnPriority LONG* Location to return a value
Function are shown in the following table: indicating the priority
established for this binding
TABLE 3 50 relative to other bindings
and the system. May not
be NULL.
Binding:Suspend Function Return Values Returns S OK Success.
E INVALIDARG The pn Priority argument is
Argument Type Description invalid.
Returns S OK Success 55
S FALS The bind operation was already 5.5 The IBindStatusCallback Interface
E suspended.
E FAIL The bind operation could not be The IBindStatusCallback interface 162 exposes member
suspended. functions of the bind-status-callback object 166 provided by
the client 152. These members functions are called by the
60 asynchronous moniker 150 and binding object 164 to pro
5.4.3 The IBinding::Resume Function vide notifications to the client 152 relating to the bind
operation, e.g., the bind operation's Status and progreSS
The IBinding::Resume function resumes a Suspended updates. The asynchronous moniker 150 calls the notifica
bind operation. The bind operation must have been previ tion member functions of the IBindStatusCallback in the
ously Suspended by a call to the IBinding::Suspend function. 65 IMoniker::BindToCbject and BindToStorage functions, and
The return values of the illustrated IBinding::Suspend func the binding object 164 will continue to call the notification
tion are shown in the following table: member functions in an asynchronous bind operation after
 US 6,401,099 B1
19 20
the asynchronous moniker returns from the BindToCbject or
BindToStorage function. -continued
The asynchronous moniker 150 also calls two member interface IBindStatusCallback: IUnknown
functions, the GetBindInfo and GetPriority functions
(described below), to receive additional information for the 5 typedef unique IBindStatusCallback
bind operation from the client 152. In its BindToCbject or *LPBINDSTATUSCALLBACK
BindToStorage function, the asynchronous moniker calls the typedef enum
IBindStatusCallback::GetBindInfo function (described {
BINDVERB GET = 0x00000000, if default action
below) to check at least the BINDF ASYNCHRONOUS BINDVERB POST = 0x00000001, If post verb
flag which indicates whether to perform the bind operation BIND VERB PUT = 0x00000002, II put verb
asynchronously. The asynchronous moniker 150 also may BINDVERB CUSTOM = 0x00000003, if custom verb
call the IBindStatusCallback::GetPriority to set the priority BINDVERB:
typedef enum
of the bind operation. Further, the asynchronous moniker
150 may call the IBindStatusCallback::QueryInterface func BINDINFOF URLENCODESTGMEDDATA = 0x00000001,
tion to request an interface pointer of a further interface of 15 If url encode the stgmed data
the client through which the asynchronous moniker can BINDINFOF URLENCODEDEXTRAINFO = OxOOOOOOO2,
If url encode the extra info
obtain further information or access additional or extended BINDINFOF:
Services. If flags that describe the type of transaction that caller wants
In the illustrated embodiment, the client 152 provides the typedef enum
bind-status-callback object 166 in association with a specific {
BINDF ASYNCHRONOUS = 0x00000001,
bind operation. The caller of the member functions exposed BINDF ASYNCSTORAGE = 0x00000002,
through the IBindStatusCallback interface thus need not BINDF NOPROGRESSIVERENDERING = 0x00000004,
pass information identifying the Specific bind operation. BINDF
BINDF
OFFLINEOPERATION
GETNEWESTVERSION
0x00000008,
0x00000010,
=
=
The client 152 registers the IBindStatusCallback interface BINDF NOWRITECACHE 0x00000020, =
of its bind-status-callback object 166 into the asynchronous 25 BINDF PULLDATA 0x00000080, =
bind context by calling the RegisterBindStatusCallback API BINDF IGNORESECURITYPROBLEM0x00000100, =
function described below. The asynchronous bind context BINDF RESYNCHRONIZE 0x00000200, =
BINDF HYPERLINK 0x00000400, =
registers only a single IBindStatusCallback interface at a BINDF COMPLETEDOWNLOAD 0x01000000, =
time (i.e., that of the last client to call the RegisterBindSta BINDF INLINESGETNEWESTVERSION = 0x1OOOOOOO,
tusCallback API function). However, the RegisterBindSta BINDF INLINESRESYNCHRONIZE = 0x20000000,
tusCallback API function returns an interface pointer of the BINDF CONTAINER NOWRITECACHE = 0x40OOOOOO
previously registered IBindStatusCallback interface to allow BINDF:
typedef struct tagBINDINFO
chaining of IBindStatusCallback interface notifications {
between multiple clients. So that notifications can be ULONG cbSize:
chained to multiple clients through the registered client, the 35 LPWSTR szExtraInfo: If e.g. string added to the URL
string range byte
client with the registered IBindStatusCallback interface will STGMEDIUM stgmedData; // e.g. put or post data
receive all IBindStatusCallback notifications from the asyn DWORD grfBindInfoF; // e.g. how meddata should be
chronous bind context. The asynchronous moniker 150 treaded
retrieves the interface pointer of the IBindStatusCallback DWORD dwBindVerb; if e.g. put, post, ...
interface which is registered for a particular bind operation 40 LPWSTR SzCustomVerb; if e.g. custom verb
DWORD cbstgmedData; // size of data in stgmed Data
from the asynchronous bind context in its IMoniker::Bind BINDINFO:
ToObject or BindToStorage member functions. typedef struct tagRemBINDINFO
If the asynchronous moniker 150 invokes other monikers {
as part of the bind operation, the asynchronous moniker may ULONG cbSize:
LPWSTR szExtraInfo: If e.g. string added to the URL
register its own IBindStatusCallback interface (not shown) 45 string range byte
in the asynchronous bind context to receive notification from DWORD grfBindInfoF; // e.g. how meddata should be
treaded
the other moniker. The notifications through the IBindSta DWORD dwBindVerb; if e.g. put, post, ...
tusCallback interfaces of more than one moniker involved in
LPWSTR SzCustomVerb; if e.g. custom verb
a bind operation can thus be chained to provide consolidated DWORD cbstgmedData; // size of data in stgmed Data
progreSS notifications. 50 RemBINDINFO:
The definition of the IBindStatusCallback interface 162 typedef struct tagRemFORMATETC {
and related data Structures is as follows: DWORD cfFormat:
DWORD ptd;
DWORD dwAspect;
LONG lindex;
55 DWORD tymed;
If----------------------------------------------------------------- RemFORMATETC, *LPREMFORMATETC;
If If Data notification flags
// Copyright (C) Microsoft Corporation, 1995-1996. typedef enum
If {
If Contents: IBindStatus.Callback interface definition BSCF FIRSTDATANOTIFICATION = 0x00000001,
If 60
BSCF INTERMEDIATEDATANOTIFICATION
If-------------------------------------------------------------------- = 0x00000002,
cpp quote(“#ifndef LPBINDSTATUSCALLBACK DEFINED) BSCF LASTDATANOTIFICATION = OxOOOOOOO4
cpp quote(“#define LPBINDSTATUSCALLBACK DEFINED) BSCF;
typedef enum tagBINDSTATUS
object, {
uuid (79eac9c1-baf-11 ce-8c82-00aaOO4ba90b), 65
BINDSTATUS FINDINGRESOURCE = 1
pointer default (unique) BINDSTATUS CONNECTING
BINDSTATUS REDIRECTING
 US 6,401,099 B1
21 22
-continued TABLE 6-continued
BINDSTATUS BEGINDOWNLOADDATA BINDVERB Enumeration Values
BINDSTATUS DOWNLOADINGDATA
BINDSTATUS ENDDOWNLOADDATA Value Description
BINDSTATUS BEGINDOWNLOADCOMPONENTS
BINDSTATUS INSTALLINGCOMPONENTS BIND VERB PUT Perform a “put operation. The data to put
BINDSTATUS ENDDOWNLOADCOMPONENTS should be specified in the stgmedData
BINDSTATUS USINGCACHEDCOPY member of the BINDINFO.
BINDSTATUS SENDINGREQUEST BINDVERB CUSTOM Perform a custom operation (protocol
BINDSTATUS CLASSIDAVAILABLE specific, see SZCustomVerb member of
BINDSTATUS MIMETYPEAVAILABLE BINDINFO). The data to use should be
BINDSTATUS CACHEFILENAMEAVAILABLE specified in the stgmed Data member of the
BINDSTATUS BEGINSYNCOPERATION BINDINFO.
BINDSTATUS ENDSYNCOPERATION
BINDSTATUS:
HRESULT OnStartBinding.( 15 5.5.2 The BINDINFOF Enumeration
in DWORD dwReserved, The BINDINFOF enumeration defines values that are
in IBinding * pib); passed to the client 152 within the IBindStatusCallback
HRESULT GetPriority( ::GetBindInfo function to specify additional flags for con
out LONG * pnPriority);
HRESULT On LowResource( trolling the bind operation. The values in the illustrated
in DWORD reserved): embodiment are shown in the following table.
HRESULT OnProgress(
in ULONG ulProgress, TABLE 7
in ULONG ulProgressMax,
in ULONG ulStatusCode, BINDINFOF Enumeration Values
in LPCWSTR szStatusText):
HRESULT OnStopBinding.(
in HRESULT hiresult, 25 Value Description
in, unique LPCWSTR szError); BINDINFOF URLENCODESTG Use URL encoding to pass is
local MEDDATA the data provided in the
HRESULT GetBindInfo( stgmed Data member of the
out DWORD grfBINDF, BINDINFO. (for PUT and POST
in, out, unique BINDINFO * pbindinfo); operations)
call as(GetBindInfo) BINDINFOF URLENCODEEXT Use URL encoding to pass is
HRESULT RemoteCietBindInfo( RAINFO the data provided in the
out DWORD grfBINDF, SzExtranfo member of the
in, out, unique RemBINDINFO * pbindinfo, BINDINFO.
in, out, unique RemSTGMEDIUM pstgmed):
local
HRESULT OnDataAvailable( 35 5.5.3 The BINDINFO Structure
in DWORD grfBSCF, The BINDINFO structure is returned to the asynchronous
in DWORD dwSize
in FORMATETC pformatetic, moniker 150 from the asynchronous moniker's call to the
in STGMEDIUM* pstgmed); IBindStatusCallback::GetBindInfo function. The client 152
call as(OnDataAvailable) of the asynchronous moniker 150 uses this structure to
HRESULT RemoteonDataAvailable( 40 qualify the bind operation. The meaning of this structure
in DWORD grfBSCF,
in DWORD dwSize, generally is specific to the class of the asynchronous moni
in RemFORMATETC *pformatetic, ker 150. The following table summarizes the meaning of the
in RemSTGMEDIUM* pstgmed); data values in the structure for the illustrated URL moniker
HRESULT OnObjectAvailable( class of asynchronous moniker described below.
in REFIID rid, 45
in, iid is(riid) IUnknown punk);
TABLE 8
cpp quote(“#endif)
BINDINFO Structure Members

5.5.1. The BIND VERB Enumeration Member Type Description

50
The BIND VERB enumeration defines values that are cbSize ULONG Size of this structure, in bytes.
SzExtranfo LPWSTR The behavior of this field is moniker
passed to the client 152 with the IBindStatusCallback: Get specific. For URL monikers, this
BindInfo function to distinguish different types of bind string is appended to the URL when
operations. The illustrated BIND VERB enumeration values the bind operation is started. Note:
are shown in the following table: 55 like all other OLE strings, this is a
Unicode string that the client should
allocate using CoTaskMemAlloc.
TABLE 6 The URL Moniker will free the
memory later.
BINDVERB Enumeration Values stgmedData STGMEDIUM Data to be PUT or POST
60
grfBindInfoF DWORD Flag from the BINDINFOF
Value Description enumeration specifying additional
flags modifying the bind operation.
BINDVERB GET Perform a “get operation (the default). The (URL specific
stgmedData member of the BINDINFO dw8indVerb DWORD A value from the BINDVERB
should be set to TYMED NULL. enumeration specifying the action to
BINDVERB POST Perform a “post operation. The data to post be performed for the bind operation.
should be specified in the stgmedData 65 SZCustomVerb LPWSTR String specifying a protocol specific
member of the BINDINFO. custom verb to be used for the bind
 US 6,401,099 B1
23 24
TABLE 8-continued TABLE 9-continued
BINDINFO Structure Members BINDF Enumeration Flags
Member Type Description Flag Description
operation (only if grfBindInfoF is set BINDF NOWRITE The moniker bind operation should not store
to BINDINFOF CUSTOM) CACHE retrieved data in the disk cache.
cbstgmed Data DWORD size of data in stgmedData
5.5.5 The BSCF Enumeration
5.5.4 The BINDF Enumeration
The BINDF enumeration defines flags that are returned to The BSCF enumeration defines flags that are passed to the
the binding object 164 from the client's IBindStatusCall client 152 by the asynchronous moniker 150 in a call to the
back: OnStartBinding function. The flags identify what type client's IBindStatusCallback: OnDataAvailable function to
of binding the asynchronous moniker 150 is to perform. The 15 clarify the type of data which is available. The flags in the
flags in the illustrated embodiment are shown in the follow illustrated embodiment are shown in the following table.
ing table.
TABLE 10
TABLE 9
BSCF Enumeration Flags
BINDF Enumeration Flags Flag Description
Flag Description BSCF FIRSTDATANOTIFICATIO Identifies the first call to
N IBindStatusCallback::OnDataAvail
BINDF ASYNCHR The moniker should return immediately from able for a given bind operation.
ONOUS IMoniker::BindToStorage or
IMoniker::BindToCbject. The actual result of 25 BSCF LASTDATANOTIFICATIO Identifies the last call to
N IBindStatusCallback::OnDataAvail
the object bind or the data backing the storage able for a bind operation.
will arrive asynchronously in calls to BSCF INTERMEDIATEDATANO Identifies an intermediate call to
IBindStatus.Callback::OnDataAvailable or
TIFICATION IBindStatusCallback::OnDataAvail
IBindStatusCallback::OnObjectAvailable. If the able for a bind operation.
client does not choose this flag, the bind
operation will be synchronous, and the client will
no receive any data from the bind operation
until the IMoniker::BindToxXX call returns. 5.5.6 The BINDSTATUS Enumeration
BINDF ASYNCST The client of IMoniker::BindToStorage prefers The asynchronous moniker 150 passes a Single Status
ORAGE that the IStorage and IStream objects returned value from the BINDSTATUS enumeration as the uStatus
in IBindStatusCallback::OnDataAvailable return
E PENDING when they reference data not yet 35 Code parameter to the IBindStatusCallback::OnProgress
available through I/O methods, rather than function to inform the client 152 about the progress of the
blocking until the data becomes available. This bind operation. The status values in the illustrated embodi
flag applies only to BINDF ASYNCHRONOUS ment are shown in the following table.
operations.
BINDF PULLDATA When this flag is specified, the asynchronous
moniker will allow the client of TABLE 11
40
IMoniker::BindToStorage to drive the bind
operation by pulling the data, (rather than BINDSTATUS Enumeration Status Values
having the moniker driving the operation and
pushing the data upon the client). Specifically, Status Value Description
when this flag is chosen, new data will only be
read/downloaded after the client finishes reading BINDSTATUS FINDINGRESOUR The bind operation is finding the
all data that is currently available. This means 45 CE resource that holds the object or
data will only be downloaded for the client after storage being bound to. The
the client does an IStream::Read operation that SzStatus Text accompanying
blocks or returns E PENDING. When the client IBindStatusCallback::OnProgress
chooses this flag, it must be sure to read all the () provides the display name of
data it can, even data that is not necessarily the resource being searched for
available yet. When this flag is not specified, 50 (e.g. "www.microsoft.com').
the moniker will continue downloading data and BINDSTATUS CONNECTING The bind operation is connecting
will call the client with to the resource that holds the
IBindStatus.Callback::OnDataAvailable object or storage being bound to.
whenever new data is available. This flag The SzStatus Text accompanying
applies only to BINDF ASYNCHRONOUS bind IBindStatusCallback::OnProgress
operations. 55 () provides the display name of
BINDF GETNEWE The moniker bind operation should retrieve the the resource being connected to
STVERSION newest version of the datafobject possible. (e.g. "www.microsoft.com').
BINDF NOPROGR If this bit is set, then only one BINDSTATUS REDIRECTING The bind operation has been
ESSIVERENDERIN IBindStatus.Callback::OnDataAvailable redirected to a different data
G notification will be generated, which will be after location. The SzStatus Text
the whole data is downloaded.
60
accompanying
BINDF OFFLINEO If this bit is set, the moniker code will not IBindStatusCallback::OnProgress
PERATION attempt network connection. If the data is () provides the display name of
available in the cache, then the binding the new data location.
operations will succeed, else they will fail. BINDSTATUS BEGINDOWNLOA The bind operation has begun
BINDF IGNORESE Ignore security problems and proceed with the DDATA receiving the object or storage
CURITY PROBLEM attempt to connect and download data. being bound to. The
BINDF RESYNCH Update the file in the cache if one on the server 65 SzStatus Text accompanying
RONIZE is later than the one in the cache. IBindStatusCallback::OnProgress
 US 6,401,099 B1
25 26
available through this function. The parameters and return
TABLE 11-continued values of the illustrated function are shown in the following
table.
BINDSTATUS Enumeration Status Values

Status Value Description TABLE 12

() provides the display name of IBindStatusCallback::QueryInterface Parameters and
the data location. Return Values.
BINDSTATUS DOWNLOADINGD The bind operation continues to
ATA receive the object or storage Parameter Type Description
being bound to. The
SzStatus Text accompanying rid REFID The REFIID for the interface for
IBindStatusCallback::OnProgress the requested service.
() provides the display name of ppvObject void* The interface returned by the
the data location. client.
BINDSTATUS ENDDOWNLOAD The bind operation has finished Returns S OK Success. The interface returned
DATA receiving the object or storage 15 is used by the moniker to
being bound to. The communicate further information
SzStatus Text accompanying pertaining to the bind operation.
IBindStatusCallback::OnProgress E NOINTERFACE The client does not know how to
() provides the display name of support the requested interface.
the data location. Note: if none of the callbacks
BINDSTATUS BEGINDOWNLOA This notification will be generated registered for a particular bind
DCOMPONENTS when code downloading starts. operation return S OK to this call,
BINDSTATUS INSTALLINGCOM This notification will be given the bind operation will perform
PONENTS when the code downloading is default action.
progressing. E OUTOFMEMORY Out of memory.
BINDSTATUS ENDDOWNLOAD This notification will be generated E INVALIDARG One of more arguments are
COMPONENTS when the code download is invalid.
complete. 25
BINDSTATUS USINGCACHEDC This notification will be generated
OPY if the data is found in the 5.5.8. The IBindStatusCallback::GetBindInfo Function
cache, and that data is going be
used (instead getting new data The asynchronous moniker 150 calls the IBindStatusCall
from the server). back::GetBindInfo function to obtain information from the
BINDSTATUS SENDINGREQUE Sending the http connection client 152 pertaining to the bind operation. The asynchro
ST request to the server.
BINDSTATUS CLASSIDAVAIL After the moniker figures out the nous moniker 150 calls this method within its implementa
ABLE classid from the bits, it will tions of the IMoniker:BindToCbject and BindToStorage
generate this notification. functions before returning. The parameters and return values
SzStatus Text field will contain the
class id in the sting form. 35
of the illustrated function are shown in the following table.
BINDSTATUS MIMETYPEAVAIL Same as above, after the moniker
ABLE figures out the mime type, the TABLE 13
notification will be generated.
SzStatus Text field will contain the IBindStatus.Callback::GetBindInfo Parameters and Return
MIME string. Values.
BINDSTATUS CACHEFILENAM This notification will be generated 40
EAVAILABLE if the the data is found in the Argument Type Description
cache, and that data is going be
used (instead getting new data pgrfBINDF DWORD* Location to return a value taken from
from the server). The name of the the BINDF enumeration which
cached file will be in the indicates whether the bind should
SzStatus Text field proceed synchronously or
BINDSTATUS BEGINSYNCOPE Called when URL moniker is 45 asynchronously.
RATION about to make sychronous RPC pbindinfo BINDINFO: Location to return the BINDINFO
call (e.g., CoCreateInstance, structure which describes how the
IpersistMoniker::Load, etc.). This caller wants the binding to occur.
give a chance for the host Return S OK Success.
application to put up busy cursor E INVALIDARG One or more arguments are invalid.
and block user input. 50
BINDSTATUS ENDSYNCOPERA Called after URL moniker is done
TION to make sychronous RPC call 5.5.9 The IBindStatusCallback: OnStartBinding Function
(e.g., CoCreateInstance,
IpersistMoniker::Load, etc.). At The asynchronous moniker 150 also calls the IBindSta
this time the host application can tusCallback: OnStartBinding function while initiating the
remove the busy cursor and 55 bind operation within its implementation of the IMon
enable the user input. iker::BindToStorage or IMoniker:BindToCbject functions.
In its call to this function, the asynchronous moniker 150
5.5.7 The IBindStatusCallback: QueryInterface Function passes an interface pointer of the IBinding interface 160 of
The asynchronous moniker 150 calls the IBindStatusCall the binding object 164 associated with the current bind
back: QueryInterface function to query the client 152 for 60 operation to the client 152. As detailed above, the IBinding
access to an interface which exposes additional Services interface 160 allows the client 152 to exert control over the
necessary for completing the bind operation. This function bind operation by calling the member functions on the
provides extensibility to the IBindStatusCallback interface, IBinding interface of the binding object. The client's bind
because it allows querying the client for new interfaces for status-callback object 166 stores the IBinding interface
passing information or querying information. The IEnum 65 pointer and maintains accurate reference counting by calling
Formatte interface of URL monikers described below is an the standard OLE AddRef and Release functions on the
example of additional client Services that can be made IBinding interface in accordance with OLE conventions.
 US 6,401,099 B1
27 28
The parameters and return values of the illustrated IBind
StatusCallback: OnStartBinding function are shown in the TABLE 16
following table. IBindStatusCallback::OnProgress Parameters and Return
Values.
TABLE 1.4
Argument Type Description
IBindStatusCallback::OnStartBinding Parameters and
Return Values. ulProgress ULONG Indicates the current progress of
the bind operation relative to the
Argument Type Description expected maximum indicated in
ulProgressMax.
dwReserved DWORD Reserved. ul ProgressMax ULONG Indicates the expected maximum
pbinding IBinding The IBinding interface of the current value of ulProgress for the
bind operation. May not be NULL. The duration of calls to OnProgress
client should call AddRef() on this for this operation. Note that this
pointer if it wishes to keep a reference value may change across
to the binding object. 15 invocations of this method.
Returns S OK Success. ulStatus.Code ULONG Provides additional information
E INVALI. The pbinding argument is invalid. regarding the progress of the
DARG bind operation. Valid values are
taken from the BINDSTATUS
enumeration.
SzStatusText LPCWSTR Information about the current
progress, depending on the
5.5.10 The IBindStatusCallback::GetPriority Function value of ulStatusCode as defined
for the BINDSTATUS
enumeration described above.
Typically, the asynchronous moniker 150 calls the IBind Returns S OK Success.
StatusCallback::GetPriority function to obtain the priority of E INVALIDARG One or more arguments are
25 invalid.
the bind operation prior to initiating asynchronous binding
by the binding object 164. Additionally, the function may be
called at any time during the bind operation if the asynchro 5.5.12 The IBindStatusCallback: OnDataAvailable Function
nous moniker 150 needs to make new priority decisions. The During asynchronous binding using the asynchronous
asynchronous moniker 150 can use the priority to set the moniker's IMoniker::BindToStorage function, the asynchro
nous moniker 150 calls the IBindStatusCallback:: On
actual priority of a thread associated with a download DataAvailable function to provide data to the client 152 as
operation (i.e., the thread executing the binding object 164), it becomes available. As described above, the behavior of
but more commonly the asynchronous moniker interprets the Storage passed to the client 152 by the asynchronous
the priority to perform its own Scheduling among multiple moniker 150 in the pStgmed parameter depends on the
35
bind operations. The parameter and return values of the BINDF flags that the client returned from the IBindStatus
illustrated function are shown in the following table. Callback::GetBindInfo function. More particularly, the stor
age may be asynchronous or blocking. Further, the bind
TABLE 1.5 operation may follow a “data pull” model or a “data push'
IBindStatusCallback::GetPriority Parameters and Return 40 model. For the data pull model, the client is notable to seek
Values. backwards in the data Stream provided by the asynchronous
moniker in the IBindStatusCallback: OnDataAvailable call.
Argument Type Description On the other hand, for push model bind operations, the client
pnPriority LONG* Location to return a value indicating 152 commonly can Seek back into a data Stream and read any
the priority of this download. Priorities 45 data that has been downloaded for an ongoing IMon
may be any of the constants defined iker::BindToStorage operation.
for prioritizing threads in Microsoft's The parameters and return values of the illustrated IBind
Win32 API. Default is priority normal. StatusCallback: OnDataAvailable function are shown in the
Returns S OK Success.
E INVALIDARG One or more arguments are invalid. following table.
50
TABLE 1.7
Parameters and Return Values of the
5.5.11 The IBindStatusCallback::OnProgress Function IBindStatusCallback::OnDataAvailable Function.

55 Argument Type Description

The binding object 164 calls the IBindStatusCallback
:: OnProgreSS function repeatedly to indicate the current grfBSCF DWORD Values taken from the BSCF
enumeration.
progreSS of the bind operation, preferably at reasonable dwSize DWORD The amount (in bytes) of total data
intervals during a lengthy bind operation. The client 152 available from the current bind
may use the progreSS notification to provide progreSS infor 60
operation.
pfmtetc FORMATETC* Indicates the format of the available
mation to the user, Such as by displaying a “% complete' bar data when called as a result of
graph, a download Status notification message or like IMoniker::BindToStorage. If there is
progreSS indicating user interface control. The client 152 no format associated with the avail
also may use the progreSS notification to make programmatic able data, pformatetic may contain
CF NULL.
decisions based on the uStatusCode parameter. The param 65 pstgmed STGMEDIUM* Holds the actual data that became
eters and return values of the illustrated function are shown available when called as a result of
in the following table.
 US 6,401,099 B1
29 30
and return values of the illustrated IBindStatusCallback
TABLE 17-continued :: OnStopBinding function are shown in the following table.
Parameters and Return Values of the TABLE 2.0
IBindStatusCallback::OnDataAvailable Function.

Argument Type Description BindStatusCallback:OnStopBinding function

IMoniker::BindToStorage. If it Argument Type Description
wishes to keep the data in pstgmed hrStatus HRESULT Status code which would have been
allocated, the client should call returned from the method that initiated
AddRef () on the bind operation
pstgmed->pUnkForRelease (IMoniker::BindToCbject or
(if the pointer is non-NULL). IMoniker::BindToStorage).
Returns S OK Success.
E INVALIDARG One or more arguments are invalid.
SzStatusText LPCWST Status text. In case of error, this string
R may provide additional information
describing the error. In case of success,
15 SzStatusText provides the friendly name
5.5.13 The IBindStatusCallback:OnObject Available Func of the data location bound to.
tion Returns S OK Success.
During asynchronous binding using the asynchronous
moniker's IMoniker::BindToCbject function, the asynchro 5.6 The IPersistMoniker Interface
nous moniker 150 calls the IBindStatusCallback: On Ob
ject Available function to pass the requested object interface The object 154 which is named by the asynchronous
pointer to the client 152. The asynchronous moniker 150 moniker can support an IPersistMoniker interface 170 to
never calls this function for asynchronous binding per obtain more control over the way the object is bound to its
persistent data. When instantiating and initializing the
formed using the IMoniker::BindToStorage function. The named object 154 in the IMoniker::BindToCbject function,
parameters and return values of the illustrated IBindStatus 25 the asynchronous moniker 150 queries the named object for
Callback:;OnObject Available function are shown in the fol persistence interfaces, Such as the IPersistMoniker Interface
lowing table. 170 or the standard OLE IPersistFile, IPersistStream Init),
or IPerSistStorage interfaces, which the asynchronous moni
TABLE 1.8 ker then utilizes in the bind operation to load the objects
persistent data. In the illustrated embodiment, the asynchro
Parameters and Return Values of the nous moniker 150 uses the highest precedence interface
IBindStatusCallback:OnObiectAvailable Function. supported by the object in the following order:
Argument Type Description IPersistMoniker, IPersistStream Init, IPersist Storage,
IPersistFile, IPersistMemory.
rid REFID The REFIID of the requested The IPersistMoniker interface 170 allows monikers and
interface. 35
punk IUnkown The object pointer requested in the
other application programs which instantiate objects from
call to IMoniker::BindToCbject. The persistent data to give control to the object 154 to choose
client should call AddRef() on this how the object is bound to its persistent data. The object 154
pointer in order to maintain a can implementa IPersistMoniker::Load function (described
reference to the object. below) with code that calls IMoniker::BindToStorage on a
Returns S OK Success.
E INVALIDARG One or more arguments are invalid.
40 moniker that names the object's persistent State and Specifies
a preferred interface and binding options, Such as IStorage,
IStream, asynchronously bound, etc.
5.5.14 The IBindStatusCallback: OnLowResource Function The IPersistMoniker interface 170 is defined as follows:
The asynchronous moniker 150 calls this function when it
detects low resources. The client 152 should free any 45
resource it no longer needs when receiving this notification. If--------------------------------------------------
The illustrated function's parameters and return values are If
shown in the following table. // Copyright (C) Microsoft Corporation, 1995-1996.
If
TABLE 1.9 50 If Contents: IPersistMoniker interface definition
If
IBindStatusCallback::OnLowResource Parameters and If--------------------------------------------------
Return Values. ccp quote(“#ifndef LPPERSISTMONIKER DEFINED)
cpp quote(“#define LPPERSISTMONIKER DEFINED)
Argument Type Description
55 object,
dwReserved DWORD Reserved for future use. Must be zero. uuid(79eac9c.9-baf'9-11ce-8c82-00aaOO4ba90b),
Returns S OK Success. pointer default (unique)
interface IPersistMoniker : IUnknown
5.5.15 The IBindStatusCallback: OnStopBinding Function {
The asynchronous moniker 150 calls IBindStatusCall 60 typedefunique iPersistMoniker *LPPERSISTMONIKER:
HRESULT GetClassID(
back: OnStopBinding function to indicate the end of the out CLSID *pClassID
bind operation. This function is always called, whether the );
bind operation Succeeded, failed, or was aborted by the HRESULT IsIDirty(void):
client 152. When this function is called, the client 152 must HRESULT Load.(
in BOOL fFully Available,
call the Release function on the IBinding interface pointer it 65 in IMoniker * pimkName,
received in the asynchronous moniker's call to the IBind in LPBC pibc,
StatusCallback: OnStartBinding function. The parameters
 US 6,401,099 B1
31 32
-continued TABLE 22-continued
in DWORD grfMode IPersistMoniker::Save Parameters and Return Values.
): 5
HRESULT Save( Argument Type Description
in IMoniker * pimkName,
in LPBC pbc, IPersistMoniker::Load method can treat
in BOOL fRemember); this value as a suggestion, adding more
HERESULT SaveCompleted.( restrictive permissions if necessary. If
in IMoniker * pimkName, grfMode is Zero, the implementation
in LPBC pibc): 1O should bind to the persistent state using
HRESULT GetCurMoniker( default permissions.
out IMoniker **ppimkName): Returns S OK Success.
S FALSE The object requires that the data be fully
cpp quote(“#endif) available.
E INVALI One or more arguments are invalid.
15 DARG
5.6.1 The IPersistMoniker::IslDirty Function
The IPersistMoniker::IsIDirty function checks whether the
persistent State of the object has changed since it was last 5.6.3 The IPersistMoniker::Save Function
saved. The illustrated function's return values are shown in The IPersistMoniker:Save function is called to request
the following table. that the object 154 save itself into the location referred to by
the moniker pointer parameter, pmkDSt. The illustrated
TABLE 21 function's parameters and return values are shown in the
PersistMoniker:IsDirty Return Values.
following table.
Argument Type Description 25 TABLE 23
Returns S OK Yes, the object has changed since it was last IPersistMoniker::Save Parameters and Return Values.
saved.
S FALS No, the object has not changed since it was Argument Type Description
E last saved.
pmkDst IMoniker* Moniker to the location where the
object should persist itself. The ob
5.6.2 The IPersistMoniker::Load Function ject typically binds to the location
The IPersistMoniker::Load function loads the object with using pmkDst->BindToStorage for
either IStream or IStorage. May be
its persistent state referred to by a parameter, pmkSrc. If the NULL, in which case the object is
fFully Available argument is true, the implementation of the 35
requested to save itself to the same
IPersistMoniker::Load function in the illustrated object location referred to by the moniker
immediately binds to its persistent State with the call, passed to it in IPersistMoniker::Load.
This may act as an optimization to
pmkSrc->BindToStorage(pbc, ), specifying either prevent the object from binding,
IStream or IStorage as the interface pointer parameter of the since it has typically already bound
call. Otherwise, if the fully Available argument is set to pbc bindCtX*
to the moniker it was loaded from.
false, the object's response to the call depends on whether 40 The bid context to use for any
moniker binding during this method.
the object Supports binding to its persistent State while the fRemember BOOL Indicates whether pmkDst is to be
data for that State is still in the process of being downloaded used as the reference to the current
to the Storage object. If So, the object's implementation of persistent state after the save. If
this function binds to its persistent State by calling the TRUE, pnkDst becomes the
45 reference to the current persistent
BindToStorage function of the moniker specified in the state and the object should clear its
pmkSrc argument as in the case where the fully Available dirty flag after the save. If FALSE,
argument is true. Otherwise, the object's implementation of this save operation is a “Save A
this function returns the value “S FALSE.” Copy As ... operation. In this case,
the reference to the current
The following table Summarizes the parameters and return 50 persistent state is unchanged and
values of the illustrated IPersistMoniker::Load function. the object should not clear its dirty
flag. If pmkDst is NULL, the
TABLE 22 implementation should ignore the
fRemember flag.
Returns S OK Success.
IPersistMoniker::Save Parameters and Return Values. E INVALI One or more arguments are invalid.
55 DARG
Argument Type Description
fFullyAvailable BOOL The data referred to by the moniker has
already been loaded once, Subsequent 5.6.4 The IPersistMoniker:SaveCompleted
binding to the moniker should be very Calling this function notifies the object that it has been
fast.
pmkSrc IMoniker* A reference to the persistent state to 60 completely Saved and points the object to its new persisted
initialize this object from. state. The implementation of this function in the illustrated
pbc IBindCtx* The bind context to use for any moniker object 154 immediately bind to the object's persistent state
binding during this method. using the code, pmkNew->BindToStorage(pbc., . . . ), and
grfMode DWORD A combination of the values from the
STGM enumeration which indicate the Specifying either IStream or IStorage, as in the implemen
access mode to use when binding to the 65 tation of IPersistMoniker::Load function. The parameters
persistent state. The and return values of the illustrated IPersistMoniker::Save
Completed function are shown in the following table.
 US 6,401,099 B1
33 34
TABLE 24 TABLE 26-continued
IPersistMoniker:SaveCompleted Parameters and Return Create AsyncBindCtX API Function Parameters and Return
Values. Values.

Argument Type Description Argument Type Description

pmkNew IMoniker* The moniker to the object's new persistent pbsc IBindStatusCallback The callback to receiving data
state, or NULL as an optimization if the : availability and progress
moniker to the object's new persistent state notification.
is the same as the previous moniker to the dwReserved DWORD Reserved.
objects persistent state - only allowed if penumfmtetc. IEnumFORMATETC Enumerator of formats to use
there was a prior call to : for format negotiation during
IPersistMoniker::Save with binding, if applicable. May be
fRemember=TRUE - in which case the NULL, in which case the caller
object need not rebind to pmkNew. is not interested in format
pbc BindCTX* The bind context to use for any moniker 15 negotiation during binding and
binding during this method. the default format of the object
Returns S OK Success. will be bound to.
E INVALI One or more arguments are invalid. ppbc BindCtx** Location to return the new
DARG bind-context.
Returns S OK Success.
E OUTOFMEMORY Out of memory.
5.6.5 The IPersistMoniker::GetCurMoniker Function E INVALIDARG One or more arguments are
This function is used to retrieve the moniker that refers to invalid.
the object's persistent State. Typically, this is the moniker
last passed to the object via IPersistMoniker::Load, IPer 5.7.2 The RegisterBindStatusCallback API Function
sistMoniker:Save or IPersistMoniker:SaveCompleted. The 25
The system 158 provides a RegisterBindStatusCallback
parameter and return values of the illustrated IPersistMoni API function having the following form.
ker::GetCurMoniker function are shown in the following HRESULT Register BindStatusCallback(pbc, pbsc,
table. dwReserved, dwReserved);
The client 152 call the RegisterBindStatusCallback API
TABLE 25 function to register its IBindStatusCallback interface with an
existing bind context. The RegisterBindStatusCallback API
IPersistMoniker::GetCurtMoniker Parameter and Return function also allows the client to specify flags that determine
Value. which callback notifications the client is capable of receiv
Argument Type Description ing. The client may implement functions for callback noti
fications that it does not receive as empty function stubs
ppmkCur IMoniker** Location to return the moniker to the 35 (returning E NOTIMPL).
object's current persistent state. This API function allows a single client at a time to
Returns S OK Success. register a callback for a same bind context. The API function
E INVALIDARG. The ppmkCur argument is invalid. outputs an interface pointer of a callback interface (if any)
which was previously registered for the Same bind context.
5.7 API Functions for Asynchronous Monikers 40 The client utilizes the previously registered callback inter
For use in asynchronous binding using the asynchronous face to chain callback notifications to other clients which
moniker 150, the system 158 provides several API functions had registered to receive callback notifications from the bind
COnteXt.
described below.
The parameters and return values of the RegisterBindSta
5.7.1. The Create AsynchbindCtX API Function tusCallback API function in the illustrated embodiment are
45
The system 158 provides a Create AsynchBindCtX API shown in the following table.
function having the following form:
HRESULT Create AsynclindCtX(dwReserved, pbsc, TABLE 27
dwReserved, penumfmtetc., ppbc); RegisterBindStatusCallback API Function Parameters and
The client 152 calls the Create AsyncBindCtX API func 50 Return Values.
tion to create an asynchronous bind context for use with the
asynchronous moniker 150. The Create AsyncBindCtX API Argument Type Description
function automatically registers the IBindStatusCallback pbc BindCtX* The bind context to register
interface 162 and the IEnumEORMATETC interface the call back with.
(described below) with the asynchronous bind context. 55 pbsc IBindStatusCallback The callback interface to
The parameters and return values of the illustrated Cre register.
dwReserved DWORD Reserved.
ate AsynclindCtX API function are shown in the following dwReserved DWORD Reserved for future
table. extension.
Returns S OK Success.
TABLE 26 60
E OUTOFMEMORY Insufficient memory to
register the callback with the
Create AsyncBindCtX API Function Parameters and Return bind context.
Values. E INVALIDARG One or more arguments are
invalid.
Argument Type Description
dwReserved DWORD Reserved for future use. Must 65 5.7.3 The RevokeBindStatusCallback API Function
be zero. The system 158 provides a Revoke BindStatusCallback
API function having the following form.
 US 6,401,099 B1
35 36
HRESULT Revoke BindStatusCallback(); monikers) to asynchronously bind to an object 208 named
The client 152 calls the RevokeBindStatusCallback API by an uniform resource locator (URL). URLs are a well
function to revoke a previous IBindStatusCallback interface known encoding of names and addresses of resources (e.g.,
registration in the asynchronous bind context. This call will documents, images, and other data) residing on the Internet.
not Succeed if it is made during a bind operation. URLS generally comprise a transport protocol identifier
(e.g., "http,” “ftp,” “gopher, etc.), a Site name (e.g.,
TABLE 28 "www.microsoft.com'), and a resource name (e.g.,
RevokeBindStatusCallback API Function Parameters and
“document.html), Such as the following text string
Return Values.
example: "http://www.microSoft.com/intclev/page.html.”
URLs are described in more detail in the following docu
Argument Type Description ments currently available from the Internet: Uniform
pbc BindCtX* The bind context to revoke the Resource Locators (URL), http://ds.internic.net/rfc/
callback from. rfc1738.txt; Relative Uniform Resource Locators, http://
pbsc IBindStatusCallback The callback interface to revoke. ds.internic.net/rfc/rfc11808.txt, Universal Resource Identi
Returns S OK
E FAIL
Success.
The IBindStatusCallback is not
15 fiers in WWW (RFC 1630), http://ds.internic.net/rfc/
registered on the bind context. rfc1630.txt, Names and Addresses, URIs, URLs, URNs,
E INVALIDARG One or more arguments are URCs, http://www.w3.org/pub/WWW/Addressing/
invalid. Addressing.html; and IETF Hypertext Transfer Protocol
(HTTP) Working Group, http://www.ics.uci.edu/pub/ietf/
5.7.4 The ISAsyncMoniker API Function http.
The URL moniker 200 is an instance of a class derived
The system 158 provides an ISAsyncMoniker API func from the asynchronous moniker class, and Supports the
tion having the following form. IMoniker interface 124. Since the IMoniker interface 124 is
HRESULT ISAsyncMoniker(pmk); derived from the IPersistStream interface, the URL moniker
By calling this API, the client 152 tests whether a moniker 25 200 also supports the IPersistStream, IPersist, and IUn
Supports asynchronous binding. The illustrated asynchro known interfaces (which are Standard OLE interfaces). Also,
nous moniker 150 implementation indicates that it is asyn as described above for the asynchronous moniker 150, the
chronous by Supporting an IMoniker ASync interface, an URL moniker 200 supports the IASyncMoniker interface
“empty' interface which is actually just IUnknown, having which is a stub interface that is used to allow the client 202
the following form. to determine whether the moniker Supports asynchronous
binding (which the URL moniker does).
In an asynchronous bind operation, the URL moniker 200
MyCustom Moniker:QueryInterface(REFIID rid, void** ppv) { makes use of a transport object 210 which Supports the
if (rid == IID IUnknown || rid == IID IPersistStream | rid IBinding interface 152 and implements an Internet transport
== IID IMoniker | rid == IID IAsyncMoniker) { 35 protocol (e.g., HTTP, FTP, Gopher or other transport
*ppv = this;
AddRef(); protocol) associated with the URL of the URL moniker. The
return S OK; illustrated transport object 210 is provided by the system
204, and additionally supports an IBindProtocol interface
return E NOINTERFACE:
212, the IParselDisplayName interface (described above),
40 and protocol Specific interfaces 214 which may be required
for interacting with other operating System components
involved in downloading data from the Internet (e.g., the
The implementation of the ISAsyncMoniker API function “WinSock” or “WinInet” layer of the Windows(R 95 oper
tests Support for this interface by the moniker to determine ating System).
if it is asynchronous. The parameter and return values of the 45 To Support asynchronous binding, the client 202 imple
illustrated ISAsyncMoniker API function are shown in the ments the bind-status-callback object 166 which supports
following table. the IBindStatusCallback interface 162, and registers the
IBindStatusCallback interface 162 with the asynchronous
TABLE 29 bind context 156. The illustrated client 202 additionally
IsAsyncMoniker API Function Parameter and Return
50 implements a format enumerator object 220 which Supports
Values. an IEnumFORMATETC interface 222 for media-type nego
tiation (described more fully below). The client 202 also
Argument Type Description registers the IEnumFORMATETC interface 222 with the
pmk IMoniker* The moniker to test. asynchronous bind context 156.
Returns S OK Yes, the moniker is asynchronous. 55 The client 202 makes use of the URL moniker 200 in a
S FALSE No, the moniker is not way generally Similar to the use of the asynchronous moni
asynchronous. ker 150 described above. The client 202 creates the asyn
E INVALIDARG The pmk argument is invalid.
chronous bind context 156 with a call to the Create Asyn
cBindCtX API function (described above) of the system
6. URL Monikers 60 component 204, and registers the IBindStatusCallback inter
According to the illustrated embodiment of the invention face 162 of its bind-status-callback object 166 in the asyn
shown in FIG. 7, a client program (hereafter “client”) 202 chronous bind context 156 with flags specifying which
utilizes an URL moniker 200 provided by an operating callback notifications the bind-status-callback object
system component (hereafter “system') 204 (specifically a receives from the URL moniker. The client 202 also creates
component such as the COM library 114 which also imple 65 the URL moniker 200, such as by calling the CreateURL
ments the API functions described above for asynchronous Moniker API function (described below) or the MkParse
monikers and the API functions described below for URL DisplayName API function of the system 204. From creating
 US 6,401,099 B1
37 38
the asynchronous bind context 156 and the URL moniker format(s) to the URL moniker 200 through FORMATETC
200, the client 202 obtains pointers to the IBindCtX interface data structures (described below) in the format enumerator
128 and the IMoniker interface 124 which the client stores object 220 which the client makes available from the
as pbc and pmk pointer variables 134, 136. The client 202 IEnumEORMATETC interface 222.
then calls the IMoniker::BindToCbject or IMoniker::Bind Each FORMATETC data structure specifies a clipboard
ToStorage functions of the URL moniker and passes an format value identifying a preferred data format (media
interface pointer of the IBindCtX interface 128 of the asyn type), a “NULL" target device value, a “DVASPECT
chronous bind context 156 to the URL moniker 200 to CONTENT' value, a “Ilindex' value of -1, and a
initiate binding to the object named by the URL moniker “TYMED NULL value. The clipboard format values are
200. value used by the well known OLE Clipboard protocol for
In the URL moniker's IMoniker:BindToCbject or Bind eXchanging data between two programs, Such as in cut/copy/
ToStorage function, the URL moniker 200 identifies the paste or drag-and-drop operations between programs. An
Internet protocol associated with the URL according to the example of code for creating a FORMATETC data structure
in the client 202 follows:
transport prefix of the URL, and retrieves the IBinding
interface 160 of the transport object 210 which implements 15
the associated Internet protocol. The URL moniker 200 also
looks up the IBindStatusCallback interface 162 of the bind FORMATEWTC fmtetc:
status-callback object 166 registered by the client 202 in the fmtetc.cfformat =
asynchronous bind context 156. The URL moniker 200 then RegisterClipboard Format(CF MIME POSTSCRIPT);
passes an interface pointer of the IBinding interface 160 to fmtetc.ptd = NULL;
fmtetc.dwAspect = DVASPECT CONTENT:
the bind-status-callback object 166 in a call to the OnStart fmtetc.lindex = -1;
Binding function on the IBindStatusCallback interface 162. fmtetc. tymed = TYMED NULL;
AS described above, the client calls functions on the IBind
ing interface 160 to effect pausing, cancellation, and priori A special clipboard format value, “CF NULL', can be
tization of the asynchronous binding operation. 25 used by the client 202 in a FORMATETC data structure to
The URL moniker 200 also passes its pointer for the indicate that the default media type of the resource pointed
IBindStatusCallback interface 162 to the transport object to by the URL should be retrieved. Although the FOR
210 when initiating the bind operation. During the bind MATETC data structure with the CF NULL clipboard
operation, the transport object 210 calls notification func format value can be placed anywhere within the enumerator,
tions on the IBindStatusCallback interface 162. In particular, the client 202 generally lists such a FORMATETC data
the bind-status-callback object 166 receives progreSS noti Structure as last in order of priority of the client's preferred
fication through the IBindStatusCallback::OnProgress data formats.
function, data availability notification through the IBindSta When no FORMATETC enumerator 220 is registered
tusCallback: OnDataAvailable function, as well as various with the asynchronous bind context 156 (which is a common
other notifications from the transport object 210 about the 35 case), the URL moniker 200 operates as if an enumerator
Status of the bind operation. containing a single FORMATETC with a clipboard format
The URL moniker 200 or transport object 210 may also value equal to CF NULL is available. More specifically, the
request extended information from the client 202 via the URL moniker 200 will automatically bind to or download
IBindStatusCallback: QueryInterface function, allowing the the default media-type of the resource named by the URL.
client 202 to provide protocol-specific information that will 40 When performing a bind operation for the client 202, the
affect the bind operation. URL moniker 200 translates the preferred data format(s)
6.1 Media-type Negotiation with the URL Moniker specified in the FORMATETC data structures into Multi
The URL moniker 200 supports media type negotiation in purpose Internet Mail Extension (MIME) media types.
order to allow clients to negotiate the format of the named MIME is a well known protocol for electronic mail
object's data to be downloaded in the URL's BindToStorage 45 eXchange on the Internet. Many application-level Internet
function (i.e., where the URL moniker downloads the named protocols are based on the eXchange of messages using
object's data directly into the computer's Secondary Storage MIME media types. MIME was originally developed for
42 (FIG. 1), rather than loading the data into the running eXchanging electronic mail messages with rich content
object 208). The client 202 requests preferred data format(s) acroSS heterogeneous networking, machine, and e-mail envi
using the IEnumFORMATETC interface 222 on the format 50 ronments. MIME has since been adopted in numerous
enumerator object 220. The client 202 creates the format non-mail applications, and Several of its useful core features
enumerator object 220, and registers the IEnumFOR extended by further protocols, such as HyperText Transfer
MATETC interface 222 with the asynchronous bind context Protocol (HTTP) used on the world wide web. Further
156. The client registers the IEnumFORMATETC interface details of MIME and its use in HTTP are described in the
222 in a call to the Create AsynclindCtX API function 55 following documents available from the Internet: MIME
(described above), or with the RegisterFormatEnumerator Overview, http://ds.internic.net/rfc/rfc1630.txt; Media Type
API function (described below) as shown in the following Registration Procedure, http://ds. internic.net/rfc/
example code: rfc1590.txt; and IETF- Hypertext Transfer Protocol
CreateBindCtX(0,&pbc); (HTTP) Working Group, http://www.ics.uci.edu/pub/ietf/
RegisterFormat numerator(pbc, &enumfmtetc, 0); 60 http.
The URL moniker 200 obtains an interface pointer to the The URL moniker 200 uses the MIME media types to
IEnumFORMATETC interface 222 from the asynchronous request downloading the data named by the URL using the
bind context 156 when performing a bind operation in the highest priority of the client's preferred data formats in
IMoniker::BindToStorage or BindToCbject functions. The which the data is available from its site on the Internet.
URL moniker 200 then calls functions on the IEnumFOR 65 MIME media types are simple Strings which denote a type
MATETC interface 222 to obtain the client's preferred data and subtype (such as “text/plain” or “text/html”) and are
format(s). The client 202 represents the requested preferred used to label data or qualify a request. In general, the URL
 US 6,401,099 B1
39 40
moniker 200 lists media types in the client's priority order,
and the Internet server (or world wide web site) where the TABLE 31
data resides responds with the highest priority available data CreateEormat numerator API Function Parameters and
format. For example, when the URL moniker is binding to 5
Return Values.
a URL of an image which specifies the HTTP protocol, the Argument Type Description
transport object 210 lists as part of an HTTP request-for-data
(Get Request-Line) or request-for-info (Head Request-Line) cfmtetc UINT The number of
FORMATETCS in
that it is requesting "image/gif” or "image/jpeg MIME rgfmtetc. May not be
media types. If the data is available in the image/gif data ZCO.

format, the world wide web site for the URL responds by rgfmtetc CLIPFORMAT: Static array of formats.
ppenumfmtetc EnumEORMATETC** Location to return the
returning the MIME media type of “image/gif” and option IEnumEORMATETC
ally the image data itself in the GIF format if the call was a interface of the
request-for-data. enumerator.

The client 202 is notified of the actual data format that it 15 Returns S OK Success.
E INVALIDARG One or more arguments
receives during the bind operation of the BindToStorage are invalid.
function through the pformatetic argument on the client's
IBindStatusCallback: OnDataAvailable function. 6.1.3 The RegisterFormatEnumerator API Function
6.1.1 The RegisterMediaTypes API Function The client 202 calls this API function to register the
This API function registers text strings of MIME media format enumerator object 220 onto the bind context 156.
types with corresponding clipboard format values for use in This allows the URL moniker 200 to query for the client's
clipboard format value to MIME media type mapping by the preferred data formats for media type negotiation in a
URL moniker 200 in media type negotiation for the client 25
Subsequent bind operation as described above. The Regis
202. The RegisterMediaTypes API function has the follow terFormat numerator API function has the following form:
ing form:
HRESULT RegisterMediaTypes(ctypes, rgszTypes, HRESULT RegisterFormatEnumerator(pbc, pFFetc, dwReserved);
rgcfTypes);
The parameters and return values of the RegisterMedi
aTypes API function are shown in the following table. The parameters and return value of the RegisterFormat
numerator API function are shown in the following table.
TABLE 30
TABLE 32
RegisterMediaTypes API Function Parameters and 35
Return Values. RegisterFormatEnumerator API Function Parameters and
Return Values.
Argument Type Description
Argument Type Description
ctypes UINT The number of media type strings in
the rgSZTypes array. May not be 40 pbc LPBC The pointer to the bind
ZCO. context.
rgSZTypes LPTSTR* Array of strings identifying the media pEFetc EnumEORMATETC* The format enumerator.
types to be registered. None may be dwReserved DWORD Reserved for future use,
NULL. must be Zero.
rgcfTypes CLIPFORMAT: An array of 32-bit values that should Returns S OK Success.
be assigned to the corresponding 45 E INVALIDARG One or more arguments are
media types in rgSZTypes. invalid.
Returns S OK Success.
E INVALIDAR One or more arguments are invalid.
G 6.1.4 The RevokeFormat numerator API Function
50
The client 202 calls this API function to removes the
6.1.2 The CreateEormat numerator API Function format enumerator object 220 from registration with the
asynchronous bind context 156. The API function has the
This function creates an object which implements the following form:
IEnumFORMATETC interface over a static array of FOR HRESULT RevokeFormatEnumerator(pbc, pEFetc);
MATETC data structures. The client 202 can call this API
function to create the format enumerator object 220 for use
55 The parameters and return values of the RevokeFormat
in media type negotiation with the URL moniker 200. The numerator API function are shown in the following table.
Createformat numerator API function has the following TABLE 33
form:
60 RevokeFormat numerator API Function Parameters and
Return Values.

HRESULT CreateFormatEnumerator(cfmtetc, rgfmtetc, Argument Type Description

ppenumfmtetc);
pbc LPBC The pointer to the bind
context.
65 pEFetc EnumEORMATETC* The format enumerator.
The parameters and return values of the CreateformatE Returns S OK Success - the format
numerator API function are shown in the following table.
 US 6,401,099 B1
41 42
TABLE 33-continued TABLE 34-continued
RevokeFormat numerator API Function Parameters and CreateURLMoniker API Function Parameters and Return Values.
Return Values.
5 Argument Type Description
Argument Type Description
IMoniker::BindToCbject or
enumerator was removed. IMoniker::BindToStorage.
E INVALIDARG One or more arguments are SZURL LPWSTR The display name to be parsed.
ppmk IMoniker** Location to return a moniker if
successful,
6.1.5 The CreateURLMoniker API Function Returns S OK Success.
E OUTOFM Out of memory.
The client 202 calls this function to create the URL EMORY
moniker 200 from a given URL. The function also can be MK E SYN A moniker could not be created
called from a ParselDisplayName function called through the TAX because SZURL does not correspond
15 to valid URL syntax for a full or partial
IParselDisplayName interface described above. The Cre URL. This is uncommon, since most
ateURLMoniker API function has the following form: parsing of the URL occurs during
binding and also since the syntax for
URLs is extremely flexible.

HRESULT CreateURLMoniker(pmkContext, SzURL, ppmk); 6.2 URL Moniker Functions

The implementation of the member functions of the URL
moniker 200 is described in further detail below. These
The CreateURLMoniker API function creates the URL functions have the form defined for the member functions of
moniker 200 from either a full URL string or from a partial the IUnknown, IASyncMoniker, IPersist, IPersistStream,
URL string. The partial URL string identifies a resource on 25 and IMoniker interfaces which are described above or are
the Internet relative to a base context. The full URL string well known OLE interfaces described in Inside Ole, Second
identifies a resource independent of any context. The caller Edition, Supra.
can create the URL moniker to name a partial URL String by 6.2.1 The URL Moniker-IUnknown::QueryInterface Func
Specifying a separate URL moniker that names the base tion
context as the pmkContext parameter. In this case, the The client 202 uses this function to request an interface
CreateURLMoniker API function retrieves the display name pointer of another of the OLE moniker's interfaces. The
of the base context URL moniker by calling the IMoniker URL Moniker 200 supports the interfaces, IUnknown,
::Get DisplayName function on the base context URL IASyncMoniker, IPersist, IPersistStream, and IMoniker. As
moniker, and then manually composes the base context described above, the IASyncMoniker interface is a stub
together with the partial URL string specified in the SZURL 35 interface having no member functions that is used to allow
parameter according to URL composition rules. the client 202 to determine transparently if the URL moniker
The caller alternatively can create the URL moniker 200 200 supports asynchronous binding. This function has the
from a partial URL String without Specifying the base form of the standard OLE IUnknown:QueryInterface func
tion.
context (i.e., with pmkContext=NULL). In such case, the 6.2.2 The URL Moniker-IPersist::Get ClassID Function
URL moniker 200 will draw further context during binding 40 This function returns the class identifier of the URL
(i.e., in the IMoniker::BindToobject and IMoniker::Bind moniker's class, CLSID Std URLMoniker. This function
ToStorage functions) from the asynchronous bind context has the form of the standard OLE IPersist::Get ClassID
156. The URL moniker 200 obtains the base context by function.
looking for a contextual URL moniker parameter held by the 6.2.3 The URL Moniker-IPersistStream::IsIDirty Function
asynchronous bind context 156, such with the function call, 45 The client 202 calls this function to check whether the
IBindCtx::Get Object Param(SZ URLCONTEXT, URL held by the URL moniker 200 has changed since the
(IUnknown)&pmkContext). The base context can be con URL moniker was last Saved to the computer's Secondary
tained as a set of URL monikers which form a composite storage 42 (FIG. 1). The implementation of this function in
moniker (a well known type of OLE moniker), in which case the URL moniker 200 returns the value, S OK, if the URL
the URL moniker 200 continues looking at each URL 50 Moniker 200 has changed since it was last saved (i.e., with
moniker to the left of the first URL moniker obtained from a call to the IPersistStream::Save function described below,
the IBindCtX::Get ObjectParam function call to complete the with the parameter f(learldirty==TRUE). Otherwise, the
base context. function returns the value, S FALSE. This function has the
form of the standard OLE IPersistStream::IsIDirty function.
The parameters and return values of the CreateURLMoni 6.2.4 The URL Moniker-IPersistStream::Load Function
ker API function are shown in the following table. 55
This function initializes the URL moniker 200 from data
(a URL String) Stored within a stream. The stream usually is
TABLE 34 stored previously using the URL moniker's IPersistStream
CreateURLMoniker API Function Parameters and Return Values. ::Save function described below (via OleSaveToStream or
60
OleSaveToStreamEx). The binary format of the stream is the
Argument Type Description URLstring in Unicode TM, which is a well known fixed width
16-bit encoding Standard of international character Sets. The
pmkContext IMoniker* The URL to use as the URL string may be a full or partial URL string as described
base context when SzURL is a partial above in connection with the CreateURLMoniker API func
URL string. NULL when szl JRL is a tion. The URL string is represented as a ULONG (32-bit)
full URL string or if this moniker will
retrieve full URL context from its left 65 data type value indicating a count of characters followed by
or from the bind-context during that many Unicode characters. This function has the form of
the standard OLE IPersistStream::Load function.
 US 6,401,099 B1
43 44
6.2.5 The URL Moniker-IPersistStream::Save Function resource. The illustrated transport object 210 retrieves the
This function saves the URL named by the URL moniker resource to a Stream object which Supports the Standard OLE
200 to a data Stream in the computer's Secondary Storage 42 interface, IStream.
(FIG. 1). The function saves the URL in a binary format The URL moniker 200 also passes an interface pointer of
comprising a ULONG (32-bit) data type value indicating a the transport object's IBinding interface to the client 202 at
count of characters in the URL followed by that many step 258 via the client's IBindStatusCallback: OnStart
Unicode TM characters. As described above, the URL may be Binding function. Finally at step 259, the IMoniker::Bind
a full or partial URLstring. This function has the form of the ToObject function of the URL moniker 200 returns the
standard OLE IPersistStream::Save function.
6.2.6 The URL Moniker-IPersistStream::GetSizeMax Func value, MK S ASYNCHRONOUS, to the client 202, with
tion NULL as the ppv output parameter. (The URL moniker only
This function returns the maximum number of bytes in the returns MK S ASYNCHRONOUS and performs asyn
data stream in which a subsequent call to the IPersistStream chronous binding if the client has requested asynchronous
::Save function Stores the URL of the URL moniker 200. The binding by setting the BINDF ASYNCHRONOUS flag as
function computes the maximum bytes value as SIZEOF shown at step 256 and described above.) The remaining
(ULONG)==4 plus SIZEOF(WCHAR)*n, where n is the 15 steps 260–271 of FIG. 8B are executed asynchronously (i.e.,
length of the full or partial URL string including the NULL without blocking the client’s execution) in the URL moni
terminator character. The function has the form of the ker's transport object 210.
standard OLE IPersistStream: GetSizeMax function. At step 260, the class (i.e., CLSID) associated with the
6.2.7 The URL Moniker-IMoniker::BindToCbject Function resource designated by the URL Moniker 200 is determined
This function has the form of the standard OLE IMon in one of several ways. In the case of the HTTP transport
iker::BindToCbject function, and implements the URL protocol, the initial HTTP response packet header that the
moniker's binding proceSS which instantiates the named transport object 210 receives when requesting the resource
object 208 as a running object in the computer's main from its Internet site may contain the CLSID associated with
memory 40 (FIG. 1). In the same manner as the asynchro the resource as an “Extension-Header” to the “Entity
nous moniker 150 described above, the URL moniker 200 25 Header' section of the “Full-Response” message. The
Supports asynchronous and Synchronous binding as deter CLSID in the HTTP response packet header is a character
mined by the client setting the BIND F String having the following form:
ASYNCHRONOUS flag passed in response to the URL
moniker's IBindStatusCallback: GetBindInfo function call.
FIGS. 8A-8B show the asynchronous binding process CLSID = “CLSID “: stringized-slsid
250 implemented in the IMoniker::BindToCbject function
of the URL moniker 200 (which the URL moniker performs
when the BINDF ASYNCHRONOUS flag is set). At a first Where Stringized-clsid is a character String created using the
step 252, the URL moniker 200 gets information for use in StringFromCLSID API function. The transport object 210
the bind operation from the asynchronous bind context 156, 35 interprets the stringized-clsid using the CLSIDFrom String
including particularly pointers for the IBindStatusCallback API function. The StringFromCLSID and CLSIDFrom
interface 166 and the IEnumEORMATETC interface 222 String API functions are well known OLE API functions.
which are registered by the client 202 in the asynchronous The extension header of the HTTP response packet is
bind context. described in more detail in the following documents avail
In a next step 253, the URL moniker 200 checks the 40 able from the Internet: Hypertext Transfer Protocol HTTP
running object table of the asynchronous bind context 156 to 1.0, http://www.ics.uci.edu/pub/ietf/http/draft-ietf-http-V10
determine if the object 208 named by the URL moniker is spec-04.html; IETF Hypertext Transfer Protocol (HTTP)
already running, Such as with the following code Statements: Working Group, http://www.ics.uci.edu/pub/ietf/http.
The URL moniker 200 also can determine the class
45 associated with the URL by examining the MIME media
type of the resource. If the resource has the media type,
IBindCtx::GetRunningObjectTable(&prot); “application/x-oleobject,” then the first 16-bytes of the
prot- > IsRunning (this);
resources actual (i.e., non-header) data (termed the
“Content-Body") contain the CLSID associated with the
If the named object 208 is already running, the URL 50 resource, and Subsequent data of the Content-Body is to be
moniker 200 retrieves the running named object 208 at step interpreted by the class identified by the CLSID. For all
254 (such as with the code statement: prot->Get Object(this, other media types, the URL moniker 200 looks in the system
&punk)), and continues to step 270 of FIG. 8B. registry for the key, HKEY CLASSES
Otherwise, the URL moniker 200 proceeds to query the ROOTVMIME \Database \Content-Type \k media
client 202 for bind information by calling the IBindStatus 55 types\CLSID, where <media-typed is the resource's media
Callback::GetBindInfo function at step 256. In this bind type and “CLSID' is the CLSID associated with that media
information, the client 202 indicates that the bind operation type.
is to be performed asynchronously by setting the BINDF The URL moniker 200 can further determine the CLSID
ASYNCHRONOUS flag. At step 257, the URL moniker 200 of the URL designated resource's class by matching portions
then initiates the bind operation with the transport object 210 60 of arriving data to patterns registered in the System registry
according to the bind information Specified by the client. under the keys, HKEY CLASSES ROOT\FileTypes, as is
The URL moniker 200 selects the transport object which well known in OLE and used in the GetClassFile API
implements the transport protocol Specified in the URL function.
prefix (e.g., an HTTP transport object for an URL with the Finally, if the above techniques fail, the URL moniker
prefix, *http:\\"). The transport object 210 begins retrieving 65 correlates the trailing extension of the resource's name (e.g.,
the resource designated by the URL, Such as by connecting “.gif,” “.html,” “...doc,” “.VSd,” etc.), if any, to a CLSID using
to the URL's Site on the Internet, and requesting the the HKEY CLASSES ROOT\,XXX keys in the system
 US 6,401,099 B1
45 46
registry, as is also well known in OLE and used in the other Internet-downloaded data, So the client must be Sure
GetClassFile API function and by the Windows(R operating not to delete the file.
System shell program. When the object 208 returns from one of the various
Next, at step 261, the URL moniker 200 creates the named IPersistXXX::Load calls above at steps 265, 267 and 269,
object 208 based on the resource's CLSID using the CoCre the URL moniker 200 queries the object using the IUn
atenstance API function, and requesting the IUnknown known: QueryInterface function at step 270 for an interface
interface. The URL Moniker 200 then calls the QueryInter pointer that the client 202 originally requested in the client's
face function on the IUnknown interface of the object 208 to call to the URL moniker's IMoniker::BindToCbject func
obtain the highest level IPersistXXX interface Supported by tion. Finally, at step 271, the URL moniker 200 returns this
the object (i.e., in the order IPersistMoniker, IPersistStream, interface pointer to the client using the client’s IBindSta
and IPersistFile) as shown at steps 262, 263,266 and 268. tusCall Back: OnObject Available function.
If the object 208 Supports the IPersistMoniker interface 6.2.8 The URL Moniker-IMoniker::BindToStorage Function
170, the URL moniker calls the objects's IPersistMoniker The client 202 calls the BindToStorage function to cause
::Load function and Specifies itself as that function's moni the URL moniker 200 to download the named resource into
ker parameter (e.g., by passing the pointer, “this,” as the 15 the secondary storage 42 of the computer 20 (FIG. 1). The
“pmkSrc' parameter) at step 264. If the transport object 210 implementation of the BindToStorage function in the illus
has already completed retrieval of the resource (i.e., the trated URL moniker 200 is similar to the BindToGbject
object's persistent state data), the URL moniker sets the function (i.e., having the operation shown in FIGS. 8A and
“ffully Available” argument of the Load function to TRUE. 8B) except that, rather than instantiating the data of the
Otherwise, where the transport object is still in the proceSS resource designated by the URL moniker as an object of a
of retrieving the resource (as is typical of the resource being class associated with the resource (as shown at Steps
retrieved from the Internet), the URL moniker sets the 260-269 of FIG. 8B), the URL moniker provides the
“ffully Available” argument to FALSE. resource's data to the client as a storage object. More
As explained above in the description of the IPersistMoni Specifically, in its call to the BindToStorage function, the
ker::Load function, the object 208 responds to this call to its 25 client 202 can specify the IStream, IStorage, or IUnknown
IPersistMoniker::Load function by, in turn, calling the URL interfaces (which are each well known OLE interfaces
Moniker's BindToStorage function and specifying the described in Inside OLE, Second Edition, supra). If the
object's preferred IPerSistXXX interface. An exception is IStream interface is requested, the URL moniker 200 pro
where the fully Available argument is set to FALSE vides the downloaded data to the client 202 as an object
(indicating the resource is not yet retrieved) and the object (“IStream object”) which supports the IStream interface. If
208 cannot load the resource as its persistent state while the the IStorage interface is requested and the resource named
resource is still being retrieved. In Such a case, the object by the URL moniker is an OLE compound file (a well known
208 returns the value “S FALSE, which causes the URL OLE file format described in Inside OLE, Second Edition,
moniker to wait and call the IPersistMoniker::Load function supra), the URL moniker 200 provides the downloaded data
on the Object 208 after retrieving the resource is completed. 35 to the client 202 as an IStorage object (i.e., an object
In this second call to the IPersistMoniker::Load function, the Supporting the IStorage interface). Otherwise, if IUnknown
URL moniker can then set the fully Available argument to is requested, the downloaded data is provided as a file. The
TRUE, and the object 208 can respond by calling the URL IStream or IStorage interface requested by the client 202 is
moniker's BindToStorage function while Specifying its pre passed to the client via the IBindStatusCallback:: On
ferred IPersistXXX interface. 40 DataAvailable function (in place of the step 271 of FIG. 8B
Otherwise, if the object 208 Supports the IPersistStream in the BindToCbject function).
interface, the URL moniker calls the object’s IPersist According to well known OLE conventions, if the client
Stream::Load function, and passes as a parameter of the call 202 needs access to the Storage object outside the Scope of
the IStream object which is being filled with the data of the the IBindStatusCallback: OnDataAvailable function, then
resource that the transport object 210 is downloading asyn 45 the client must call the AddRef function of the object whose
chronously from the Internet. This causes the object 208 to IUnknown interface pointer is passed in the punkForRelease
load its State from the resource that the transport object is field of the STGMEDIUM structure, which also contains the
asynchronously downloading. If the object 208 is of an Storage object. AS indicated above, the Storage object can be
asynchronously aware class (i.e., the CLSID of the object's an IStream or IStorage object, or it can be a name of a file
class is marked in the System registry with the category 50 in the file System. If the Storage object is an IStream or
CATID AsyncAware), the object can access the resource's IStorage object then the client must also call the AddRef
data from the IStream as it is downloaded by the transport function on the Storage object. After finishing with the
object 210 from the Internet with the IStream::Read and Storage object, the client must call the Release function on
IStream::Write functions. If the object's class is not in the the object whose interface is passed in the punkForRelease
asynchronously aware category, calls to the IStream::Read 55 field. In addition, the client must call Release on the IStream
or IStream::Write function which reference data that is not or IStorage object if one were avaliable. If the Storage object
yet available block until the data becomes available. If the happens to be a file System file, then the client must free the
object's class is marked with the category CATID memory allocated for the filename. The client must not
AsyncAware, then calls to the IStream::Read or IStream delete the file. The ownership of the file is with the object
::Write function which reference data not yet available 60 whose IUnknown interface pointer is the one which is used
return the value, E PENDING. for punkForRelease.
Finally, if the IPersistFile interface is the highest IPer As with the BindToCbject function, the client 202 can
sistXXX interface supported by the object, the URL moniker Specify Synchronous or asynchronous operation with the
200 completes the download of the resource's data into a BindToStorage function by setting the BINDF
temporary file. The URL moniker 200 then calls the load 65 ASYNCHRONOUS flag in the bind information returned
function on the object’s IPersistFile interface. In the illus when the URL moniker 200 calls the client's IBindStatus
trated embodiment, the temporary file is cached along with Callback:: GetBindInfo function. For synchronous
 US 6,401,099 B1
47 48
operation, the BindToStorage function blockS execution of string designated by the URL moniker 200). The function
the client 202 during downloading of the resource desig checks whether the other moniker's CLSID (obtained via the
nated by the URL moniker 200. For asynchronous operation, IPersist::GetClassID function) is CLSID URLMoniker,
the URL moniker 200 returns immediately from the Bind and also compares the display names of the URL moniker
ToStorage function, and the client 202 is not blocked. 200 and the other moniker for equality. If the other moniker
In cases where the data is provided as the IStream or is equivalent to the URL moniker, the function returns
IStorage objects, the client 202 can further request asyn S OK. If not, the function returns S FALSE.
chronous storage operation by setting the BINDF 6.2.13 The URL Moniker-IMoniker::Hash Function
ASYNCSTORAGE flag in the bind information returned This function creates a hash value based on the URL
from the client's IBindStatusCallback::GetBindInfo func designated by the URL moniker 200. The function typically
tion. When asynchronous Storage is requested, the IStream is used to Speed up comparisons by reducing the number of
or IStorage object provided by the URL moniker 200 allows times that it is necessary to call the ISEqual function.
the client 202 to access the data as it is downloaded. When 6.2.14 The URL Moniker-IMoniker::IsRunning Function
the client 202 call the Read function on the IStream or This function returns S OK if the URL moniker 200 is
IStorage interface, the IStream or IStorage object returns the 15 currently “running”, otherwise returns S FALSE. The
data if available, or returns the value E PENDING if not implementation of the function in the illustrated URL moni
yet available. Otherwise, if asynchronous Storage is not ker 200 determines if the URL moniker is running by first
requested, the IStream or IStorage object provided by the checking whether the URL moniker is equal to the newly
URL moniker 200 blocks the client 202 when the client calls running moniker (i.e., by calling pmkNewly Running
the Read function on the object. >IsEqual(this)), and next by checking whether the URL
6.2.9 The URL Moniker-Moniker::Reduce Function moniker 200 is registered with the Running Object Table of
In the illustrated URL moniker 200, this function returns the bind context 156.
a value, MK S REDUCED TO SELF, and a pointer to 6.2.15 The URL Moniker
itself (i.e., the pointer, “this') as its output parameter, IMoniker::GetTimeOfLastChange Function
* ppmkReduced. 25 This function returns the time of last change of an object
6.2.10 The URL Moniker-IMoniker::ComposeWith Func that is registered in the running object table of the bind
tion context 156.
The illustrated URL moniker 200 supports composition 6.2.16 The URL Moniker-IMoniker::Inverse Function
via this function. More specifically, the URL moniker 200 This function returns the value, MK E NOINVERSE.
composes itself together with a relative moniker (a moniker 6.2.17 The URL Moniker-IMoniker: Common Prefix With
that names a resource relative to that named by the URL Function
moniker) to form a resulting moniker whose encapsulated This function computes a common prefix of the URL
name is a composite of those of the URL and relative moniker 200 and a specified other URL moniker.
monikers. The function parses the name held by the relative 6.2.18 The URL Moniker-IMoniker::RelativePathTo Func
moniker which is specified as an argument to the function 35 tion
according to the RFC Syntax rules, and creates an appropri This function computes a relative path between the URL
ate moniker to hold the composite name according to the moniker 200 and a specified other URL moniker.
type of the relative moniker. For example, if the relative 6.2.19 The URL Moniker-IMoniker: Get DisplayName
moniker is a file moniker (a well known type of OLE Function
moniker) which names a file relative to a base URL specified 40 This function returns the URL string designated by the
by the URL moniker (e.g., the file is stored in a directory URL moniker 200. The function returns the full URL string
Specified by the URL on a server), the function composes the if the URL moniker designates a full URL string. If the
base URL plus the file name into a composite URL and moniker was created with a partial URL String (as described
creates a URL moniker to hold the composite URL. On the above for the CreateURLMoniker), the function attempts to
other hand, if the relative moniker is an item moniker 45 find an URL moniker which designates a base context of the
(another well known type of OLE moniker) which names an URL moniker 200. The function 200 first checks in the bind
embedded item relative to the base URL of the URL moniker context 156 under the data member, SZ URLCONTEXT,
(e.g., the item names an Excel spreadsheet embedded in a and next checks to the left of the URL moniker if the URL
Word document whose location on the Internet is specified moniker is part of a compound moniker. If the function does
by the base URL), the function creates a generic composite 50 not find a base context, the function returns the partial URL
moniker (also a well known type of OLE moniker) to name string designated by the URL moniker 200.
the item. 6.2.20 The URL Moniker-IMoniker::Parse|DisplayName
The caller of this function can set the fonlyIfNotGeneric Function
argument to TRUE to cause the function not to return a This function parses a full or partial URLstring (which is
generic composite moniker. If the function's fonlyIfNotGe 55 input as parameter, SZDisplayName) to create a resulting
neric flag is set to TRUE and the composition will result in URL moniker (which is output as paramter, ppmkOut). If the
a composite moniker, the function returns the value, SZDisplayName parameter represents a full URL String (e.g.,
MK E NEEDGENERIC. “http://foo.com/default.html”), the function creates a new
6.2.11 The URL Moniker-IMoniker::Enum Function full URL moniker which designates the full URL string. If
This function returns the value, S OK, and sets its 60 the SZDisplayName parameter represents a partial URL
“ppenumMoniker' output parameter to NULL, indicating String (e.g., "...Vdefault.html), the function creates a new full
that the URL moniker 200 does not contain Sub-monikers. URL moniker which designates a full URL string formed by
6.2.12 The URL Moniker-IMoniker::IsBqual Function combining the parameter with a base context from either the
This function checks another moniker Specified in its SZ URLCONTEXT object-parameter of the bind context
pmkOtherMoniker parameter is equivalent to the URL 65 156 or from the URL moniker 200. For example, if the
moniker 200, meaning the other moniker also is of the URL context moniker is “http://foo.com/pub/list.html and SZDis
moniker class and has a same display name (i.e., the URL playName is “..\default.html,” the resulting URL moniker
 US 6,401,099 B1
49 SO
would represent “http://foo.com/default.html.” The function
is used by the MkParselDisplayName (described in the TABLE 35
Moniker Overview section above) and MkParse Dis The IAuthenticate::Authenticate
playNameEX (described below) API functions. Function Parameters and Return Values.
6.2.21 The URL Moniker-IMoniker::IsSystemMoniker Argument Type Description
Function
This function returns the value, S TRUE, and outputs the phwind HWND * Client-provided HWND of the
parent window for default
value, MKSYS URLMONIKER, as its output parameter, authentication UI. If no UI is
*pdwMksys. desired, the client must provide a
6.3 Client Extension Services user name and password in the
other parameters, and this handle
In some cases, the bind operation with the URL moniker SZUsername LPWSTR
is set to the value -1.
Client-provided user name for
200 requires additional services from the client 202 in order authentication. If the client
to complete negotiations necessary for downloading the 15 returns a value here it should also
resource designated by the URL moniker from the Internet. SZPassword LPWSTR
set phwind = -1.
Client-provided password for
The illustrated client 202 supports an IAuthenticate interface authentication. If the client
230 and an IHttpNegotiate interface 232 which expose returns a value here it should also
services for authentication and HTTP negotiations. The URL set phwind = -1.
moniker 200 requests pointers to these interfaces using the Returns S OK Success.
E INVALIDARG One or more arguments are
IBindStatusCallback: QueryInterface function. invalid.
6.4 The IAuthenticate Interface
The illustrated client 202 supports the IAuthenticate inter 6.5 The IHttpNegotiate Interface
face 230 to provide a Service, the authentication function, 25 The URL moniker 200 utilizes the services provided by
which the URL moniker 200 calls to retrieve information the illustrated client 200 through the IHttpNegotiate inter
needed for authentication during a download. The illustrated face 232 to allow the client to negotiate HTTP download
IAuthenticate interface is defined as follows: parameters. The IHttpNegotiate interface 232 is defined as
follows:

If----------------------------------------------------------------------------
If If----------------------------------------------------------------------------
// Copyright (C) Microsoft Corporation, 1995-1996. If
If // Copyright (C) Microsoft Corporation, 1995-1996.
If Contents: IAuthenticate interface definition If
If 35 If Contents: IHttpNegotiate interface definition
If---------------------------------------------------------------------------- If
cpp quote(“#ifndef LPAUTHENTICATION DEFINED) If----------------------------------------------------------------------------
cpp quote(“#define LPAUTHENTICATION DEFINED) cpp. quote(*#ifndef LPHTTPNEGOTIATE DEFINED)
cpp quote(“#define LPHTTPNEGOTIATE DEFINED)
local, 40
object, object,
uuid(79eac9d0-baf9-11ce-8c82-00aaOO4ba90b), uuid (79eac9d2-baf'9-11ce-8c82-00aaOO4ba90b),
pointer default (unique) pointer default (unique)

interface IAuthenticate : IUnknown 45 interface IHttpNegotiate : IUnknown

{
typedefunique IAuthenticate *LPAUTHENTICATION: typedefunique IHttpNegotiate *LPHTTPNEGOTIATE:
HRESULT Authenticate( HRESULT BeginningTransaction.(
out HWND* phwind, in LPCWSTR szURL,
out LPWSTR *pszUsername, 50 in, unique LPCWSTR SzHeaders,
out LPWSTR *pszPassword in DWORD dwReserved,
); Out LPWSTR pszAdditional Headers);
cpp quote(“#endif) HRESULT OnResponse(
in DWORD dwResponseCode,
in, unique LPCWSTR SZResponseHeaders,
55 in, unique LPCWSTR SZRequestHeaders,
The Authenticate member function of this interface is
Out LPWSTR *pszAdditional RequestHeaders);
called by the URL moniker 200 when it needs basic authen
tication information from the client 202. In response, the cpp quote(“#endif)
client 202 can return a user name and a password Strings to
the URL moniker 200. Alternatively, the client can provide 60 6.5.1 The IHttpNegotiate::BeginningTransaction Function
a window handle, HWND, of a window that is used to The URL moniker 200 calls this function before sending
present a default authentication user interface. The URL an HTTP request for downloading the resource designated
moniker 200 uses the authentication user interface to obtain by the URL moniker. In the URL moniker's call to this
authentication information (i.e., the user name and function, the URL moniker notifies the client of the URL of
password) from the user. The parameters and return values 65 the resource which is to be downloaded in the HTTP request.
of the illustrated Authenticate function are shown in the The URL moniker 200 also allows the client 202 to add
following table. additional headers to the HTTP request. The illustrated
 US 6,401,099 B1
S1 52
IHttpNegotiate::BeginningTransaction function has the
parameters and return values shown in the following table. TABLE 38-continued

TABLE 36 IHttpNegotiate:OnBrror Function Parameters and Return Values

IHttpNegotiate::BeginningTransaction Argument Type Description
Function Parameters and Return Values S FALSE Do not append any
headers.
Argument Type Description E INVALIDARG The argument is invalid.
E ABORT Abort the HTTP
SZURL LPCWSTR The URL for the HTTP transaction.
1O
transaction.
dwReserved DWORD Reserved for future use.
SzHeaders LPCWSTR The current request 6.6 Display Name Parsing
headers.
SZAdditionalEHeaders LPWSTR Additional headers to With reference still to FIG. 7, the illustrated system 204
append to the HTTP 15
extends parsing of display names into monikers to also
request header. support the Universal Resource Indicator (URI) syntax,
Returns S OK Success, append the
headers.
which is used for Internet URLs. The URI syntax specifies
S FALSE Do not append any
that a String begins with a transport protocol identifier
headers. followed by a colon character (e.g., “http:” for the Hypertext
E INVALIDARG The argument is invalid. Transport Protocol, “ftp:” for the File Transport Protocol,
E ABORT Abort the HTTP etc.). A Sub-String following the transport protocol prefix
transaction. designates a resource and its site. The URI syntax is
described in the IETF RFC1630 specification, which is
available from the Internet at “http://ds.internic.net/rfc/
6.5.2 The IHttpNegotiate: OnHeaders Available Function rfc1590.txt.'
This function is called by the URL moniker 200 to 25 For parsing URI syntax display names, the illustrated
provide the client with the HTTP response header informa system 204 provides a MkParselDisplayNameEX API func
tion used in downloading the resource designated by the tion. Similar to the MkParselDisplayName API function
URL moniker. In the function, the client 202 may examine described in the Moniker Overview section above, this API
these headers and choose to abort the HTTP transaction. The function is called by the client 202 to obtain a moniker that
illustrated IHttpNegotiate::OnHeaders Available functions references data identified by a text String (referred to herein
parameters and return values are shown in the following as the “display name” of the data). This is referred to herein
table. as "parsing the display name.
In an initial Step of the parsing process, the MkParselDis
TABLE 37
playNameEX API function parses a first portion of the
display name and creates an initial moniker appropriate to
IHttpNegotiate::OnHeadersAvailable
35 that portion. For parsing with the MkParselDisplayNameEx
Function Parameters and Return Values API function, the display name is allowed to begin in one of
three ways: with a programmatic identifier (“ProgID") fol
Argument Type Description lowed by a colon character (":"), with a valid file system
dwResponseCode DWORD HTTP response code. name, or with the 'G' character followed by a ProgID. A
SzHeaders LPCWSTR The response headers (a 40 ProgID is a short text string used in the Windows(R operating
NULL-terminated string). System registry to uniquely identify classes of objects
Returns S OK Success. Continue the installed on the computer system. The ProgID follows a
HTTP transaction.
E INVALIDARG The argument is invalid.
Syntax that the String: (1) have no more than 39 characters,
E ABORT Abort the HTTP transaction. (2) contain no punctuation (including underScore), except
45 that it may contain one or more periods, (3) not start with a
digit, and (4) differ from any OLE version 1 class name.
6.5.3 The IHttpNegotiate:OnError Function Programmatic identifiers are described, inter alia, in OLE 2
The URL moniker 200 calls this function when an HTTP Programmer's Reference, Volume One, Microsoft Press,
error occurs that cannot be resolved. The function allow the 1994.
client 202 to add HTTP headers that are used to respond to 50 The MkParselDisplayNameEX API function creates the
the error. The function's parameters and return values are initial moniker by attempting each of the following Strate
shown in the following table. gies in order.
“ProgID:” Case. If a prefix of the display name in the
TABLE 38 SZDisplayName parameter conforms to legal ProgID
55 Syntax, is longer than a Single character, and is followed
IHttpNegotiate:OnBrror Function Parameters and Return Values by a colon character (:), the API function converts the
Argument Type Description ProgID to a CLSID using the CLSIDFromProgID API
function (a well known Windows(R operating system
dwResponseCode
SZRequestHeaders
DWORD
LPCWSTR
HTTP response code.
HTTP headers sent to the
API function). The MkParse|DisplayNameEx API func
HTTP server.
60 tion then calls the CoCreatenstance API function
SZResponseHeader LPCWSTR Response headers from (described in the Document Object and Server Over
the HTTP server. view Section above) to create an object of the class
SZAdditional Request
Headers
LPWSTR Headers to add to the
request headers before
identified by the CLSID (which is the initial moniker),
resending. and obtains an interface pointer to the IParselDis
Returns S OK Success, append the 65 playName Interface on the initial moniker.
headers to the request. Running Object Table Case. If a prefix of the display
name is a valid file name, the MkParselDisplayNameEx
 US 6,401,099 B1
S3 S4
API consults the running objects table for a file moni following table 39.
ker that references the file name. If there is a running
file moniker that references the display name prefix, the
MkParsedisplayNameEX API treats the file moniker as
the initial moniker. 5 HRESULT MkParseDisplayNameEx(in IBindCtx* pbc, in LPWSTR
SZDisplayName, out ULONG*pcchEaten, out IMoniker** ppmk);
File System Case. The MkParselDisplayNameEX API
function consults the file system of the computer 20
(FIG. 1) to check whether a prefix of the display name
matches any existing file in the file System. The TABLE 39
MkParsedisplayNameEX API function then creates a
file moniker (as described in the Moniker Overview MkParsedisplayNameEX API Function Parameters and Return Values
section above) which references this file as its initial Argument Type Description
moniker.
“GProgID Case. If the initial character of the display pbc BindCtX* The binding context in which to
accumulate bound objects.
name is the (O) character, the MkParse Dis 15 SZDisplayName LPCWSTR The display name to be parsed.
playNameEx API function converts a portion of the pcchEaten ULONG* On exit the number of characters of the
display name following the (G) character which con display name that was successfully
forms to the ProgID syntax into a CLSID using the parsed. Most useful on syntax error,
when a non-zero value is often
CLSIDFromProgID API function. The MkParselDis returned and therefore a subsequent
playNameEX API function then creates a instance of the call to MkParselDisplayNameEx with
class identified by the CLSID (which is the initial the same pbc and a shortened
SZDisplayName should return a valid
moniker). moniker.
The MkParselDisplayNameEx API function then itera ppmk IMoniker** Location to return a moniker if
tively calls the IParselDisplayName::ParsedisplayName successful.
function of the moniker it has created thus far (the “current” 25 Returns S OK Success.
moniker), passing a Suffix portion of the display name which MK E SYN Parsing failed because SZDisplayName
TAX could only be partially resolved into a
remains to be parsed (the “current” portion) in the call. The moniker. In this case, pcchEaten
ParselDisplayName function parses this remaining portion of holds the number of characters that
the display name into a new moniker, and returns the new were successfully resolved into a
moniker with a new Suffix portion of the display name that moniker prefix.
E OUTOF Out of memory.
remains to be parsed. The returned moniker and display MEMORY
name portion become the current moniker and current
portion in the next iteration of this step. The iterations end Having described and illustrated the principles of our
when the display name is fully parsed, an error occurs, or the invention with reference to an illustrated embodiment, it will
remaining Suffix of the display name cannot be parsed. AS a 35
be recognized that the illustrated embodiment can be modi
result of the iterative parsing, the MkParselDisplayNameEx fied in arrangement and detail without departing from Such
API function creates a Succesion of increasingly more principles. It should be understood that the programs,
Specific monikers which it combines into a composite moni processes, or methods described herein are not related or
ker. Each Successive moniker is able to parse a next more limited to any particular type of computer apparatus, unless
Specific portion of the display name into a moniker. For 40 indicated otherwise. Various types of general purpose or
example, a display name can be parsed by the API function Specialized computer apparatus may be used with or perform
into a composite moniker which includes a file moniker that operations in accordance with the teachings described
references a file designated in the display name, and an item herein. Elements of the illustrated embodiment shown in
moniker that references a part of the file designated in a Software may be implemented in hardware and Vice versa.
further portion of the display name. 45 In view of the many possible embodiments to which the
The MkParselDisplayNameEX API function supports the principles of our invention may be applied, it should be
URI syntax in an extensible fashion with the “ProgID:” case recognized that the detailed embodiments are illustrative
Strategy for parsing the display name prefix to an initial only and should not be taken as limiting the Scope of our
moniker. In the illustrated embodiment, the display name invention. Rather, we claim as our invention all Such
prefixes that designate Internet transport protocols (e.g., 50 embodiments as may come within the Scope and Spirit of the
“http:,” “ftp:,” and “gopher:”) are registered as ProgIDs in following claims and equivalents thereto.
the system registry which map to a CLSID for the URL We claim:
moniker. Thus, when the MkParselDisplayNameEX API 1. An object-oriented framework for providing asynchro
function is called to parse an URL, the MkParsedis nous retrieval of data from a Storage site for a client, wherein
playNameEx API function creates a URL moniker in its 55 the client comprises plural instructions for executing, the
initial parsing step, and calls the URL moniker's IParsedis object-oriented framework comprising:
playName::ParselDisplayName function to parse the remain a naming object having a reference to the data; and
der of the URL. Likewise, the MkParse|DisplayNameEX API a binding function callable from the client to initiate
function can be extended to parse display names with new asynchronous retrieval of the data from the Storage Site,
transport protocols by registering the protocol identifier as a 60 the client continuing instruction execution indepen
ProgID in the System registery that maps to a handler dently of the retrieval of the data from the storage site.
moniker, and implementing a ParsedislayName function in 2. The object-oriented framework of claim 1 comprising:
the handler moniker to parse display names using the a bind context object for the client to register a call back
protocol. interface callable from the naming object, wherein the
The MkParselDisplayNameEX API function is defined as 65 call back interface exposes one or more functions
shown in the following C programming language Statement, Supported by the client for the naming object to invoke
and has the parameters and return values shown in the in order to initiate communication with the client.
 US 6,401,099 B1
SS S6
3. The object-oriented framework of claim 2 wherein the naming object operating to retrieve the data in an
call back interface exposes a function operable to notify the available one of the preferred formats from the remote
client about progreSS of the data retrieval. computer network.
4. The object-oriented framework of claim 2 wherein the 17. The object-oriented framework of claim 13 compris
call back interface exposes a function for the naming object 5 ing:
to get parameters relating to the data retrieval from the a bind context object for the client to register an interface
client, whereby the client controls aspects of the data provided by the client having an authentication func
retrieval. tion callable from the naming object for the client to
5. The object-oriented framework of claim 1 wherein the provide authentication of the data retrieval from the
naming object operates in a data pull mode to retrieve the remote computer network.
data from the Storage Site when the client reads the data. 18. The object-oriented framework of claim 13 in which
6. The object-oriented framework of claim 1 wherein the the naming object performs parameter negotiation between
naming object operates in a data push mode to retrieve the the client and the remote computer network of a transport
data from the Storage Site and notify the client when the data protocol with which the naming object retrieves the data
is available for reading. 15
from the remote computer network.
19. The object-oriented framework of claim 13 compris
7. The object-oriented framework of claim 1 comprising: ing:
an asynchronous Storage object provided by the naming a bind context object for the client to register an interface
object for Storing the data retrieved from the Storage provided by the client having functions callable from
Site, and for allowing access by the client to a part of the naming object for the client to negotiate parameters
the data already retrieved from the Storage Site during of a transport protocol for retrieving the data from the
the data retrieval before the data retrieval is completed. remote computer network.
8. The object-oriented framework of claim 7 wherein the 20. A method of retrieving data in a computer System,
asynchronous Storage object has a non-blocking mode in comprising:
which execution of the client is not blocked when accessing providing an interface of a naming object having a
a part of the data not yet retrieved from the Storage Site, and 25
reference designating Stored data to a client application,
a blocking mode in which execution of the client is blocked wherein the client application comprises plural instruc
when accessing the part of the data not yet retrieved from the tions for executing, the interface exposing a binding
Storage Site, the asynchronous Storage object operating in the function of the naming object operative to perform a
blocking or non-blocking mode as Set by the client. binding operation on the Stored data; and
9. The object-oriented framework of claim 1 wherein the on a call from the client application to the binding
naming object is operative to perform asynchronous or function, initiating binding the Stored data as a back
Synchronous data retrieval depending on a flag Set by the ground process while returning execution to the client
client. application, the client application continuing instruc
10. The object-oriented framework of claim 1 comprising: tion execution independently of the binding operation
35
a function provided by the naming object for the client to on the Stored data.
interrupt the data retrieval. 21. The method of claim 20 comprising receiving a call
11. The object-oriented framework of claim 1 comprising: back interface on the client application, the call back inter
a binding interface provided by the naming object and face exposing at least one function Supported by the client
having functions callable from the client to cause the 40
application callable from the naming object for Sending
data retrieval to abort, Suspend, and resume. notifications relating to the binding operation of the Stored
12. The object-oriented framework of claim 1 comprising: data from the naming object to the client application.
a plurality of other naming objects for retrieving data 22. The method of claim 21 comprising:
from Storage Sites, repeatedly calling a progreSS notification function of the
the naming object performing the data retrieval according 45
call back interface during the binding operation to
to a priority Set by the client relative to data retrievals provide an indication of the progreSS of the binding
performed by the other naming objects. operation to the client application.
13. The object-oriented framework of claim 1 wherein the 23. The method of claim 21 comprising:
reference is a resource identifier of data residing on a remote calling a data available notification function of the call
computer network, the naming object operating to asynchro 50 back interface to notify the client application at a time
nously retrieve the data for the client from the remote before the binding operation is completed that a
computer network. retrieved part of the stored data is available for the
14. The object-oriented framework of claim 13 in which client application to access.
the naming object obtains information of any preferred 24. The method of claim 21 comprising:
formats for the data from the client, and retrieves the data 55 calling a stop binding notification function of the call back
from the remote computer network in an available one of the interface to notify the client application of a Status of
preferred data formats. the binding operation at ending the binding operation.
15. The object-oriented framework of claim 13 in which 25. The method of claim 20 comprising:
the naming object performs media type negotiation between passing a binding interface by the naming object to the
the client and the remote computer network of a format in 60 client application, the binding interface exposing an
which the naming object retrieves the data. abort function; and
16. The object-oriented framework of claim 13 compris terminating the binding operation upon a call from the
ing: client application to the abort function.
a bind context object for the client to register an interface 26. The method of claim 20 comprising:
provided by the client having a format enumeration 65 passing a binding interface by the naming object to the
function callable from the naming object for the client client application, the binding interface exposing a
to request any preferred formats for the data, the Suspend function and a resume function;
 US 6,401,099 B1
57 58
Suspending the binding operation upon a call from the creating a bind context object for Storing information
client application to the Suspend function; and relating to a binding operation;
resuming the binding operation upon a call from the client registering a call back interface Supported by a client
application to the resume function. application with the bind context object, wherein the
27. The method of claim 20 comprising: call back interface exposes functions Supported by the
passing a binding interface by the naming object to the client application callable from the naming object to
client application, the binding interface exposing a initiate communication with the client application, and
priority Setting function; and wherein the client application comprises plural instruc
establishing a priority of a thread for executing the tions for executing,
binding operation according to a value passed from the 1O creating a moniker object containing a name that refer
client application in a call to the priority Setting func ences Stored data and having a bind function;
tion. initiating a binding operation in the bind function which
28. The method of claim 20 comprising: executes asynchronously of the client application, the
providing an interface of a bind context object to the client client application continuing instruction execution
application, the bind context object operative to register
15 independently of the binding operation; and
a call back interface of the client application, wherein providing notifications to the client application relating to
the call back interface exposes functions Supported by the binding operation's Status with the call back inter
the client application callable from the naming object to face.
initiate communication with the client application; 33. The storage medium of claim 32 wherein the data
receiving the interface of the bind context object in the retrieval method further comprises:
client application's call to the binding function; and returning a bind interface from the moniker object to the
calling functions on the call back interface to provide client application, the bind interface having functions
notifications to the client application relating to the for at least one of aborting, Suspending, resuming, and
binding operation. 25
Setting an execution priority of the binding operation.
29. The method of claim 20 comprising, in the binding 34. The storage medium of claim 32 wherein the step of
operation: providing notifications in the method comprises:
creating a Storage object having an interface which repeatedly providing progreSS notifications during the
exposes a read function for reading data in the Storage binding operation to the client application indicative of
object; which proportion of the binding operation is complete.
35. The storage medium of claim 32 wherein the method
passing the interface of the Storage object to the client comprises:
application; and registering information in the bind context of any media
retrieving the Stored data into the storage object by the types acceptable to the client application for retrieving
background process, whereby the client application has 35 the Stored data; and
access to the Stored data in the Storage object during the retrieving the Stored data in the binding operation in one
binding operation. of Said acceptable media types.
30. The method of claim 29 comprising: 36. In a computer System having at least one computer, a
returning a retrieval pending error notification to the client moniker object comprising:
application when the client application calls the read 40 a name element for Storing a name that identifies data
function to access the Stored data which is not yet Stored in the computer System;
retrieved into the Storage object. an interface Structure through which a client invokes
31. A method of creating a moniker object to retrieve data method elements of the moniker object via Synchro
referenced by a name, the name having a prefix portion nous calls that Suspend instruction execution of the
indicative of a transport protocol followed by a colon 45 client pending return from the Synchronous calls, and
character, the method comprising: a bind method element invoked by the client through such
registering a program identifier indicative of the transport a Synchronous call using the interface Structure, the
protocol in association with a class identifier in a invoked bind method element operating to commence
registry database, the class identifier being associated a retrieval operation to retrieve the data identified by
with a Server application which Supports a class of 50 the name and to return from Said Synchronous call
transport protocol object, objects of Said class being during the retrieval operation, the return from Said
operative to communicate using the transport protocol Synchronous call permitting continued instruction
to retrieve named data and having a name parsing execution of the client independent of the retrieval
function operative to create monikers from names using operation, whereby the continued instruction execution
the transport protocol; 55 of the client occurs asynchronously of the retrieval
parsing the prefix portion up to the colon character from operation.
the name; 37. The moniker object of claim 36 in combination with
Searching the program identifiers in the registry for a a bind context object for the client to register a call back
match to the prefix portion; interface callable from the moniker object, wherein the call
on matching the prefix portion to the program identifier 60 back interface exposes one or more functions Supported by
indicative indicative of the transport protocol, instan the client for the moniker object to invoke in order to initiate
tiating a transport protocol object of Said class and communication with the client.
calling the name parsing function on the name So as to 38. The moniker object of claim 36 in combination with
create the moniker object. an asynchronous Storage object provided by the moniker
32. A Storage medium having instructions therein for 65 object for Storing retrieved data, and for allowing acceSS by
causing a computer to perform a data retrieval method the client to a part of the retrieved data during the retrieval
comprising the Steps of: operation before the retrieval operation is completed.
 US 6,401,099 B1
59 60
39. The moniker object of claim 36 further comprising: 50. The object-oriented framework of claim 49 wherein
a flow control element invoked by the client through such the retrieval object exposes control interface that includes
a Synchronous call using the interface Structure, the one or more functions for controlling the asynchronous
invoked flow control element operating to affect the retrieval of data.
execution of the retrieval operation. 51. the object-oriented framework of claim 49 wherein a
40. The moniker object and bind context object of claim System object encompasses the association data and the
38 wherein the moniker object obtains information of any retrieval object.
preferred data formats from the client, and retrieves the data 52. The object-oreiented framework of claim 49 wherein
from a remote computer in the computer System in an computer Storage persistently Stores the asynchronously
available one of the preferred data formats. retrieved data.
41. The object-oriented framework of claim 1 wherein the 53. The object-oriented framework of claim 49 wherein
data retrieval and the client instruction execution occur
concurrently. an object associated with the name encapsulates the asyn
chronously retrieved data.
42. The object-oriented framework of claim 1 wherein the 54. A method of communicating between a client appli
data retrieval occurs as a background process. 15 cation program and a System object to asynchronously
43. An object-oriented framework for providing asyn retrieve data Stored in a computer System, the method
chronous retrieval of data from a Storage Site for a client comprising:
application program, wherein the client application program initiating by client application program an asynchronous
includes plural instructions for executing, and wherein the retrieval operation of Stored data for a named item,
client application program further includes a name that wherein the asynchronous data retrieval operation
references a named item, the object-oriented framework executeS as a background process, and wherein the
comprising:
asSociation data defining an association of the name to the client application program continues execution inde
named item;
pendently of the asynchronous retrieval operation; and
a System object that exposes a programming interface to 25
providing a control interface to the client application
the client application program, wherein the program program, wherein the control interface includes func
ming interface includes a retrieval function, wherein tions for the client application program to call to
the client application program initiates asynchronous control the asynchronous retrieval operation.
retrieval of data for the named item through the 55. The method of claim 54 further comprising:
retrieval function, and wherein the client application on a call from the client application program to an abort
program continues instruction execution independently function of the control interface, aborting the asynchro
of the asynchronous retrieval of data. nous retrieval operation.
44. The object-oriented framework of claim 43 wherein 56. The method of claim 54 further comprising:
the programming interface returns to the client application on a call from the client application to a Suspend function
program a reference to a control interface, and wherein the 35 of the control interface, Suspending the asynchronous
client application program controls the asynchronous retrieval operation.
retrieval of data through the control interface. 57. The method of claim 54 further comprising:
45. The object-oriented framework of claim 43 wherein persistently Storing asynchronously retrieved data in com
the name reflects a hierarchical name Space. puter Storage.
46. The object-oriented framework of claim 43 wherein 40 58. The method of claim 54 further comprising:
the name indicates a transport protocol, and wherein the encapsulating asynchronously retrieved data within an
initiated asynchronous retrieval of data occurs according to object associated with the named item.
the indicated transport protocol. 59. A method of communicating between a client appli
47. The object-oriented framework of claim 43 wherein cation program and a System object to asynchronously
the System object places the asynchronously retrieved data 45 retrieve data Stored in a computer System, wherein the client
in persistent Storage. application program includes a client object, the method
48. The object-oriented framework of claim 43 wherein comprising:
the System object places the asynchronously retrieved data initiating by a client application program an asynchronous
in an object associated with the name. retrieval operation of Stored data for a named item,
49. An object-oriented framework for providing asyn 50
chronous retrieval of data from a storage Site for client wherein the a Synchronous data retrieval operation
application program, wherein the client application program executeS as a background process, and wherein the
includes plural instructions for executing, and wherein the client application program continues execution inde
client application program furthr includes a name that ref pendently of the asynchronous retrieval operation; and
erences a named item, the object-oriented framework com 55 providing a callback interface to the System object,
prising: wherein the callback interface includes functions for
asSociation data defining an association of the name to the the system object to call to notify the client object of
named item, wherein the name further indicates a events concerning the asynchronous retrieval opera
transport protocol for retrieving data for the named tion.
item; 60 60. The method of claim 59 comprising:
a retrieval object that implements the transport protocol on a call to a completion function of the callback
indicated by the name, wherein the retrieval object interface, notifying the client object of the completion
handles asynchronous retrieval of data for the named of the asynchronous retrieval operation.
item at the transport protocol level, and wherein the 61. The method of claim 59 further comprising:
client application program continues instruction execu 65 on a call to a partial completion function of the callback
tion independently of the asynchronous retrieval of interface, notifying the client object of the partial
data. completion of the asynchronous retrieval operation.
 US 6,401,099 B1
61 62
62. The method of claim 59 further comprising: cation program, wherein the client application program
placing asynchronously retrieved data in persistent com includes plural instructions for executing, and wherein the
puter Storage. client application program further includes a name that
63. The method of claim 59 further comprising: references the named item, the object-oriented framework
placing asynchronously retrieved data in an object asso comprising:
ciated with the named item. a Service object that instantiates one or more System
64. An object-oriented framework for providing asyn objects, wherein the Service object is callable from a
chronous retrieval of data for a named item for a client client applicatino program; and
application program, wherein the client application program a System object that exposes a programming interface to
includes plural instructions for executing, and wherein the the client application program, wherein the Service
client application program further includes a name that object instantiates the System object, wherein the pro
references the named item, the object-oriented framework gramming interface includes a retrieval function,
comprising:
wherein the client application program initiates asyn
a name parsing interface accessible to the client applica 15 chronous retrieval of data for the named item through
tion program and operating to parse a name passed the retrieval function, and wherein the client applica
from the client application program in a request issued tion program continues instruction execution indenpen
by the client application program to the interface, the dently of the asynchronous retrieval of data.
name parsing interface identifying the type of the name 68. The object-oriented framework of claim 67 wherein
and providing a name-type specific object to the client the Service object instantiates a name-type specific System
application program; and object.
the name-type specific System object exposing a program 69. A method for encapsulating asynchronously retrieved
ming interface to the client application program data within an object for a client application program,
wherein the programming interface includes a retrieval wherein the client application program includes plural
function, wherein the client application program ini 25 instructions for executing, the method comprising:
tiates asynchronous retrieval of data for the named item de-referencing a data type to an object type;
through the retrieval function, and wherein the client instantiating an object of the object type;
application program continues instruction execution
independently of the asynchronous retrieval of data. asynchronously retrieving the data, wherein the client
65. The object-oriented framework of claim 64 wherein application program continues instruction execution
the name-type specific System object encapsulates name to independently of the asynchronous retrieval of the data;
named item association data. and
66. The object-oriented framework of claim 64 wherein encapsulating the asynchronously retrieved data within
the name-type specific System object is a moniker object. the instantiated object.
67. An object-oriented framework for providing asyn
chronous data retrieval for a named item for a client appli
 UNITED STATES PATENT AND TRADEMARK OFFICE
CERTIFICATE OF CORRECTION

PATENT NO. : 6,401,099 B1 Page 1 of 1

DATED : June 4, 2002
INVENTOR(S) : Koppolu et al.

It is certified that error appears in the above-identified patent and that said Letters Patent is
hereby corrected as shown below:

Column 57
Line 61, “indicative indicative' Should read -- indicative --.
Column 59
Line 54, "program furthr” should read -- program further --.
Column 60
Line 5, “the object-oriented” should read -- The object-oriented --.
Line 34, "application to' Should read -- application program to --.
Line 60, “comprising:” should read -- further comprising: --.
Column 62
Line 9, “applicatino” should read -- application --.
Lines 17-18, “indenpendently” should read -- independently --.

Signed and Sealed this

Seventh Day of September, 2004

WDJ
JON W. DUDAS
Acting Director of the United States Patent and Trademark Office