ch11 monikers.doc

7/27/2019 CH11 Monikers.doc

1/28

The COM Specification Chapter 11. Monikers

Persistent Intelligent Names: Monikers

Overview

A moniker is simply an object that supports the IMonikerinterface. IMonikerinterface includes the IPersist-

Streaminterface; thus, monikers can be saved to and loaded from streams. The persistent form of a moni-ker contains the class identifier (CLSID) of its implementation which is used durin the loadin process,and so new kinds of monikers can be created transparently to clients.

The most basic operation in IMonikerinterface is that of bindingto the object to which it points,which issupported by IMoniker::BindToObject. This function takes as a parameter the interface identifier by which thecaller wishes to talk to the object, runs whatever alorithm is necessary in order to locate the object, thenreturns a pointer of that interface type to the caller.! "ach moniker class can store arbitrary data its

persistent representation, and can run arbitrary code at bindin time.

#f there is an identifiable piece of persistent storae in which the object referenced by the moniker isstored, then IMoniker::BindToStoragecan be used to ain access to it. $any objects have such identifiablestorae, but some, such as the objects which are the ranes on a $icrosoft "%cel spreadsheet do not.(These ranes e%ist only as a part of "%cel&s data structures; they are in effect a fiment of "%cel&simaination and are only reified on demand for clients.)

#n most cases, a particular moniker class is desined to be one step alon the path to the informationsource in 'uestion. These pieces can be composedtoether to form a moniker which represents the com-plete path. or e%ample, the moniker stored inside a chart that refers to its underlyin data in aspreadsheet miht be a composite moniker formed from three pieces

C:\Q3RPTDOC

!i"eMoniker

S#L$STBL

ItemMoniker

R%C%:R&C'

ItemMonikerMoniker class

User Name

(enericCom)ositeMoniker

Figure 1. Moniker in a chart referring to a spreadsheet from which it extracts data.

This composite is itselfa moniker; it just happens to be a moniker which is a se'uenced collection of othermonikers. The composition here isgenericin that it has no knowlede of the pieces involved otherthanthat they are monikers.

$ost monikers have a te%tual representation which is meaninful to the user; this can be retrieved withIMoniker::(etDis)"a*+ame

. The A*# functionMkParseDis)"a*+ame

oes the other direction it can turn a te%tualdisplay name into the appropriate moniker, thouh beware that in eneral this is operation is as e%pensiveas actually bindin to the object.

$onikers can compare themselves to other monikers usin IMoniker::Is$,a". A hash value useful for storinmonikers in lookup tables is available throuh IMoniker::.as/. $onikers are not a total order or even a

partial order; therefore, monikers cannot be stored in tables that rely on sortin for retrieval; use hashininstead (it is inappropriate to use the display name of a moniker for sortin, since the display name maynot reflect the totality of internal state of the moniker).

The earliest time after which the object to which the moniker points is known not to have chaned can beobtained with IMoniker::(etTimeO0LastC/ange. This is notnecessarily the time of last chane of the object;rather, it is the best cheaply available appro%imation thereto.

A moniker can be asked to re-write itself into another e'uivalent moniker by callin IMoniker::Redce. Thisfunction returns a new moniker that will bind to the same object, but does so in a more efficient way. Thiscapability has several uses

#t enables the construction of user-defined macros or aliases as new kinds of moniker classes.

+hen reduced, the moniker to which the macro evaluates is returned.

#t enables the construction of a kind of moniker which tracks data as it moves about. +hen

reduced, the moniker of the data in its current location is returned.

! This function also takes some parameters that provide conte%tual information to the bindin process which we shall et toin a moment.

DRAFT age! 1 Cop"right # 1$$% Microsoft CorporationAll Rights Reser&ed


2/28

Chapter 11. Monikers The COM Specification

n file systems such as $acintosh ystem which support an #/-based method of accessin

files which is independent of file names, a ile $oniker could be reduced to a monikerwhich contains one of these #/s.

iure 0 shows a (somewhat contrived) e%ample of moniker reduction. #t illustrates the reduction of amoniker which names the net income entry for this year&s report in the 1*rojects2 directory of the currentuser&s home directory.

-ser )ro0i"edate2

3orking director*

.ome

#"iasMoniker

\\ser4er\s/are

+et5o"-meMoniker

0red

!i"eMoniker

Projects C-rrentRe)ort

!i"eMoniker MacroMoniker

+etIncome

ItemMoniker

Projects

!i"eMoniker

#nn-a"

!i"eMoniker

+etIncome

ItemMoniker

67768"s

!i"eMoniker

user name

class

original moniker:

reduced moniker:

o!ects connected to

during reduction:

Figure ". #eduction of a moniker showing the o!ects connected to during reduction.

(3ote that the particular classes of monikers used here are for illustrative purposes only.) As we can see,many monikers in this e%ample are reduced to somethin completely different, and some bind to some-thin durin their reduction, but some do not. or e%ample, to reduce the alias 1.ome2, the reduction mustaccess the information that 1.ome2 was an alias for 1\\ser4er\s/are\0red2.

The process of moniker reduction may also be tied to a lobal table called the R'nning Ob(ect Table. The4unnin bject Table serves as the place where monikers in the process of bindin look to see if they arealready runnin or not.

*ointers to instances of IMonikerinterface can be marshaled to other processes, just as any other interfacepointer can. $any monikers are of the nature that they are immutable once created and that they maintainno object state outside themselves. #tem $onikers are an e%ample of a class of such monikers. Thesemonikers, which can be replicated at will, will usually want to support custom marshalin (see IMars/a"interface) so as to simply seriali5e themselves and de-seriali5e themselves in the destination conte%t (seeIPersistStreamreardin seriali5ation). This is referred to as marshalin an object b" &al'e.

IMoniker interface and $ore Monikers

This section describes the details of IMonikerinterface and related interfaces. #n addition, it discusses thevarious kinds of monikers that are provide as part of every 6$ implementation.

