Scrap/ComTutorial/DataMarshalling

UserPreferences

http://progtutorials.tripod.com/COM.htm

1. When is Data Marshaller Needed
2. Data Marshalling and Parameter Direction Attrubutes
3. CoTaskMemAlloc & CoTaskMemFree
4. Example of Passing Arrays
1. IDL
2. Server implementation
3. Client implementation
5. Example of Passing Variable-Length Custom Types
1. IDL
2. Server implementation
3. Client implementation
6. Proxy/StubClasses
7. Marshalling Options
1. Custom Marshalling
2. Standard Marshalling
3. Universal Marshalling
8. Hosting an DLL in a Surrogate Process

1 When is Data Marshaller Needed

When designing a DLL server, you can simply use a pointer to pass into the server an array, just like a normal method call, because the DLL server is in-process and shares the same address space:



[id(1), helpstring("method PassShorts")] 
HRESULT PassShorts([in] short count, [in] short * pShort);

STDMETHODIMP CAny::PassShorts(short * pShort, int count)
{
    char temp[80];
    
    for(int i = 0; i < count; i++)
    {
        sprintf(temp, "%d \n", pShort[i]);
        MessageBox(NULL, temp, "Server", MB_OK);
    }

    return S_OK;
}

When it comes to EXE server, if you use the same code shown above, only pShort0 has a legal value. If you try to access the succeeding array elements, the server will fail.

This is because the server and the client are not in the same address space, the data transfer between the client and the server is taken care of by the marshaller. When the client passes a pointer to the server or vice versa, the receiver actually does not get a pointer pointing to the original location in the sender's address space. Instead it gets a pointer to a copy of data in his own address space allocated by the marshaller. The marshaller transfers the data from the sender to the receiver.

For a in-process method call, both the caller and the method are refering to the same piece of physical data (in case of pass-by-pointer), the reference itself doesn't cause data flow. For a method call between a client and EXE server, however, a data reference itself will cause data flow, and therefore you must tell the marshaller the flow direction and the amount of data to be transfered.

2 Data Marshalling and Parameter Direction Attrubutes

Data marshaller's job is to allocate memory for the destination, and copy data from the corresponding source memory block to the allocated memory. The source and destination is decided by the parameter direction attributes [in] and [out]. The amount of memory to be allocated is decided by the type definition of the parameter and ? if the parameter has a variable size like a variable-size array or structure ? the [size_is] attribute.

Notice that when the parameter is a pointer, the marshaller will not only allocate memory for the pointer itself, but also for the memory block pointed by the pointer. Otherwise the destination side can not make any use of the pointer.

When the direction attribute is [in], before the server method is called, marshaller allocates memory for the server and copies data from the client to server. When the attribute is [out], marshaller allocates memory for the client and copies data from server to it after the server method returns. When the attribute is [in, out], the marshaller does the [in] process before the method call, then the [out] process after the method returns.

Because the marshaller copies data from the source to the allocated memory of the destination, the source must have allocated the corresponding memory before the marshalling process starts. If not, for example, the source only uses a pointer to NULL to call the destination, then run-time error will happen when marshaller accesses the memory pointeded by the source pointer and tries to copy data from it.

Becaue the marshaller usually needs to copy some data from server's memory back to the client after the server method returns, the server should never delete any allocated memory ? no matter it is allocated by the server itself or the marshaller. The marshaller will deallocate all server memory after it finishes the marshalling process. In comparison, the client should always deallocate memory ? no matter it is allocated by the client itself or the marshaller.

Just as in-process method calls, if you want to get result from the called function, you must pass the parameter by pointer. If it is passed by value, the server may modify his copy of the parameter but the client-side parameter will remain unchanged. If the object to be passed itself is a pointer, then it should be passed by a double pointer.

3 CoTaskMemAlloc & CoTaskMemFree

To safely allocate the memory that may be accessed by the marshaller, or deallocate memory allocated by the marshaller, use method CoTaskMemAlloc and CoTaskMemFree, which are known by the marshaller:


LPVOID CoTaskMemAlloc(ULONG ulSize); 
void CoTaskMemFree(void *pv); 

