Getting and Setting Properties
A version of this page is also available for
4/8/2010
Properties are accessed in the same way as methods, except you specify DISPATCH_PROPERTYGET or DISPATCH_PROPERTYPUT instead of DISPATCH_METHOD.
Some languages cannot distinguish between retrieving a property and calling a method. In this case, set the flags DISPATCH_PROPERTYGET and DISPATCH_METHOD.
The following code example gets the value of a property named On. You can assume that the object has been created, and that its interfaces have been queried, as in the previous example.
VARIANT FAR *pVarResult;
// Code omitted for brevity.
szMember = "On";
hresult = pdisp->GetIDsOfNames(IID_NULL, &szMember, 1,
LOCALE_USER_DEFAULT, &dispid);
hresult = pdisp->Invoke(
dispid,
IID_NULL,
LOCALE_USER_DEFAULT,
DISPATCH_PROPERTYGET,
&dispparamsNoArgs, pVarResult, NULL, NULL);
As in the previous example, the code calls IDispatch::GetIDsOfNames for the DISPID of the On property, and then passes the identifier to IDispatch::Invoke.
Then, Invoke returns the property's value in pVarResult.
In general, the return value does not set VT_BYREF. However, this bit might be set and a pointer returned to the return value, if the lifetime of the return value is the same as that of the object.
To change the property's value, the call looks like the following.
VARIANT FAR *pVarResult;
DISPPARAMS dispparams;
DISPID mydispid = DISP_PROPERTYPUT
// Code omitted for brevity.
szMember = "On";
dispparams.rgvarg[0].vt = VT_BOOL;
dispparams.rgvarg[0].bool = FALSE;
dispparams.rgdispidNamedArgs = &mydispid;
dispparams.cArgs = 1;
dispparams.cNamedArgs = 1;
hresult = pdisp->GetIDsOfNames(IID_NULL, &szMember, 1,
LOCALE_USER_DEFAULT, &dispid);
hresult = pdisp->Invoke(
dispid,
IID_NULL,
LOCALE_USER_DEFAULT,
DISPATCH_PROPERTYPUT,
&dispparams, NULL, NULL, NULL);
The new value for the property (the Boolean value FALSE) is passed as a parameter when the On property's Put function is invoked.
The DISPID for the parameter is DISPID_PROPERTYPUT. This DISPID is defined by Automation to designate the parameter that contains the new value for a property's Put function. The remaining details of the DISPPARAMS structure are described in Passing Parameters.
The DISPATCH_PROPERTYPUT flag in the previous example indicates that a property is being set by value. In Visual Basic, the following statement assigns the Value property (the default) of YourObj to the Prop property.
MyObj.Prop = YourObj
This statement should be flagged as a DISPATCH_PROPERTYPUT. Similarly, statements like the following assign the Value property of one object to the Value property of another object.
Worksheet.Cell(1,1) = Worksheet.Cell(6,6)
MyDoc.Text1 = YourDoc.Text1
These statements result in a PROPERTY_PUT operation on Worksheet.Cell(1,1) and MyDoc.Text1.
Use the DISPATCH_PROPERTYPUTREF flag to indicate a property or data member that should be set by reference.
For example, the following Visual Basic statement assigns the pointer YourObj to the property Prop, and should be flagged as DISPATCH_PROPERTYPUTREF.
Set MyObj.Prop = YourObj
The Set statement causes a reference assignment, rather than a value assignment.
The parameter on the right side is always passed by name, and should not be accessed positionally.
See Also
Reference
DISPPARAMS
IDispatch::GetIDsOfNames
IDispatch::Invoke