ome moniker errors have associated with them some e%tended information. ee IBindCt8t::RegisterObject-Paramfor more details.

IMoniker interface

+e&ll now look in detail at IMonikerinterface its supportin functions and structures.

inter0ace IMoniker: IPersistStream9.R$SLT BindToObject;)bc2 )mkToLe0t2 iidRes"t2 ))4Res"t


3/28


.R$SLT 'arse)ispla*Name;)bc2 ")s>Dis)"a*+ame2 )cc/$aten2 ))mkOtDe"im2 ")s>Item2 ))mk


4/28


ToObject;


5/28


Arument Type /escription

)bc IBindCt8E the bindin conte%t for this bindin operation.

iid R$!IID the interface by which we wish to bind to this storae. 6ommoninterfaces passed here include #torae, #tream, and #9ock:ytes.

))4Obj 4oidEE n successful return, a pointer to the instantiated storae is placedhere, unless BI+D!L#(SSTT$ST$IST$+C$ was specified in the

bindin options, in which case +LLma"be returned instead.

return value .R$SLT SOA2 MA$+OSTOR#($2 MA$$C$$D$DD$#DLI+$2 MA$CO+-+$CTM#+#LLF2 $+OI+T$R!#C$2 MA$I+T$RM$DI#T$I+T$R-!#C$+OTSPPORT$D2 ST($#CC$SSD$+I$D

IMoniker::#educe

74"89T #$oniker4educe(pbc, dw4educe7owar, ppmkTo9eft, ppmk4educed)

The reduction of monikers was reviewed and illustrated in the synopsis above; this is the function thatactually carries it out. 4eturn a more efficient or e'ually efficient moniker that refers to the same object asdoes this moniker. $any monikers, if not most, will simply reduce to themselves, since they cannot be re-written any further. A moniker which reduces to itself indicates this by returnin itself throuh ))mkRe-dcedand the returnin status code MASR$DC$DTOS$L!. A moniker which reduces to nothin shouldreturn 3899, and should return the status code SOA.

#f the moniker does not reduce to itself, then this function does notreduce this moniker in-place; instead,it returns a nemoniker.

The reduction of a moniker which is a composite of other monikers repeatedly reduces the pieces of whichit is composed until they all reduce to themselves, then returns the composite of the reduced pieces.dRedce.o!arcontrols the stoppin point of the reduction process. #t controls to what e%tent the reduc-tion should be carried out. #t has the followin leal values.

t*)ede0 enm tagMARR$DC$ 9MARR$DC$O+$ 36N2MARR$DC$TOS$R %6N2MARR$DC$T.RO(S$R 66N2MARR$DC$#LL G? M-RR)UC.

These values have the followin semantics.

>alue /escriptionMARR$DC$O+$ *erform only one step of reduction on this moniker. #n eneral, the caller

will have to have specific knowlede as to the particular kind of monikerin 'uestion in order to be able to usefully take advantae of this option.

MARR$DC$TOS$R 4educe this moniker to the first point where it first is of the form where itrepresents somethin that the user conceptuali5es as bein the identity of a

persistent object. or e%ample, a file name would 'ualify, but a macro oran alias would not. #f no such point e%ists, then this option should betreated as MARR$DC$#LL.

MARR$DC$T.RO(S$R 4educe this moniker to the point where any further reduction would reduceit to a form which the user does not conceptuali5e as bein the identity of a

persistent object. ften, this is the same stae as MARR$DC$TOS$R.

MARR$DC$#LL 4educe the entire moniker, then, if needed reduce it aain and aain to the

point where it reduces to simply itself.+hen determinin whether they have reduced themselves as far as re'uested, IMoniker::Redce implemen-tations should not compare for e'uality aainst dRedce.o!ar, as we wish to allow for the possibility thatintermediate levels of reduction will be introduced in the future. #nstead, IMoniker::Redceimplementationsshould reduce themselves at leastas far as is re'uested.

An important concept in the above is the idea of a moniker that the user thinks of as the name of a persist-ent object; a persistent identity. The intent is to provide the ability to prorammatically reduce a monikerto canonical forms whose display names would be reconi5able to the user. *aths in the file system, book-marks in word-processin documents, and rane names in spreadsheets are all e%amples of user-identities.

DRAFT age! % Cop"right # 1$$% Microsoft CorporationAll Rights Reser&ed


6/28


#n contrast, neither a macro nor an alias encapsulated in a moniker, nor an inode-like file #/ moniker aresuch identities.

The bind conte%t parameter is used as in IMoniker::BindToObject. #n particular, implementations of IMon-iker::Redce should pay attention to the time deadline imposed by the caller and the reportin of themoniker of the object that, if it had been runnin, would have allowed the reduction to proress fur ther.ee IBindCt8below.

Arument Type /escription)bc IBindCt8E The bind conte%t to use in this operation.

dRedce.o!ar DORD #ndicates to what deree this moniker should be reduced; see above.

))mkToLe0t IMonikerEE n entry, the moniker which is the prefi% of this one in the compositein which it is found. n e%it, the pointer is either +LLor non-+LL.

3on-+LL indicates that what was previously thouht of as the prefi%should be disrearded and the moniker returned throuh ))mkToLe0tconsidered the prefi% in its place (this is very rare). +LLindicates thatthe prefi% should not be so replaced. Thus, most monikers will +LLout this parameter before returnin.

))mkRedced IMonikerEE n e%it, the reduced form of this moniker. *ossibly +LL.

return value .R$SLT SOA2 MASR$DC$DTOS$L!2 MA$$C$$D$DD$#DLI+$.

IMoniker::$ompose)ith

74"89T #$oniker6ompose+ith(pmk4iht, fnly#f3ot=eneric, ppmk6omposite)

4eturn a new moniker which is a composite formed with this moniker on the left and )mkRig/ton theriht. #t is usin this operation that the pieces of the path to an object are cobbled toether to form theoverall full path.