The initial contents of the memory block returned by CoTaskMemAlloc are undefined. It may be larger than required because of the space required for alignment and for maintenance information.

If the required memory size is zero, CoTaskMemAlloc allocates a zero-length item and returns a valid pointer to that item. If there is insufficient memory available, CoTaskMemAlloc returns NULL. Therefore, applications should always check the return value from this method, even when requesting small amounts of memory.

To initialize the allocated memory, use C run time library method memset. Notice that it is always safer to initialize the allocated memory before passing it to anywhere. Errors may be caused by passing uninitialized memory.

Example:


short sSize = 100;
short * pShort;
pShort = reinterpret_cast<short *>(CoTaskMemAlloc(sSize * sizeof(short)));
if(pShort == NULL)
{
    ...
}
::memset(pShort, 0, sSize);
...
CoTaskMemFree(pShort);

4 Example of Passing Arrays

4.1 IDL

import "oaidl.idl"; 
import "ocidl.idl"; 
 
[ 
    object, 
    uuid(5E9396EC-ECA4-45F7-BEB1-EC56C381248A), 
    helpstring("IAny Interface"), 
    pointer_default(unique) 
] 
 
interface IAny : IUnknown 
{ 
    // Passing info from client to server 
    [helpstring("method PShortsClientAlloc")]  
    HRESULT PassIn( 
        [in] short count,  
        [in, size_is(count)] short * pShort); 
 
    // Passing info from server to client 
    [helpstring("method GShortsServerAlloc")]  
    HRESULT PassOut( 
        [out] short * pCount,  
        [out, size_is(1, *pCount)] short ** ppShort); 
 
    // passing info bidirectionally  
    [helpstring("method PassArray")]  
    HRESULT PassBirect( 
        [in, out] short * psSize,  
        [in, out, size_is(1, *psSize)] short ** pps);     
}; 
 
[ 
    uuid(BA65DD03-CEBC-4E7A-A968-033C1C542FB7), 
    version(1.0), 
    helpstring("Server 1.0 Type Library") 
] 
 
