OBJREF

An OBJREF is the data type used to represent an actual marshaled object reference. An OBJREF can either be empty or assume one of five variations, depending on the degree to which the object being marshaled uses the hook architecture (IMarshal, and so forth) in the marshaling infrastructure. The OBJREF structure is a union consisting of a switch flag followed by the appropriate data.

OBJREF_STANDARD

Contains one interface of an object marshaled in standard form. The data that follows the switch flag is a STDOBJREF structure (described below).

OBJREF_HANDLER

A marshaling of an object that wants to use handler marshaling. For example, an object wants to be represented in client address spaces by a proxy object that caches state. In this case, the class-specific information is just a standard reference to an interface pointer that the handler (proxy object) will use to communicate with the original object. See the IStdMarshalInfo interface.

Member

Type

Semantic

std	STDOBJREF	A standard object reference used to connect to the source object.
Clsid	CLSID	The CLSID of handler to create in the destination client.

OBJREF_LONGSTD

An interface marshaled on an object in long form. Contains a standard reference, along with a set of protocol sequences and network addresses that can be used to bind to an OXID resolver that is able to resolve the OXID in the STDOBJREF. This is useful when marshaling a proxy to give to another computer (a.k.a. the middleman case). The marshaling computer can specify the saResAddr for the resolver on the server computer so that the unmarshaler does not need to call the marshaler (middleman) back to get this information. Further, the marshaler does not need to keep the OXID in its cache beyond the lifetime of its own references in order to satisfy requests from parties that it just gave the OBJREF to.

Member

Type

Semantic

std	STDOBJREF	A standard object reference used to connect to the source object.
SaResAddr	STRINGARRAY	The resolver address.

OBJREF_LONGHDLR

Contains the same information as the handler case as well as the object resolver address. This form is needed for the same reason OBJREF_LONGSTD is needed.

Member

Type

Semantic

std	STDOBJREF	A standard object reference used to connect to the source object.
Clsid	CLSID	The class ID of the handler.
SaResAddr	STRINGARRAY	The resolver address.

OBJREF_CUSTOM

A marshaling of an object which supports custom marshaling. The Custom format gives an object control over the representation of references to itself. For example, an immutable object might be passed by value, in which case the class-specific information would contain the object's immutable data. See the IMarshal interface.

Member

Type

Semantic

clsid	CLSID	The CLSID of the object to create in the destination client.
size	unsigned long	The size of the marshaled data provided by the source object and passed here in pData.
pData	byte*	The data bytes that should be passed to IMarshal::UnmarshalInterface on a new instance of class clsid in order to initialize it and complete the unmarshal process.

STDOBJREF

An instance of a STDOBJREF represents a COM interface pointer that has been marshaled using the standard COM network protocol. A STDOBJREF in general can only be interpreted in the context of an outstanding ORPC, for it may contain an OXID unknown to the computer on which it is unmarshaled, and it is the only computer which is making [an] outstanding call which is guaranteed to be able to provide the binding information for the OXID.

The members and semantics of the STDOBJREF structure are as follows:

Member

Semantic

flags	Flag values taken from the enumeration SORFFLAGS. These are described below.
Crefs	The number of reference counts on ipid that being transferred in this marshaling.
Ipid	The IPID of the interface being marshaled.
Oid	The OID of the object to which ipid corresponds.
Oxid	The OXID of the server that owns this OID.

The various SORFLAGS values have the following meanings. The SORF_OXRESx bit flags are reserved for the object exporter's use only, and must be ignored by object importers. They need not be passed through when marshaling an interface proxy.

Flag

Value

Meaning

SORF_NOPING	1	This OID does not require pinging. Further, all interfaces on this OID, including this IPID, need not be reference counted. Pinging and reference counting on this object and its interfaces are still permitted, however, though such action is pointless.
SORF_OXRES1	8	Reserved for exporter.
SORF_OXRES2	16	Reserved for exporter.
SORF_OXRES3	32	Reserved for exporter.
SORF_OXRES4	64	Reserved for exporter.

ORPCTHIS

In every Request PDU that is an ORPC, the body (CL case) or the stub data (CO case) which normally contains the marshaled arguments in fact begins with an instance of the ORPCTHIS structure. The marshaled arguments of the COM interface invocation follow the ORPCTHIS; thus, viewed at the DCE RPC perspective, the call has an additional first argument. The ORPCTHIS is padded with zero bytes if necessary to achieve an overall size that is a multiple of eight bytes; thus, the remaining arguments are as a whole eight-byte aligned.