There are two distinct kinds of composite monikers those that know nothin about their pieces other thanthat they are monikers, and those that know more. +e have been termin the former a genericcomposite;we have seen several e%amples above. An e%ample of the latter miht be that of the result of composin aile $oniker containin a relative path on to the end of another ile $oniker the result could be a newile $oniker containin the complete path. ?There is only a need for one implementation of a =eneric6omposite $oniker, and this has been provided; see Create(enericCom)osite;


7/28


6omposition of monikers is an associative operation. That is, if #, B, and Care monikers, then

;# BDis)"a*+ame LPSTRE on e%it, the current display name for this moniker. +LLif the monikerdoes not have a display name or the deadline was e%ceeded.

return value .R$SLT SOA2 MA$$C$$D$DD$#DLI+$.

MkParse/ispla0Name

74"89T $k*arse/isplay3ame(pbc, lps5/isplay3ame, pcch"aten, ppmk)

4ecall from IMoniker::(etDis)"a*+amethat most monikers have a te%tual name which is meaninful to theuser. The function MkParseDis)"a*+amedoes the loical inverse operation iven a strin, it returns a mon-iker of the object that the strin denotes. This operation is known as parsing. A display name is parsedinto a moniker; it is resolved into its component moniker parts.

#f a synta% error occurs, than an indication of how much of the strin was successfully parsed is returnedin )cc/$atenand +LLis returned throuh ))mk. therwise, the value returned throuh )cc/$atenindicatesthe entire si5e of the display name.


)bc IBindCt8E the bindin conte%t in which to accumulate bound objects.

")s>Dis)"a*+ame LPSTR the display name to be parsed.

)cc/$aten LO+(E on e%it the number of characters of the display name that wassuccessfully parsed. $ost useful on synta% error.

))mk IMonikerE the resultin moniker.

return value .R$SLT SOA2 MA$SF+T#.

*arsin a display name may in some cases be as e%pensive as bindin to the object that it denotes, sincealon the way various non-trivial name space manaers (such as a spreadsheet application that can parseinto ranes in its sheets) need to be connected to by the parsin mechanism to succeed. As miht bee%pected, objects are not released by the parsin operation itself, but are instead handed over to the

passed-in bindin conte%t (via IBindCt8::RegisterObjectBond


14/28


Uc:\0oo\bar\ba>doc\s-mmar*tab"e\c/art V\series 6\)oint &Ulps12serName

c:\0oo\bar\ba>doc Us-mmar*tab"e\c/art V\series 6\)oint &Umoniker3so3far remaining suffix

Figure 4. Intermediate stage in parsing a displa0 name into a moniker.

The ind'cti&e stepasks the moniker-so-far usin IMoniker::ParseDis)"a*+ameto consume as much as it wouldlike of the remainin suffi% and return the correspondin moniker and the new suffi%. The moniker iscomposed onto the end of the e%istin moniker-so-far, and the process repeats.

#mplementations of IMoniker::ParseDis)"a*+amevary in e%actly where the knowlede of how to carry out theparsin is kept. ome monikers by their nature are only used in particular kinds of containers. #t is likelythat these monikers themselves have the knowlede of the leal display name synta% within the objectsthat they themselves denote, and so they can carry out the processes completely within IMoniker::Parse-Dis)"a*+ame. The common case, however, is that the moniker-so-far is eneric in the sense that is notspecific to one kind of container, and thus cannot know the leal synta% for elements within the container.ile monikers are an e%ample of these, as are #tem $onikers. These monikers in eneral employ thefollowin stratey to carry out parsin. irst, the moniker connects to the classof object that it currentlydenotes, askin for IParseDis)"a*+ameinterface. #f that succeeds, then it uses the obtained interface pointerto attempt to carry out the parse. #f the class refuses to handle the parse, then the moniker binds to theob(ect it denotes, askin aain for IParseDis)"a*+ameinterface. #f this fails, then the parse is aborted.

The effect is that ultimately an object always ets to be in control of the synta% of elements containedinside of itself. #t&s just that objects of a certain nature can carry out parsin more efficiently by havin amoniker or their class do the parsin on their behalf.

3otice that since MkParseDis)"a*+ame knows nothin of the leal synta% of display names (with thee%ception of the initial parsin step; see below). #t is of course beneficial to the user that display names indifferent conte%ts not have ratuitously different synta%. +hile there some rare situations which call forspecial purpose synta%, it is recommended that, unless there are compellin reasons to do otherwise, thesynta% for display names should be the same as or similar to the native file system synta%; the aim is to

build on user familiarity. $ost important about this are the characters allowed for the delimiters used toseparate the display name of one of the component monikers from the ne%t. 8nless throuh some specialcircumstances they have &er"ood reason not to, all moniker implementations should use inter-monikerdelimiters from the character set

\ : J

tandardi5ation in delimiters promotes usability. :ut more importantly, notice that the parsin alorithmhas the characteristic that a iven container consumes as much as it can of the strin bein parsed before

passin the remainder on to the desinated object inside themselves. #f the delimiter e%pected of the ne%t-to-be-enerated moniker in fact forms (part of) a valid display name in the container, then the container&s

parse will consume itC

$onikers and objects which have implementations on more than one platform (such as ile $onikers)should always parse accordin to the synta% of the platform on which they are currently runnin. +henasked for their display name, monikers should also show delimiters appropriate to the platform on whichthey are currently runnin, even if they were oriinally created on a different platform. #n total, users willalways deal with delimiters appropriate for the host platform.

The initial stepof the parsin process is a bit tricky, in that it needs to somehow determine the initialmoniker-so-far. MkParseDis)"a*+ameis omniscient with respect to the synta% with which the display nameof a moniker may leally bein, and it uses this omniscience to choose the initial moniker.

The initial moniker is determined by tryin the followin strateies in order, usin the first to succeed.

!. All prefi%es of ")s>Dis)"a*+amethat consist solely of valid file name characters are consultedas file monikers in the 4unnin bject Table.

