|
This month, Matthew focuses on mapping his recls library to COM.
May 01, 2004
URL:http://www.drdobbs.com/mapping-recls-to-com-collections/184401803
In previous columns, I introduced you to recls — a platform-independent library that provides recursive filesystem searching — and demonstrated techniques for integrating C/C++ libraries with C++ ("normal" classes, and STL sequences), C#, D, and Java by implementing recls mappings for those languages. The source for all the versions of the libraries and the mappings are available from http://www.cuj.com/code/ and http://recls.org/downloads.html. This month, I focus on mapping the library to COM.
There are four changes to recls for this round:
This month's developments correspond to Version 1.3(.1) or later of recls. It requires either STLSoft 1.7.1 or later (http://stlsoft.org/). (It actually relies on v1.7.1 Beta 4.)
In the STL world, the Container concept describes the things that hold collections of a given type, and the Iterator concept describes the mechanisms by which we access the elements within a collection. In the COM world, the containers are known as COM Collections, or just Collections, and the iterators are known as COM Enumerators, or just Enumerators.
A COM Enumerator implements a COM enumeration interface, which provides four methods:
interface IEnumTHING
{
HRESULT Next( unsigned long n
, THING *pElements
, unsigned long *pFetched);
HRESULT Skip(unsigned long n);
HRESULT Reset();
HRESULT Close(IEnumTHING **ppEnThing);
};
For our fictional THING type, IEnumTHING provides access to a number of THING instances via the Next() method. You specify the number of elements you require, n, along with a pointer to an array of elements, pElements, of at least length n, that receives the elements. You also specify a pointer to an integer, pFetched, which receives the number of elements retrieved. In this way, the return of fewer than the requested number is facilitated.
The Skip() method moves the enumeration point on by the given number of elements. Reset() sets the enumeration point back to the start. Clone() provides a new enumerator to the same collection of elements, whose initial enumeration point is the same as the enumerator on which it is called.
The COM Collection model requires an object to support some or all of the following methods/properties: Count, Item, _NewEnum, Add, Remove, and Clear. The first three are used to elicit information from the collection; the latter three effect changes on the collection. Since the recls mappings provide read-only information about the filesystem contents, we are not concerned with Add, Remove, and Clear.
The Count property returns the number of elements in the collection. The Item property is an indexed property by which one can retrieve an element by index and/or by name. The _NewEnum property provides access to the COM Enumerator for the collection; it's like begin() and end() rolled into one.
I used ATL for the implementation of the COM objects. Although it has some flaws, ATL is an easy framework with which to create most kinds of COM implementations, and is suitable for in-process servers (implemented in a dynamic library), which is what we're using here.
The COM objects in the recls COM mapping are lightweight wrappers over the recls API and its internal implementation, which are pretty lightweight themselves.
I won't go into detail about COM's threading models here; that's way too much information to fit into this column. If you want to learn about that, check the MSDN documentation, or ATL Internals, by Brent Rector and Chris Sells (Addison-Wesley, 1999) or Essential COM, by Don Box (Addison-Wesley, 1997). Thankfully, the recls library makes our choices very simple.
The FileSearch class has no state, and its Search() method effectively acts as a static method. The FileEntry class maintains a single recls entry handle of type recls_info_t and has no other member variables. recls does not change the data associated with an entry handle once it is created. Furthermore, retrieving information from entries, and even closing entry handles, is guaranteed threadsafe by recls. Therefore, there are no problems with different threads making simultaneous calls on the same FileEntry instance, and the mechanics of COM reference counting handles the final release of the entry handle back to recls. There's no need to manage multithreaded access to member state, so both these COM classes follow the "Both" model — which means that they support both free threading and apartment models — and they use the CComMultiThreadModelNoCS ATL threading policy class in their definitions. Essentially, this ensures that the reference counting is done in a threadsafe manner (via InterlockedIncrement()/InterlockedDecrement()), but the access to member data does not use a synchronization object (a Win32 CRITICAL_SECTION).
The FileSearch class is the entry point into the library, and provides the single method Search(), defined by the IFileSearch interface:
interface IFileSearch
: IDispatch
{
HRESULT Search( [in] BSTR searchRoot
, [in] BSTR pattern
, [in] long flags
, [out, retval] IUnknown **_srch);
};
In other words, the caller specifies a search directory, a search pattern, and search flags, and receives an object that corresponds to those parameters. The object is returned via the generic IUnknown interface. The object returned, an instance of SearchCollection, must support the COM Collection model.
Listing 1 is the implementation of FileSearch::Search(). The important feature of this method is that it starts a search before creating a FileSearch instance. This is because it would be possible for a search to fail (for reasons other than that no matching entries were found). In such a case, you want the Search() method to fail and deal with it there, rather than have some weird error reported as you start to enumerate through the collection at some later point.
The other main point to note is that the code is written to work correctly whether you are compiling for Unicode (RECLS_CHAR_TYPE_IS_WCHAR is defined) or ANSI (RECLS_CHAR_TYPE_IS_WCHAR is defined). This facilitates our working with the ATL Wizard-provided project options of Unicode and ANSI releases. Also note that the ANSI version uses the WinSTL (the STLSoft subproject for the Win32 API; http://winstl.org/) w2a() Unicode to ANSI function, which acts as a conversion shim (see my article "Generalized String Manipulation: Access Shims and Type Tunneling," CUJ, August 2003; http://www.cuj.com/documents/s=8681/cuj0308wilson/). The normal way to do such conversion in ATL is to use the W2CA(), A2T(), and associated macros, but I avoid them for three reasons:
The WinSTL components suffer from none of these problems, though they do have the conversion shim return-value lifetime restrictions.
Assuming that the call to Recls_Search() results in a valid search, or fails only for having no matching items, then an instance of the SearchCollection is created and passes a SearchInfo instance containing the attributes of the current search.
Since a recls search has no means to know ahead of time the number of elements that will be found, the Count method is not provided on the collection. Similarly, we cannot index the items because they are enumerated sequentially, nor can we access them by name, so the Item property is not supported either. We're just left with _NewEnum. The SearchCollection class embodies the COM Collection for the recls mapping, and derives from the ISearchCollection interface:
interface ISearchCollection
: IDispatch
{
[propget, id(DISPID_NEWENUM), restricted, hidden]
HRESULT _NewEnum([out,retval] IUnknown** pVal);
};
Its definition is straightforward, since it merely implements the get__NewEnum() method and stores an instance of SearchInfo to record details of the search. The SearchInfo class is defined as:
struct SearchInfo
{
hrecls_t hSrch;
CComBSTR searchRoot;
CComBSTR pattern;
long flags;
bool bEmpty;
SearchInfo()
: hSrch(NULL)
, bEmpty(false)
{}
};
The reason you need to record the search parameters is that there are several points at which a search may need to be (re)initiated. One of these is within the SearchCollection class itself. When client code calls get__NewEnum(), the current search (perhaps the one started in the FileSearch::Search() method) is given over to the object that represents the COM Enumerator for the collection, an instance of the EnumEntry class (which we'll meet shortly). An example of this is found in one of the accompanying test programs, the imaginatively titled VBClient, which provides an almost identical version of the C# client we saw in the second installment. Listing 2, from the search button handler, demonstrates the use of the collection. The For Each statement in Visual Basic causes the given object to be treated as a collection and queried for its enumerator via the _NewEnum property. In fact, it uses the stock DISPID_NEWENUM dispatch ID (DISPID) to identify the property, so you could give it any name. (You use the standard name so that C++ clients can use it directly, rather than having to use IDispatch::Invoke().)
Since there's nothing to stop any client code doing multiple enumerations through the collection's contents, we need to be able to support additional enumerations. Because the recls API has a single pass semantic, you retain the details and then start a new search if you are requested to do so. You might suggest that this is all needless complexity and that searches should only be initiated at the last minute; there's some merit in that position, but I chose this way since it provides more obvious behavior to the client code.
Listing 3 presents the implementation of SearchCollection::get__NewEnum(). Note that, as is the way with ATL, the COM objects must be initialized after construction. You just have to accept this; trying to buck the system will only bring you grief.
The EnumEntry class embodies the COM Enumerator for the recls mapping. Because all this stuff's not complicated enough, I've added an extra twist. For Visual Basic (and other automation languages) clients, the collection must be in the form of an IEnumVARIANT; in other words, the items enumerated by the collection are VARIANTs. However, since the items are always instances implementing the IFileEntry interface (see Listing 4), I've implemented the EnumEntry to provide both IEnumVARIANT and IEnumFileEntry interfaces. This means that C++ clients don't have to go through the tedious extra step of eliciting the interface from the VARIANT (which, to be correct, involves checking that the variant type is VT_UNKNOWN or VT_DISPATCH, then querying for IFileEntry).
Listing 5 is the definition of EnumEntry. The rules of COM dictate that once an object has responded positively to a request for an interface, it must always appear to support that interface. The way EnumEntry works, therefore, is that it maintains two members to monitor which interface, if any, it has provided. Once either IEnumEntry or IEnumVARIANT has been returned, the other interface cannot be made available.
This is accomplished in the QueryFunc() static method, which checks the status of the instance with respect to the two interfaces and accepts or rejects the interface request accordingly. (Some of the code is rather grisly, but it is correct; if you want to look at it, check out the implementation available in this month's code archive, or online at http://recls.org/downloads.html.) The lesser known INTERFACE_MAP entries catch the requests for IEnumVARIANT/IEnumFileEntry, and also ensure that queries for IUnknown always succeed, as they must by the rules of COM.
The other methods in the class are there to define and implement the enumeration interfaces. Since the two interfaces have identical signatures for the Skip() and Reset() methods, they share a single implementation in the class. This is fine in this particular case because the class will only ever support one enumeration interface and, therefore, only one enumerated type: either VARIANT or IFileEntry.
The Next() methods are logically identical, in that they enumerate the entries in the search represented by the hSrch field of the m_info member. The only difference is that one converts to IFileEntry, in the form of a FileEntry instance, whereas the other takes the further step of wrapping that up in a VARIANT.
Clone() is not supported for either interface and returns E_NOTIMPL. Since recls is single pass, there's no guaranteed way to Clone() an enumerator; the rationale for this was discussed in the first installment of the series.
Skip() is implemented by simply calling Recls_GetNext() the requisite number of times. The remaining method, Reset(), is the most interesting of the four (or six). Because the recls API provides single pass enumeration, resetting is implemented as closing the current search and starting a new one. This is the other reason (along with multiple enumerations of the SearchCollection) that we need to record the search criteria. After a call to Reset(), the appropriate Next() method can be called to retrieve the entries of the newly initiated search.
The search entries are represented by the FileEntry class, whose class definition is mostly simple. It implements the IFileEntry interface in Listing 4, and maintains a single recls_info_t member, which it passes to the recls API to retrieve the entry's characteristics.
The only notable aspects of this are the helper methods GetStringProperty_() and GetTimeProperty_().
HRESULT GetStringProperty_(
size_t (*)(recls_info_t, recls_char_t *, size_t)
, BSTR *pVal);
HRESULT GetTimeProperty_( recls_time_t recls_fileinfo_t::*pm
, DATE *pVal);
They encapsulate all the boilerplate COM for string and time property retrieval and use pointers to recls API functions or structure members. Hence, all such property methods have extremely simple implementations, as in:
STDMETHODIMP FileEntry::get_Path(BSTR *pVal)
{
return GetStringProperty_(Recls_GetPathProperty, pVal);
}
STDMETHODIMP FileEntry::get_CreationTime(DATE *pVal)
{
return GetTimeProperty_(&recls_fileinfo_t::creationTime, pVal);
}
The only complexity in the FileEntry class involves the get_DirectoryParts() method (Listing 6), which creates and returns a COM Collection in the form of the DirectoryPartsCollection class (Listing 7). This derives from a parameterization of the ATL ICollectionOnSTLImpl template, which implements the semantics of a COM Collection using an STL container. A full discussion of this template is outside the scope of this article, but there are good sources on the matter, including some of the COM references I gave earlier.
The important point to note is that the STL container used by ICollectionOnSTLImpl is a parameterization of STLSoft's proxy_sequence template, which I mentioned in an earlier installment when I mapped recls to STL sequences. Here, it is used in combination with the dirparts_proxy_traits traits type to create a proxy sequence over the directory parts pointers for a search entry whose value type is CComVariant. In this way, you avoid any unnecessary copying of data from the entry inside the recls API until it is actually needed during an enumeration of the DirectoryPartsCollection by client code. This efficiency is bought for the almost negligible cost of ensuring that the FileEntry instance is kept "alive" for the duration of the DirectoryPartsCollection instance; this is simply and cheaply accomplished by taking a pointer to the owner in the Init() method (Listing 7).
The implementation of dirparts_proxy_traits::make_value() revealed an interesting quirk (bug) within ATL. The original implementation was:
CComVariant make_value(const recls_strptrs_t &ptr)
{
return CComVariant( CComBSTR( ptr.end - ptr.begin
, ptr.begin));
}
Unfortunately, there is a bug in CComBSTR, or rather, in the helper function that it calls — A2WBSTR() — which assumes that the string is null terminated even when we're passing in a length. The actual implementation (Listing 8) instantiates the VARIANT directly, using the SysAllocStringLen() API function.
As I mentioned in the previous installment, I don't hold with the (Unicode) Release MinDependency versus (Unicode) Release MinSize complexity, so I tend to edit projects to produce just two flavors of release — ANSI and Unicode. In general, I like to go even further and ensure that there is a single version that works optimally on both Windows 9x/NT systems. Unfortunately, time was not my friend this month, so this has not been done. Hence, to use the COM mapping in its current guise, you should select between the ANSI and Unicode forms, and build and install the one suitable to your needs: If you only wish to use the recls COM mapping on NT family systems, you should use the Unicode version; otherwise, choose the ANSI version.
Later on, I will look at a way to obviate this hassle and just build a single library that will work optimally on all Win32 platforms.
I've included with this month's archive two test programs for the COM mapping. There's a Visual Basic 6 GUI client, similar to the C# GUI client from earlier in the series, and a C++ command-line client with similar behavior to the other command-line clients we've seen (for C, C++, D, Java, and STL test programs).
I haven't yet decided what language or technology to map recls to for next time, so it'll be a surprise to all of us — probably either Perl or Python. There are a few other changes I'd like to make as well, such as providing a single binary version to work optimally on both Windows 9x/NT, and the API function name rationalization that I've been promising since the first column. Time will tell.
Feel free to write to me (or post a FAQ at http://recls.org/faq.html) and suggest other languages/technologies for which you'd like to see a recls mapping. recls has already been adopted into the D Standard Library (as the std.recls module), and I'm open to any similar possibilities with other languages.
STDMETHODIMP FileSearch::Search( BSTR searchRoot, BSTR pattern
, long flags, IUnknown **ppenum)
{
HRESULT hr;
if(NULL == ppenum)
{
hr = E_POINTER;
}
else
{
*ppenum = NULL;
hrecls_t hSrch;
#ifdef RECLS_CHAR_TYPE_IS_CHAR
recls_rc_t rc = Recls_Search( winstl::w2a(searchRoot)
, winstl::w2a(pattern), flags, &hSrch);
#elif defined(RECLS_CHAR_TYPE_IS_WCHAR)
recls_rc_t rc = Recls_Search( searchRoot, pattern, flags, &hSrch);
#endif /* RECLS_CHAR_TYPE_IS_WCHAR */
if( RECLS_FAILED(rc) &&
rc != RECLS_RC_NO_MORE_DATA)
{
set_error_info_from_recls_rc_t(rc);
hr = E_FAIL;
}
else
{
typedef CComObject<SearchCollection> _Search_t;
_Search_t *pSrch = new _Search_t();
if(NULL == pSrch)
{
Recls_SearchClose(hSrch);
hr = E_OUTOFMEMORY;
}
else
{
pSrch->AddRef();
SearchInfo info;
if(rc == RECLS_RC_NO_MORE_DATA)
{
info.bEmpty = true;
}
else
{
info.hSrch = hSrch;
info.flags = flags;
info.pattern = pattern;
info.searchRoot = searchRoot;
}
pSrch->SetVoid(&info);
ATLASSERT(NULL == info.hSrch);
*ppenum = pSrch;
hr = S_OK;
}
}
}
return hr;
}
May 04: Mapping recls to COM Collections Delving into the Component Object Model
Listing 2: Using the collection.
Private Sub btnSearch_Click()
Dim fs As New RECLS_COMLib.FileSearch
Dim srch As Object
. . . // get search params from dialog controls
Set srch = fs.Search(searchRoot, pattern, flags)
lstFiles.Clear // Empty list box
For Each entry In srch
lstFiles.AddItem (entry) // Add entry to lbox
. . . // other stuff
Next
May 04: Mapping recls to COM Collections Delving into the Component Object Model
Listing 3: SearchCollection::get__NewEnum().
STDMETHODIMP SearchCollection::get__NewEnum(LPUNKNOWN *ppenum)
{
HRESULT hr;
if(NULL == ppenum)
{
hr = E_POINTER;
}
else
{
*ppenum = NULL;
EnumEntry *pee = new CComObject<EnumEntry>();
if(NULL == pee)
{
hr = E_OUTOFMEMORY;
}
else
{
hr = S_OK;
if( NULL == m_info.hSrch &&
!m_info.bEmpty)
{
// This collection has already been used to spawn a
// search, so we need to start another one.
recls_rc_t rc = Recls_Search( . . . );
if(rc != RECLS_RC_NO_MORE_DATA)
{
m_info.bEmpty = true;
}
else if(RECLS_FAILED(rc))
{
set_error_info_from_recls_rc_t(rc);
delete pee;
hr = E_FAIL;
}
}
if(SUCCEEDED(hr))
{
pee->SetVoid(&m_info);
ATLASSERT(NULL == m_info.hSrch);
*ppenum = static_cast<IEnumVARIANT*>(pee);
(*ppenum)->AddRef();
}
}
}
return hr;
}
May 04: Mapping recls to COM Collections Delving into the Component Object Model
Listing 4: IFileEntry interface.
interface IFileEntry : IDispatch
{
HRESULT Path([out, retval] BSTR *pVal);
HRESULT Drive([out, retval] OLECHAR *pVal);
HRESULT Directory([out, retval] BSTR *pVal);
HRESULT DirectoryPath([out, retval] BSTR *pVal);
HRESULT DirectoryParts([out, retval] LPUNKNOWN *pVal);
HRESULT File([out, retval] BSTR *pVal);
HRESULT ShortFile([out, retval] BSTR *pVal);
HRESULT FileName([out, retval] BSTR *pVal);
HRESULT FileExt([out, retval] BSTR *pVal);
HRESULT CreationTime([out, retval] DATE *pVal);
HRESULT ModificationTime([out, retval] DATE *pVal);
HRESULT LastAccessTime([out, retval] DATE *pVal);
HRESULT LastStatusChangeTime([out, retval] DATE *pVal);
HRESULT Size([out, retval] long *pVal);
HRESULT IsReadOnly([out, retval] BOOL *pVal);
HRESULT IsDirectory([out, retval] BOOL *pVal);
};
May 04: Mapping recls to COM Collections Delving into the Component Object Model
Listing 5: EnumEntry definition.
class ATL_NO_VTABLE EnumEntry
: public CComObjectRootEx<CComSingleThreadModel>
, public IEnumVARIANT , public IEnumFileEntry
{
public:
EnumEntry()
: m_bIEnumVARIANT(false)
, m_bIEnumFileEntry(false)
{}
~EnumEntry();
...
static HRESULT WINAPI QueryFunc(void *pv,REFIID riid, LPVOID *ppv,DWORD dw);
DECLARE_PROTECT_FINAL_CONSTRUCT()
BEGIN_COM_MAP(EnumEntry)
COM_INTERFACE_ENTRY2(IUnknown, IEnumVARIANT)
COM_INTERFACE_ENTRY_FUNC(IID_IEnumVARIANT, 0, EnumEntry::QueryFunc)
COM_INTERFACE_ENTRY_FUNC(IID_IEnumFileEntry, 0, EnumEntry::QueryFunc)
END_COM_MAP()
// IEnumXXXX
public:
STDMETHOD(Skip)(/* [in] */ ULONG celt);
STDMETHOD(Reset)();
// IEnumVARIANT
public:
STDMETHOD(Next)(/* [in] */ ULONG celt,
/* [length_is][size_is][out] */ VARIANT *rgVar,
/* [out] */ ULONG *pceltFetched);
STDMETHOD(Clone)(/* [out] */ IEnumVARIANT **ppEnum);
// IEnumFileEntry
public:
STDMETHOD(Next)(/* [in] */ ULONG celt,
/* [length_is][size_is][out] */ PFILEENTRY *rgVar,
/* [out] */ ULONG *pceltFetched);
STDMETHOD(Clone)(/* [out] */ IEnumFileEntry **ppEnum);
// Implementation
private:
HRESULT DoSkip();
HRESULT DoNext(VARIANT *pvar);
HRESULT DoNext(PFILEENTRY *pvar);
// Members
private:
SearchInfo m_info;
bool m_bIEnumVARIANT;
bool m_bIEnumFileEntry;
};
May 04: Mapping recls to COM Collections Delving into the Component Object Model
Listing 6: get_DirectoryParts() method.
STDMETHODIMP FileEntry::get_DirectoryParts(LPUNKNOWN *pVal)
{
typedef CComObject<DirectoryPartsCollection> DirPartsColl_t;
DirPartsColl_t *pcoll;
HRESULT hr = DirPartsColl_t::CreateInstance(&pcoll);
if(SUCCEEDED(hr))
{
directory_parts_type dirParts( m_entry->directoryParts.begin
, m_entry->directoryParts.end);
pcoll->AddRef();
hr = pcoll->Init(static_cast<IFileEntry*>(this), dirParts);
if(SUCCEEDED(hr))
{
hr = pcoll->QueryInterface(pVal);
}
pcoll->Release();
}
return hr;
}
May 04: Mapping recls to COM Collections Delving into the Component Object Model
Listing 7: DirectoryPartsCollection class.
struct dirparts_proxy_traits
{
static CComVariant make_value(const recls_strptrs_t &ptr);
};
typedef stlsoft::proxy_sequence < const recls_strptrs_t, CComVariant
, dirparts_proxy_traits> directory_parts_type;
typedef CComEnumOnSTL < IEnumVARIANT, &IID_IEnumVARIANT, VARIANT,
_Copy<VARIANT>, directory_parts_type>
Enumerator_t;
typedef ICollectionOnSTLImpl < IDirectoryPartsCollection,
directory_parts_type, VARIANT, _Copy<VARIANT>,
Enumerator_t>
Collection_t;
class ATL_NO_VTABLE DirectoryPartsCollection
: public CComObjectRootEx<CComMultiThreadModelNoCS>
, public IDispatchImpl<Collection_t,
&IID_IDirectoryPartsCollection, &LIBID_RECLS_COMLib>
, public atlstl::SupportErrorInfoImpl<&IID_IDirectoryPartsCollection>
{
public:
DirectoryPartsCollection()
: m_punkOwner(NULL)
{}
~DirectoryPartsCollection();
HRESULT Init(LPUNKNOWN punkOwner, directory_parts_type &parts)
{
m_punkOwner = punkOwner;
if(NULL != m_punkOwner)
{
m_punkOwner->AddRef();
}
m_coll = parts; // Copy STL collection
return S_OK;
}
DECLARE_PROTECT_FINAL_CONSTRUCT()
BEGIN_COM_MAP(DirectoryPartsCollection)
COM_INTERFACE_ENTRY(IDirectoryPartsCollection)
COM_INTERFACE_ENTRY(IDispatch)
COM_INTERFACE_ENTRY(ISupportErrorInfo)
END_COM_MAP()
// Members
private:
LPUNKNOWN m_punkOwner;
};
May 04: Mapping recls to COM Collections Delving into the Component Object Model
Listing 8: CComBSTR.
struct dirparts_proxy_traits
{
static CComVariant make_value(const recls_strptrs_t &ptr)
{
CComVariant var;
var.vt = VT_BSTR;
# ifdef RECLS_CHAR_TYPE_IS_CHAR
var.bstrVal = ::SysAllocStringLen(winstl::a2w(ptr.begin,
ptr.end - ptr.begin), ptr.end - ptr.begin);
# elif defined(RECLS_CHAR_TYPE_IS_WCHAR)
var.bstrVal = ::SysAllocStringLen( ptr.begin, ptr.end - ptr.begin);
# endif /* RECLS_CHAR_TYPE_IS_WCHAR */
return var;
}
};
Terms of Service | Privacy Statement | Copyright © 2024 UBM Tech, All rights reserved.