As in regular calls, the causality ID must be propagated. If A calls ComputePi on B, B calls Release on C (which gets converted to RemRelease), and C calls Add on A, A will see the same causality ID that it called B with.

Member

Type

Semantic

version	COMVERSION	The version number of the COM protocol used to make this particular ORPC. The initial value will be 1.1. Each packet contains the sender's major and minor ORPC version numbers. The client's and server's major versions must be equal. Backward-compatible changes in the protocol are indicated by higher minor version numbers. Therefore, a server's minor version must be greater than or equal to the client's. However, if the server's minor version exceeds the client's minor version, it must return the client's minor version and restrict its use of the protocol to the minor version specified by the client. A protocol version mismatch causes the RPC_E_VERSION_MISMATCH ORPC fault to be returned.
flags	unsigned long	Flag values taken from the enumeration ORPCINFOFLAGS. These are elaborated below.
reserved	unsigned long	Must be set to zero.
cid	CID	The causality ID of this ORPC. See comments below.
extensions	ORPC_EXTENT_ARRAY*	The body extensions, if any, passed with this call. Body extensions are GUID-tagged blobs of data which are marshaled as an array of bytes. Extensions are always marshaled with initial eight-byte alignment. Body extensions which are presently defined are described below.

The various ORPCINFOFLAGS have the following meanings.

Flag

Meaning

INFO_NULL	(Not a real flag. Merely a defined constant indicating the absence of any flag values.)
INFO_LOCAL	The destination of this call is on the same computer on which it originates. This value is never to be specified in calls which are not in fact local.
INFO_RESERVED1	If INFO_LOCAL is set, then reserved for local use; otherwise, reserved for future use.
INFO_RESERVED2	If INFO_LOCAL is set, then reserved for local use; otherwise, reserved for future use.
INFO_RESERVED3	If INFO_LOCAL is set, then reserved for local use; otherwise, reserved for future use.
INFO_RESERVED4	If INFO_LOCAL is set, then reserved for local use; otherwise, reserved for future use.

Implementations may use the local and reserved flags to indicate any extra information needed for local calls. Note that if the INFO_LOCAL bit is not set and any of the other bits are set, then the receiver should return a fault.

Comments }3 The cid field contains the causality ID.11. Each time a client makes a call, a new causality ID is generated. If a server makes a call while processing a request from a client, the new call must have the same causality ID. This allows simple servers to avoid working on more then one thing at a time (for example: A calls B calls A again, meanwhile C tries to call A with a new causality ID). It tells the server that he is being called because he asked someone to do something for him. There are several interesting exceptions:

The causality ID for maybe and idempotent calls must be set to CID_NULL. If a server makes a ORPC call while processing such a call, a new causality ID must be generated.
In the face of network failures, the same causality ID may end up in use by two independent processes at the same time. If A calls B calls C calls D and C fails, both B and D can independently, simultaneously make calls to E with the same causality ID.

The extensions field contains extensions to the channel header. Two are currently defined for Microsoft's implementation of this protocol (described below). Other implementations may define their own extensions with their own UUIDs. Implementations should skip over extensions they do not recognize or wish to support. Note that in order to force the ORPCTHIS header to be eight-byte aligned, an even number of extensions must be present and the size of the extension data must be a multiple of eight.

ORPCTHAT

In every Response PDU that is an ORPC, the body (CL case) or the stub data (CO case) which normally contains the marshaled output parameters in fact begins with an instance of the ORPCTHAT structure. The marshaled output parameters of the COM interface invocation follow the ORPCTHAT; thus, viewed at the DCE RPC perspective, the call has additional output parameters. The ORPCTHAT is padded with zero-bytes if necessary to achieve an overall size that is a multiple of eight bytes; thus, the remaining output parameters as a whole [are] eight-byte aligned.

Member

Type

Semantic

flags	unsigned long	Flag values taken from the enumeration ORPCINFOFLAGS. These are elaborated above.
extensions	ORPC_EXTENT_ARRAY*	The body extensions, if any, returned by this call. Body extensions are GUID-tagged blobs of data which are marshaled as an array of bytes. Extensions are always marshaled with initial eight-byte alignment.