?. The file system is consulted to check if a prefi% of ")s>Dis)"a*+amematches an e%istin file.aid file name may be drive absolute, drive relative, workin-directory relative, or beinwith an e%plicit network share name. This is a common case.

@. #f the initial character of ")s>Dis)"a*+ameis WXY, then the ma%imal strin immediately follow-in the WXYwhich conforms to the leal ProgIDsynta%Dis determined. This is converted to a

D 9etters, numbers, or periods; must not bein with a number. ee the appendi%.

Cop"right # 1$$% Microsoft Corporation age! 1- DRAFT All Rights Reser&ed


15/28


CLSIDwith CLSID!romProgID. An instance of this class is asked in turn for IParseDis)"a*+ameinterface; the IParseDis)"a*+ame interface so found is then iven the whole strin (startinwith the WXY) to continue parsin.

IMoniker::Parse/ispla0Name

74"89T #$oniker*arse/isplay3ame(pbc, pmkTo9eft, lps5/isplay3ame, pcch"aten, ppmkut)

=iven that the composite moniker ;)mkToLe0t ;t/e recei4erDis)"a*+ameis the as-yet-to-be-parsed tail of the display name. This function is to consume as much ofit as is appropriate for a name within the object identified by ;)mkToLe0t

;t/e recei4er


16/28



)dMks*s DORDE the place at which the result is to be returned. $ay not be +LL.

return value .R$SLT SOA

IParseDisplayName interface

IParse/ispla0Name::Parse/ispla0Name

74"89T #*arse/isplay3ame*arse/isplay3ame(pbc, lps5/isplay3ame, pcch"aten, ppmkut)

This is the sinle function in the IParseDis)"a*+ameinterface

inter0ace I'arse)ispla*Name : Inknon 9.R$SLT 'arse)ispla*Name;)bc2 ")s>Dis)"a*+ame2 )cc/$aten2 ))mkOt


17/28


I%ind$tx::#egisterO!ect%ound

74"89T #:ind6t%4eisterbject:ound(punk)

4emember the passed object as one of the objects that has been bound durin a moniker operation andwhich should be released when it is complete overall. 6allin this function causes the bindin conte%t tocreate an additional reference to the passed-in object with #ddRe0; the caller is still re'uired to Re"easeitsown copy of the pointer independently.

The effect of callin this function twice with the same object is cumulative, in that it will re'uire twoIBindCt8::Re4okeObjectBond calls to completely remove the reistration of the object within the bindinconte%t.


)nk InknonE the object which is bein reistered as needin to be released.

return value .R$SLT SOA.

I%ind$tx::#evokeO!ect%ound

74"89T #:ind6t%4evokebject:ound(punk)

This function undoes the effect of IBindCt8::RegisterObjectBond it removes the object from the set that willbe released when the bind conte%t in IBindCt8::Re"easeBondObjects(actually removes one occurrence of it).This function is likely to be rarely called, but is included for completeness.


)nk #8nknownK the object which no loner needs to be released.

return value 74"89T SOA2 MA$+OTBO+D2 $OTO!M$MORF

I%ind$tx::#elease%oundO!ects

74"89T #:ind6t%4elease:oundbjects()

4eleases all the objects currently reistered with the bind conte%t thouh IBindCt8::RegisterObjectBond.

This function is (conceptually) called by the implementation of IBindCt8::Re"ease.


return value 74"89T SOA

I%ind$tx::(et%indOptions

74"89T #:ind6t%et:indptions(pbindopts)

tore in the bind conte%t a block of parameters that will apply to later IMonikeroperations usin this bindconte%t. 8sin block of parameters like this is just an alternative way to pass parameters to an operation.+e distinuish the parameters we do for conveyance by this means because !) they are common to mostIMonikeroperations, and 0) these parameters do not chane as the operation moves from piece to piece of aeneric composite.


)bindo)ts BI+DOPTSE the block of parameters to set. These can later be retrieved withIBindCt8::(etBindO)tions.

return value .R$SLT SOA2 $OTO!M$MORF

BI+DOPTSis defined as follows

t*)ede0 strct tagBI+DOPTS 9DORD cbStrct= t/e si>e in b*tes o0 t/is strctre ie: si>eo0;BI+DOPTS


18/28


$ember /escription

gr0!"ags

A roup of :oolean flas. 9eal values that may be OR&d toether are the taken from theenumeration BI+D!L#(S; see below. $oniker implementations must inore any set-bits in thisfield that they do not understand.

gr0Mode

