ATL Development   «Prev  Next»
Lesson 11 Adding a read-write property
Objective Add the CurRec property to IReadPhBook.

Adding read-write Property

Our next step is to add property CurRec to IReadPhBook. Property CurRec sets an index within COM object PhBookObj that acts as a current record pointer. Recall from our previous discussions that COM clients access COM objects via a COM interface pointer.
The interface pointer is a pointer to a vtable pointer. The only entries in a vtable are pointers to interface methods, for example COM clients cannot directly access data within a COM object. To allow data access, we use properties. A property is an attribute of a COM object. Within the COM object, a property may directly correlate to a variable or a calculated value. Properties are accessed via "get" and "put" methods. A read-only property does not have a put method.
Lets add get and set methods for property CurRec to IReadPhBook:

Adding read-write property using COM

Here are the Steps required to add a read-write property:
  1. In the project Workspace window with the Class View tab selected, right-click on IReadPhBook.
  2. On the context-sensitive menu, click Add Property... This will bring up the Add Property to Interface dialog.
  3. The first step in adding a property is to set the property type. Open the drop-down menu for Property Type.
  4. Select long as the property type. Normally, the implementation would be visible in the window at the bottom of the dialog.
  5. With the property type set, type CurRec as Property Name. Normally, you would see the implementation as you type in the property name. When you've done this, click OK to finish adding the property.
  6. The Add Property dialog closes. We've expanded the interface IReadPhBook so you can see the property we've added. The project workspace ClassView pane should appear.

Notice that two CurRec methods were added: CurRec(Long newVal) and CurRec(long * pVal). These are the put and get methods respectively.
IReadPhBook, within PhBook.idl, now appears as:
 helpstring("IReadPhBook Interface"),
interface IReadPhBook : IUnknown
      [propget, helpstring("property CurRec")]
      HRESULT CurRec([out, retval] long *pVal);
      [propput, helpstring("property CurRec")]
      HRESULT CurRec([in] long newVal);

Notice the propget and propput attributes assigned to each method. These impose a naming convention on each. For example, the get method is named get_CurRec, the put method is named put_CurRec.
High-level development environments such as Visual Basic use the helpstring attribute to display information about the method. High-level development environments also use the retval attribute, assigned to pVal in get_CurRec. The retval attribute is translated into a return value from the method within the high-level development language. Visual C++ also created stub code for these methods within our COM object implementation class CPhBookObj.
Stub object created
Stub object created

CPhBookObj now has method declarations for get_CurRec and put_CurRec in PhBookObj.h.

Adding a read-write property


class CPhBookObj : 
  public IReadPhBook,
  public IManagePhBook,
  public CComObjectRoot,
  public CComCoClass < CPhBookObj,&CLSID_PhBookObj>
  CPhBookObj() {}

Microsoft Visual C++ Windows Applications


    [out, retval]*/ long *pVal);
    [in]*/ long newVal);

Implementation file PhBookObj.cpp has stub methods for get_CurRec and put_CurRec.

Adding a read-write property | PhBookObj.cpp

// PhBookObj.cpp : Implementation of
// CPhBookApp and DLL registration.

#include "stdafx.h"
#include "PhBook.h"
#include "PhBookObj.h"

STDMETHODIMP CPhBookObj::get_CurRec(long *pVal)
  // TODO: Add your implementation code here

    return S_OK;

STDMETHODIMP CPhBookObj::put_CurRec(long newVal)
  // TODO: Add your implementation code here

    return S_OK;

Add Read Write Property - Exercise

Click the Exercise link below to apply what you have learned about adding read-write properties to a COM object.
Add Read Write Property - Exercise