library SERVERLib 
{ 
    importlib("stdole32.tlb"); 
    importlib("stdole2.tlb"); 
 
    [ 
        uuid(963BC191-1265-4E90-A330-13787BCA9437), 
        helpstring("Any Class") 
    ] 
 
    coclass Any 
    { 
        [default] interface IAny; 
    }; 
}; 
 
 == Server implementation == 
  {{{
STDMETHODIMP CAny::PassIn(short count, short * pShort)
{
    char buf[80];

    for(short i = 0; i < count; i++)
    {
        sprintf(buf, "Passed from client: %d", pShort[i]);
        if((i % 1000) == 0)
            ::MessageBox(NULL, buf, "Server", MB_OK);
    }

    return S_OK;
}

STDMETHODIMP CAny::PassOut(short * pCount, short ** ppShort)
{
    short sSize = 10;
    (*pCount) = 10;
    (*ppShort) = (short *)CoTaskMemAlloc(sSize * sizeof(short));
    if((*ppShort) == NULL)
        return E_OUTOFMEMORY;

    for(short i = 0; i < sSize; i++)
        (*ppShort)[i] = i;

    return S_OK;
}

STDMETHODIMP CAny::PassBidirect(short * pSize, short **pps)
{
    char buf[80];
    for(short i = 0; i < *pSize; i++)
    {
        sprintf(buf, "Passed from client:\n*pps[%d] = %d", i, (*pps)[i]);
        ::MessageBox(NULL, buf, "Server", MB_OK);
    }

    CoTaskMemFree(*pps);
    short sSize = 10;

    (*pps) = (short *)CoTaskMemAlloc(sSize * sizeof(short));
    for(i = 0; i < sSize; i++)
    {
        (*pps)[i] = i * i;
    }
    (*pSize) = sSize;
    return S_OK;
}

 == Client implementation ==
  {{{
#!cpp
void CClientDlg::OnPassIn() 
{
    const short sSize = 7001;
    short * pShort;
    pShort = (short *)CoTaskMemAlloc(sSize * sizeof(short));
    if(pShort == NULL)
    {
        ::MessageBox(NULL, "CoTaskMemAlloc failed!", "Client", MB_OK);
        return;
    }

    for(short i = 0; i < sSize; i++)
        pShort[i] = i;

    HRESULT hr = m_pAny->PassIn(sSize, pShort);
    if(FAILED(hr))
        ::MessageBox(NULL, "PassShorts failed!", "Client", MB_OK);

    CoTaskMemFree(pShort);
}

void CClientDlg::OnPassOut() 
{
    short sSize;
    short * pShort = NULL;
    HRESULT hr = m_pAny->PassOut(&sSize, &pShort);
    if(FAILED(hr))
        ::MessageBox(NULL, "PShortsServerAlloc failed!", "Client", MB_OK);

    char buf[80];
    for(short i = 0; i < sSize; i++)
    {
        sprintf(buf, "Got from server: %d", pShort[i]);
        if((i % 1000) == 0)
            ::MessageBox(NULL, buf, "Client", MB_OK);
    }

    CoTaskMemFree(pShort);
}

void CClientDlg::OnPassBidirect() 
{
    sSize = 5;
    short * ps = (short *)CoTaskMemAlloc(sSize * sizeof(short));
    for(i = 0; i < sSize; i++)
        ps[i] = i;

    hr = pAny->PassBidirect(&sSize, &ps);
    if(FAILED(hr))
    {
        ::MessageBox(NULL, "PassArray failed!", "Client", MB_OK);
        return;
    }

    char buf[80];
    for(i = 0; i < sSize; i++)
    {
        sprintf(buf, "Passed from client:\nps[%d] = %d", i, ps[i]);
        ::MessageBox(NULL, buf, "Server", MB_OK);
    }

    CoTaskMemFree(ps);
}

5 Example of Passing Variable-Length Custom Types

5.1 IDL

import "oaidl.idl"; 
import "ocidl.idl"; 
 
typedef struct  
{ 
    short sSize; 
    [size_is(sSize)] short sArray[]; 
} Group; 
 
[ 
    object, 
    uuid(9BF19302-65E6-4218-8C6F-55C3816123F5), 
    helpstring("IAny Interface"), 
    pointer_default(unique) 
] 
 
interface IAny : IUnknown 
{ 
    [helpstring("method StructInOut")]  
    HRESULT StructInOut([in, out] Group ** ppg); 
}; 
 
[ 
    uuid(185CB840-2F73-4095-A165-8FAFEDA1CBF8), 
    version(1.0), 
    helpstring("Marshal 1.0 Type Library") 
] 
 
library MARSHALLib 
{ 
    importlib("stdole32.tlb"); 
    importlib("stdole2.tlb"); 
 
    [ 
        uuid(27FE57E8-26EF-4E41-AEB9-79DE4079F0E1), 
        helpstring("Any Class") 
    ] 
 
    coclass Any 
    { 
        [default] interface IAny; 
    }; 
}; 




5.2 Server implementation

STDMETHODIMP CAny::StructInOut(Group **ppg)
{
    char buf[100];
    for(short i = 0; i < (*ppg)->sSize; i++)
    {
        sprintf(buf, "(*ppg)->sArray[%d] = %d", i, (*ppg)->sArray[i]);
        M(buf); // Macro to simplify function ::MessageBox
    }

    CoTaskMemFree(*ppg);

    short sSize = 20;
    (*ppg) = (Group *)CoTaskMemAlloc(sSize * sizeof(short) + sizeof(Group));
    if((*ppg) == NULL) // must check the result of memory allocation
    {
        ::MessageBox(NULL, " CoTaskMemAlloc failed!", "Server", MB_OK);
        return E_OUTOFMEMORY;
    }

    (*ppg)->sSize = sSize;
    for (i = 0; i < (*ppg)->sSize; i++) 
        (*ppg)->sArray[i] = i * i;   

    return S_OK;
}





5.3 Client implementation

void CClientDlg::OnButton3() 
{
    short lSize = 5;
    Group * pg;
    pg = (Group *)CoTaskMemAlloc(lSize * sizeof(short) + sizeof(Group));
    if(pg == NULL)
    {
        M("CoTaskMemAlloc failed!");
        return;
    }

    pg->sSize = lSize;
    for(short i = 0; i < lSize; i++)
        pg->sArray[i] = i;
 
    HRESULT hr = m_p->StructInOut(&pg);
    if(FAILED(hr))
        M("StructInOut failed");

    char buf[100];
    for(i = 0; i < pg->sSize; i++)
    {
        sprintf(buf, "pg->sArray[%d] = %d", i, pg->sArray[i]);
        M(buf);
    }

    CoTaskMemFree(pg);
}

6 Proxy/StubClasses

A proxy resides in the client's process and represents the server, and a stub resides in the server's process to receive data sent from the proxy and send server's response back. They are all standard COM objects residing in a DLL server. On such DLL server may contain many proxy/stub classes.

Each interface in a server is represented by a separate proxy and stub coclass. Each proxy coclass implements two interfaces: the one which it represents and a standard interface IRpcProxyBuffer, which has method Connect and Disconnect.

Channel object implementing interface IRpcChannelBuffer is responsible to conduct the data transfer between the proxy and the stub. Proxy manager is responsible to connect proxy objects to the channel object, and assemble the proxy objects representing different interfaces of one coclass together using COM aggregation, so that the cluster of proxy coclasses appears to the client as a cluster of interfaces of one coclass.

A stub implements IRpcStubBuffer and is managed by the stub manager. Stub manager doesn't aggregate the stubs.

Class factories implement interface IPSFactoryBuffer. One class factory is responsible to create both the proxy and stub for a given server coclass with its method CreateProxy and CreateStub.

7 Marshalling Options

7.1 Custom Marshalling

If you choose to write all marshalling code yourself, you should let your coclass implement interface IMarshal. SCM will query for IMarshal first. This marshalling option is called custom marshalling.



7.2 Standard Marshalling

This is an easier option. When MIDL compiles the IDL file it will generate all files that is needed to build the proxy/stub DLL, such as Shape_i.c, Shape.h, Shape_p.c and dlldata.c. ATL AppWizard can generate a make file which can automatically build the proxy/stub DLL from the above four files. To build the proxy/stub DLL server and register it:


nmake ProjectNameps.mk  
regsvr32 ProjectNameps.dll 

You can put the last two commands in mene “Project” | “Settings” | “Custom build”. This way every time you build the project the rest is done automatically.

When client invokes an interface, SCM will find the interface entry under HKCR\Interface, then the ProxyStubClsid32 entry under it, which points to the corresponding custom proxy/stub DLL. Then SCM will call the class factory and instantiate a proxy/stub object to prepresent the interface.



7.3 Universal Marshalling

The third option is to use the universal marshaller oleaut32.dll. The ProxyStubClsid32 entries of all interfaces should point to this universal marshaller, and the TypeLib entries point to the registered type library. The universal marshaller will find the registered type library of the invoked interface, read the type information in it, and create the proxy/stub DLL on the fly.

To use universal marshaller, you have to:


1. Put attribute [oleautomation] in front of all interfaces and make them variant compatible;
   
2. Register the type library;
   
3. Register all interfaces and set the value of ProxyStubClsid32 entry under each interface to the guid of oleaut32.dll and the value of TypeLib entry to your type library guid.
   
   
You can also do all the above things through a function call at run time:


ITypeLib * ptlb = NULL;
LoadTypeLibEx(L”Shapes.tlb”, REGKIND_REGISTER, &ptlb);
ptlb->Release();

If there is [oleautomation] attribute in front of all interfaces in the IDL file, this function will point the ProxyStubClsid32 entry to the universal marshaler.

8 Hosting an DLL in a Surrogate Process

To host a DLL in an EXE housing named dllhost.exe, you need to have an AppID for the DLL server and have a DllSurrogate entry under it. When its value is "", it means that we use the default surrogate dllhost.exe.

To automatically assign an AppID and add a DllSurrogate entry under it, open the DLL object under "All Object" entry of OLE/COM Object Viewer. Tick the "Use Surrogate Process" option. The COM objects in the DLL server must support aggregation.

• see also COM
  

• CategorySystemProgramming