A roup of flas that indicates the intended use that the caller has towards the object that heultimately receives from the associated moniker bindin operation. 6onstants for this member aretaken from the ST(Menumeration.

+hen applied to the IMoniker::BindToObjectoperation, by far the most sinificant fla values areST(MR$#D,ST(MRIT$, and ST(MR$#DRIT$. #t is possible that some bindin operationsmiht make use of the other flas, particularly ST(MD$L$T$O+R$L$#S$or ST(MCR$#T$, butsuch cases are 'uite esoteric.

+hen applied to the IMoniker::BindToStorageoperation, mostST(Mvalues are potentially usefulhere.

The default value for gr0Modeis ST(MR$#DRIT$ ST(MS.#R$$CLSI5$.

dTickContDead"ine

This is an indication of when the caller would like the operation to complete. 7avin thisparameter allows the caller to appro%imately and heuristically bound the e%ecution time of an

operation when it is more important that the operation perform 'uickly than it is that it performaccurately. $ost often, this capability is used with IMoniker::(etTimeO0LastC/ange, as was previouslydescribed, thouh it can be usefully applied to other operations as well.

This ?0-bit unsined value is a time in milliseconds on the local clock maintained by the (etTick-Contfunction. A value of 5ero indicates 1no deadline;2 callers should therefore be careful not to

pass to the bind conte%t a value of 5ero that was coincidentally obtained from (etTickCont. 6lockwrappin is also a problem. Thus, if the value in this variable is less than the current time bymore than 0?!milliseconds, then it should be interpreted as indicatin a time in the future of itsindicated value plus 0?0milliseconds.

Typical deadlines will allow for a few hundred milliseconds of e%ecution. "ach function shouldtry to complete its operation by this time on the clock, or fail with the error MA$$C$$D$D-D$#DLI+$if it cannot do so in the time allotted. unctions are not re+'ired to be absolutelyaccurate in this reard, since it is almost impossible to predict how e%ecution miht take (thus,callers cannot rely on the operation completin by the deadline), but operations which e%ceeded

their deadline e%cessively will usually cause intolerable user delays in the operation of theircallers. Thus, in practice, the use of deadlines is a heuristic which callers can impose on thee%ecution of moniker operations.

#f a moniker operation e%ceeds its deadline because a iven object or objects that it uses are notrunnin, and if one of these had been runnin, then the operation would have completed more ofits e%ecution, then the monikers of these objects should be recorded in the bind conte%t usinIBindCt8::RegisterObjectParamunder the parameter names 1$8ceededDead"ine2, 1$8ceededDead"ine62,1$8ceededDead"ine%2, etc.; use the first name in this series that is currently unused. This approachives the caller some knowlede as to when to try the operation aain

The enumeration BI+D!L#(S, which contains the leal values for the bit-field BI+DOPTS::gr0!"ags, isdefined as follows

t*)ede0 enm tagBI+D!L#(S 9BI+D!L#(SM#FBOT.$RS$R 62

BI+D!L#(SSTT$ST$IST$+C$ %2? BIN)+%,#S=

These flas have the followin interpretation.

Cop"right # 1$$% Microsoft Corporation age! 12 DRAFT All Rights Reser&ed


19/28


>alue /escription

BI+D!L#(SM#FBOT.$RS$R

#f not present, then the operation to which the bind conte%t containin this parameter isapplied should not interact with the user in any way, such to ask for a password for anetwork volume that needs mountin. #f present, then this sort of interaction is permitted. #f

prohibited from interactin with the user when it otherwise would like to, an operation mayelect to use a different alorithm that does not re'uire user interaction, or it may fail with theerror MAMSTBOT.$RS$R.

BI+D!L#(SSTT$ST$IST$+C$

#f present, indicates that the caller of the moniker operation to which this fla is beinapplied is not actually interested in havin the operation carried out, but only in learnin ofthe operation could have been carried out had this fla not been specified. or e%ample, thisfla ive the caller the ability to e%press that he is only interested in findin out whether anobject actually e%ists by usin this fla in a IMoniker::BindToObjectcall. $oniker imple-mentations are free, however, to inore this possible optimi5ation and carry out the operationin full. 6allers, therefore, need to be able to deal with both cases. ee the individual routinedescriptions for details of e%actly what status is returned.

I%ind$tx::-et%indOptions

74"89T #:ind6t%=et:indptions(pbindopts)

4eturn the current bindin options stored in this bind conte%t. ee IBindCt8::SetBindO)tsfor a description ofthe semantics of each option.

3otice that the caller provides a BI+DOPTSstructure, which is filled in by this routine. #t is the caller&sresponsibility to fill in the cbStrctmember correctly.


pbindpts BI+DOPTSE the structure of bindin options which is to be filled in.

return value .R$SLT SOA2 $+$P$CT$D

I%ind$tx::-et#unningO!ect&ale

74"89T #:ind6t%=et4unninbjectTable(pprot)

4eturn access to the 4unnin bject Table relevant to this bindin process. $oniker implementations

should et access to the 4unnin bject Table usin this function rather than the lobal A*# (etRnning-ObjectTab"e. The appropriate 4unnin bject Table is determined implicitly at the time the bind conte%t iscreated.


))rot IRnningObjectTab"eEE the place to return the runnin object table.

return value .R$SLT SOA2 $OTO!M$MORF2 $+$P$CT$D

I%ind$tx::#egisterO!ectParam

74"89T #:ind6t%4eisterbject*aram(lps5Bey, punk)

4eister the iven object pointer under the name ")s>Ae*in the internally-maintained table of object poin-ters. The intent of this table is that it be used as an e%tensible means by which conte%tual information can

be passed to the bindin process. trin keys are compared case-sensitive.

9ike IBindCt8::RegisterObjectBond, this function creates an additional reference to the passed-in object usin#ddRe0. The effect of callin this function a second time with the same ")s>Ae* is to replace in the table theobject passed-in the first time.

:y convention, moniker implementers may freely use object parameters whose names bein with thestrin representation of the class id of the moniker implementation in 'uestion.

This facility is also used as means by which various errors can convey information back to the caller.Associated with certain error values are the followin object parameters

DRAFT age! 1$ Cop"right # 1$$% Microsoft CorporationAll Rights Reser&ed


20/28


"rror *arameters

MA$$C$$D$DD$#DLI+$ *arameters named 1$8ceededDead"ine2, 1$8ceededDead"ine62,1$8ceededDead"ine%2, etc., if they e%ist, are monikers who appearance asrunnin would make it reasonable for the caller to attempt the bindinoperation aain.

$CL#SS+OT!O+D The parameter named 1C"ass+ot!ond2, if present, is a moniker to the storae

of the object whose class was not able to be loaded in the process of amoniker operation.

3ew moniker authors can freely use parameter names that bein with the strin form of the CLSIDof theirmoniker; see String!romCLSID().

The aruments to this function are as follows


")s>Ae* LPSTR the name under which the object is bein reistered.

)nk InknonE the object bein reistered.

return value .R$SLT SOA2$OTO!M$MORF

I%ind$tx::-etO!ectParam

74"89T #:ind6t%=etbject*aram(lps5Bey, ppunk)9ookup the iven key in the internally-maintained table of conte%tual object parameters and return thecorrespondin object, if one e%ists.


")s>Ae* LPSTR the key under which to look for an object.

))nk InknonEE The place to return the object interface pointer. +LLis returned onfailure (alon with S!#LS$).

return value .R$SLT SOA2 S!#LS$

I%ind$tx::*numO!ectParam

74"89T #:ind6t%"numbject*aram(ppenum)

"numerate the strins which are the keys of the internally-maintained table of conte%tual object

parameters.


))enm I$nmStringEE the place to return the strin enumerator. ee 6hapter @ for adescription of I$nmString.


I%ind$tx::#evokeO!ectParam

74"89T #:ind6t%4evokebject*aram(lps5Bey)

4evoke the reistration of the object currently found under this key in the internally-maintained table ofconte%tual object parameters, if any such key is currently reistered.


")s>Ae* LPSTR the key whose reistration is to be revoked.return value .R$SLT SOA2 S!#LS$

$reate%ind$tx

74"89T 6reate:ind6t%(reserved, ppbc)

Allocate and initiali5e a new IBindCt8usin a system-supplied implementation.

Cop"right # 1$$% Microsoft Corporation age! )7 DRAFT All Rights Reser&ed


21/28



reser4ed DORD reserved for future use; must be 5ero.

))bc IBindCt8E the place in which to put the new BindCt8.


Generic Composite Moniker class4ecall that in eneral monikers are a composite list made up of other pieces. All monikers which are aeneric composite of other monikers are instances of =eneric 6omposite $oniker class whose implemen-tation is provide with 6$; there is no need for two =eneric 6omposite $oniker classes.

The implementations of =eneric 6omposite IMoniker::Redceand =eneric 6omposite IMoniker::BindToObjectare particularly important as they manae the interactions between the various elements of the composite,and as a conse'uence define the semantics of bindin to the moniker as a whole.

=eneric composite monikers of si5e 5ero or of si5e one are never e%posed outside of internal =eneric6omposite $oniker method implementations. rom a client perspective, a =eneric 6omposite $onikeralways contains at least two elements.

$reate-eneric$omposite

74"89T 6reate=eneric6omposite(pmkirst, pmk4est, ppmk6omposite)

Allocate and return a new composite moniker. )mk!irst and )mkRest are its first and trailin elementsrespectively. "ither of )mk!irst and )mkRestmay be a eneric composite, or another kind of moniker.=eneric composites et flattened into their component pieces before bein put into the new composite.This function will be called by implementations of IMoniker::Com)oseit/when they wish to carry out aeneric compose operation.


)mk!irst IMonikerE the first element(s) in the new composite. $ay not be +LL.

)mkRest IMonikerE the trailin element(s) in the new composite. $ay not be +LL.

))mkCom)osite IMonikerE throuh here is returned the new composite.

return value 74"89T SOA2 $OTO!M$MORF

-eneric $omposite Moniker5IMoniker::#educe4eduction of a eneric composite conceptually reduces each of its pieces in a left-to-riht fashion and

builds up a composite of the result. #f any of the pieces of the composite did not reduce to themselves (andthus, the eneric composite overall did not reduce to itself), then this process is repeated.

An optimi5ed implementation of this function miht use a more complicated but e'uivalent alorithm thatavoids unnecessarily re-reducin monikers that the composite already knows reduce to themselves.

-eneric $omposite Moniker5IMoniker::%ind&oO!ect

:indin to a eneric composite works in a riht-to-left manner. 6onceptually, the eneric compositemerely forwards the bind re'uest onto its last piece, alon the way informin that piece of the moniker toits left in the composite. The last piece, if it needs to, recursively binds to the object to its left. #n practice,

bindin to a eneric composite itself has to handle the recursive call on the left-hand object, as was de -scribed in IMoniker::BindToObject.

File Moniker class

A ile $oniker can be thouht of as a wrapper for a path name in the native file system. #t&s implementa -tion of IMoniker::(etDis)"a*+ame, for e%ample, is trivial it just returns the path. +hen bound to, it de-termines the class of the file (usin the A*# (etC"ass!i"eon +in?0), makes sure that the appropriate classserver is runnin, then asks it to open the file.

DRAFT age! )1 Cop"right # 1$$% Microsoft CorporationAll Rights Reser&ed


22/28


$reateFileMoniker

74"89T 6reateile$oniker(lps5*ath3ame, ppmk)

6reates a moniker from the iven path name. This path may be an absolute path or a relative path. #n thelatter case, the resultin moniker will need to be composed onto another ile $oniker before it can be

bound. #n either case, it will often be the case that other monikers are composed onto the end of thismoniker in order to access sub-pieces of the document stored in the file.


")s>Pat/+ame LPSTR the path name of the desired file.

))mk IMonikerE the newly created moniker.

return value .R$SLT SOA2 MA$SF+T#2 $OTO!M$MORF

File Moniker5IMoniker::%ind&oO!ect

The class of an object desinated by a ile $oniker is determined in a platform-specific way. 7avinfound the correct class, ile $oniker IMoniker::BindToObjectwill instantiate it usin the interface IPersist-!i"e::Load method.

File Moniker5IMoniker::%ind&o(torage

The +in?0 implementation of ile $oniker supports BindToStorage;2 IIDIStorage2


23/28


The followin is the IO"eItemContainerinterface used by #tem $onikers

inter0ace IOleItemContainer: IO"eContainer 94irta" .R$SLT #etObject;")s>Item2 dS)eed+eeded2 )bc2 riid2 ))4ObjectItem2 )bc2 riid2 ))4StorageItem


24/28



")s>Item LPSTR the item in this container that should be bound to.

dS)eed+eeded DORD a value from the enumeration BI+DSP$$D. ee above.

)bc IBindCt8E the actual deadline parameter involved in this bindin operation. orthe use of more sophisticated containers. $ost can inore this, andinstead use dS)eed+eeded.

riid R$!IID the interface with which a connection to that object should be made.

))4Object 4oidEE the bound-to object is returned here.

return value .R$SLT SOA2 MA$$C$$$D$DD$#DLI+$2 MA$+OOB$CT2 $+OI+T$R!#C$2$OTO!M$MORF

Item Moniker5IMoniker::%ind&o(torage

or storae bindin, #tem $onikers merely re'uire IO"eItemContainerinterface of the object to their left. Theimplementation of #tem $oniker IMoniker::BindToStoragebinds to the object to its left usin IO"eItemContainerinterface, then invokes IO"eItemContainer::(etObjectStoragewith the internally stored item name.

IOleItem$ontainer::-etO!ect(torage

74"89T #le#tem6ontainer=etbjecttorae(lps5#tem, pbc, riid, ppvtorae)

#f ")s>Itemdesinates an item in this container that has an independently identifiable piece of storae (suchas does an embedded object), then return access to that storae usin the indicated interface.

)bcis the bind conte%t as received by the #tem $oniker IMoniker::BindToStoragecall. $ost container imple-mentations can simply inore this value; it is passed for the benefit for more sophisticated containers.


")s>Item LPSTR the item access to whose storae is bein re'uested.

)bc IBindCt8E as in IO"eItemContainer::(etObject. 6an be inored by most containers.

riid R$!IID the interface by which the caller wishes to access that storae. ftenIIDIStorageor IIDIStreamare used.

))4Storage 4oidEE the place to return the access to the storae

return value .R$SLT SOA2 MA$$C$$D$DD$#DLI+$2 MA$+OOB$CT2 $OTO!M$MORF2

$+OI+T$R!#C$2 MA$+OSTOR#($

IOleItem$ontainer::Is#unning

74"89T #le#tem6ontainer#s4unnin(lps5#tem)

Answer whether the iven item in this item container is in fact runnin or not. ee IMoniker::IsRnningfor asketch of how this function is used in #tem $onikers.


")s>Item LPSTR the item access to whose runnin status is bein re'uested.

return value .R$SLT SOA2 S!#LS$2 MA$+OOB$CT

Item Moniker5IMoniker::Parse/ispla0Name

#tem $onikerIMoniker::ParseDis)"a*+ame

usesIParseDis)"a*+ame

in the same way as a ile $oniker does.3ote that it re'uests this interface from a different ob(ect than the one that supplies the IO"eItemContainerinterface used in IMoniker::BindToObject, etc. it asks for IO"eItemContainerof the object desinated by themoniker to its left, whereas it asks for IParseDis)"a*+ameof the object that it (the #tem $oniker) desinates.

Anti Moniker class

An Anti $oniker is a moniker that when composed onto the end of a eneric composite moniker removesthe last piece. 6omposin an Anti $oniker onto the end of another kind of moniker should, enerally,annihilate the whole other moniker.

Cop"right # 1$$% Microsoft Corporation age! )- DRAFT All Rights Reser&ed


25/28


:ein composed onto the end of another moniker is pretty much the only interestin thin one can do toan anti-moniker they cannot be bound, their display name is useless, etc. They e%ist to support implemen-tations of IMoniker::In4erse; see that function for usae scenarios.

$oniker implementations that use Anti $onikers as inverses should check for Anti $onikers on the rihtin their implementations of IMoniker::Com)oseit/and collapse down to nothin if so.

$reate6ntiMoniker74"89T 6reateAnti$oniker(ppmk)

6reate and return a new anti-moniker.


))mk IMonikerEE the place to return the new anti-moniker


Pointer Moniker class

A pointer moniker is a kind of moniker that wraps an e%istin object pointer in a moniker so that it mayparticipate as a piece in the moniker bindin process. Think of pointers as a referencin mechanism intothe 1active space2 a process&s memory. $ost moniker implementations are by contrast references into1passive space2 the representation of an object on disk. *ointer monikers provide a means by which a a

iven use of a moniker can transparently reference eitheractive orpassive space.

Implementations of functions in IMoniker interface for Pointer Monikers work roughly as follows.IMoniker::BindToObject turns into a Qer*Inter0ace on the pointer; IMoniker::BindToStorage returnsMA$+OSTOR#($; IMoniker::Redce() reduces the moniker to itself; IMoniker::Com)oseit/ always does ageneric composition; IMoniker::$nm returns +LL; IMoniker::IsS*stemMoniker returns MASFSPTR;IMoniker::Is$,a"() uses the identity test paradigm on pointers after first checking that the other moniker forthe right class; IMoniker::.as/returns a constant; IMoniker::(etTimeO0LastC/ange returns MA$+#5#IL#BL$;IMoniker::In4erse returns an anti-moniker; IMoniker::Re"ati4ePat/To returns the other moniker;IMoniker::(etDis)"a*+ame returns +LL; and IMoniker::ParseDis)"a*+ame() binds to the punk pointer usingIParseDis)"a*+ameinterface and works from there.

Instances of this kind of moniker refuse to be serialized; that is, IPersistStream::Sa4ewill return an error.These monikers can, however, be marshaled to a different process; internally, this marshals and

unmarshals the pointer using the standard paradigm for marshaling interface pointers: CoMars/a"Inter0ace

and Conmars/a"Inter0ace.

CreatePointerMoniker

74"89T 6reate*ointer$oniker(punk, ppmk)

Wrap a pointer in a Pointer Moniker so that it can be presented to interfaces that require monikers forgenerality, but specific uses of which can usefully deal with a moniker which cannot be saved to backing

store.

Argument Type Description

)nk InknonE the pointer that we are wrapping up in a moniker.

))mk IMonikerEE the returned Pointer Moniker.


!nnin" O#$ect Ta#le

#n eneral when bindin to an object we want to open it if it is currently passive, but if not, then we wantto connect to the runnin instance. To take an e%ample from 6ompound /ocuments, a link to a 9otus !0?for +indows spreadsheet, for e%ample, when first bound to should open the spreadsheet, but a second

bind should connect to the already-open copy. The key technical piece that supports this type offunctionality is the 4unnin bject Table.

The 4unnin bject Table is a lobally accessible table on each workstation. #t keeps track of the objectsthat are currently runnin on that workstation so that if an attempt is made to bind to one a connection to

DRAFT age! )% Cop"right # 1$$% Microsoft CorporationAll Rights Reser&ed


26/28


the currently runnin instance can be made instead of loadin the object a second time. The tableconceptually is a series of tuples, each of the form

()mkObject+ame, )4Object)

The first element is the moniker that if bound should connect to the runnin object. The second element isthe object that is publici5ed as bein available, the object that is runnin. #n the process of bindin, mon -ikers bein bound with nothin to their left consult the )mkObject+ameentries in the 4unnin bject Table

to see if the object that they (the moniker bein bound) indicate is already runnin.Access to the 4unnin bject Table is obtained with the function (etRnningObjectTab"e. This returns anobject with the interface IRnningObjectTab"e (note as described earlier, however, that moniker imple-mentations should not use this A*#, but should instead access the 4unnin bject Table from the bindconte%t they are passed).

inter0ace IRunningObjectTable: Inknon 9.R$SLT Register;reser4ed2 )nkObject2 )mkObject+ame2 )dRegister


27/28



reser4ed DORD reserved for future use; must be 5ero.

)nkObject InknonE the object which has just entered the runnin state.

)mkObject+ame IMonikerE the moniker which would bind to the newly runnin object.

)dRegister DORDE a place to return a value by which this reistration can later be revoked.$ay not be +LL. Lero will never be returned as a valid reistrationvalue; that is, on e%it, E)dRegisteris never +LL.

return value .R$SLT SOA2 MASMO+IA$R#LR$#DFR$(IST$R$D

I#unningO!ect&ale::#evoke

74"89T #4unninbjectTable4evoke(dw4eister)

8ndo the reistration done in IRnningObjectTab"e::Register, presumably because the object is about to ceaseto be runnin. 4evokin an object that is not reistered as runnin returns the status code $I+5#LID#R(.+henever any of the conditions that cause an object to reister itself as runnin cease to be true, the objectshould revoke its reistration(s). #n particular, objects should be sure to e%tant reistrations of themselvesfrom the 4unnin bject Table as part of their release process.


dRegister DORDa value previously returned from

IRnningObjectTab"e

Register.

return value .R$SLT SOA2 $I+5#LID#R(

I#unningO!ect&ale::Is#unning

74"89T #4unninbjectTable#s4unnin(pmkbject3ame)

This function should, in eneral, only be called by implementations of IMoniker::IsRnning; clients of moni-kers should invoke this on their monikers, rather than askin the 4unnin bject Table directly.

#n'uire by lookin up in this 4unnin bject Table as to whether an object with this moniker is cur rentlyreistered as runnin. uccess or failure is indicated usin the return codes SOA or S!#LS$. The4unnin bject Table compares monikers by sendin IMoniker::Is$,a"to the monikers already in the tablewith moniker on the riht as an arument.

Arument Type /escription)mkObject+ame IMonikerE the moniker that we want to see is runnin

return value .R$SLT SOA2 S!#LS$

I#unningO!ect&ale::-etO!ect

74"89T #4unninbjectTable=etbject(pmkbject3ame, ppunkbject)

#f the object desinated by )mkObject name is reistered as actually runnin, then return the object soreistered. The 4..T. compares monikers by sendin IMoniker::Is$,a"to the monikers already in the tablewith moniker on the riht as an arument.

This is the function moniker implementations should use to test if they are already runnin (and et thepointer to the object if so).

DRAFT age! )0 Cop"right # 1$$% Microsoft CorporationAll Rights Reser&ed


28/28



)mkObject+ame IMonikerE the moniker in whom interest is bein e%pressed.

))nkObject InknonEE the place to return the pointer to the object. A returned value of 3899indicates that the object is not reistered.

return value .R$SLT SOA2 MA$+#5#IL#BL$

I#unningO!ect&ale::Note$hange&ime

74"89T #4unninbjectTable3ote6haneTime(dw4eister, pfiletime)

$ake a note of the time that a particular object has chaned in order that IMoniker::(etTimeO0LastC/angecanreport an appropriate chane time. This time so reistered is retrievable with IRnningObject-Tab"e::(etTimeO0LastC/ange. bjects should call this as part of their data chane notification process.


dRegister DORD the token previously returned from IRnningObjectTab"e::Register. Themoniker whose chane time is noted is the one specified in)mkObject+amein that call.

)0i"etime !IL$TIM$E on entry, the time at which the object has chaned.

return value .R$SLT SOA2 $I+5#LID#R(

I#unningO!ect&ale::-et&imeOfast$hange

74"89T #4unninbjectTable=etTimef9ast6hane(pmkbject3ame, pfiletime)

As with IMoniker::IsRnning, this function should, in eneral, only be called by implementations ofIMoniker::(etTimeO0LastC/ange; clients of monikers should invoke this on their monikers, rather than askinthe 4unnin bject Table directly.

9ook up this moniker in the runnin object table and report the time of chane recorded for it if same ispresent. The 4unnin bject Table compares monikers by sendin IMoniker::Is$,a"to the monikers alreadyin the table with moniker on the riht as an arument. #mplementations of IMoniker::(etTimeO0LastC/ange,when invoked with )mkToLe0t +LL, will want to call this function as the first thin they do.


)mkObject+ame IMonikerE the moniker in which we are interested in the time of chane.)0i"etime !IL$TIM$E on e%it, the place at which the time of chane is returned.

return value .R$SLT SOA2 MA$+#5#IL#BL$

I#unningO!ect&ale::*num#unning

74"89T #4unninbjectTable"num4unnin(ppenum$oniker)

"numerates the objects currently reistered as runnin. The returned enumerator is of type I$nmMoniker,which enumerates monikers.

t*)ede0 $nmIMonikerE@ InumMoniker=

The monikers which have been passed to IRnningObjectTab"e::Register() are enumerated.


))enmMoniker I$nmMonikerEE the place at which to return the enumerator.return value .R$SLT SOA2 $OTO!M$MORF

ch11 monikers.doc

Documents