I have worked with client-server applications for a couple of years now, all of these applications use RPC as the layer of communication between the client and the server. I found it strange that no real article existed on this matter here on CodeProject, so I decided to write one of my own to spread my knowledge on this matter.

The matter is on the other hand a bit big, so I have decided to split it into several articles of different levels of difficulty. This is the second article and it will introduce you to context handles. You should have read the previous article before reading this one.

What is a context handle and what is it good for? Well we use context handles all the time when we are programming, but often they have different names in different places. You can think of a context handle as the equivalent to the this-pointer in C++, the HANDLE returned from CreateFile, or the FILE*-pointer returned from fopen. They are all different context handles that behave somewhat different, but they accomplish the same thing: they all connect to an object.

The different context handles you are used to, are more or less opaque, in RPC the context handles are totally opaque as they are actually pointers of type void*.

It is time to expand the Hello World example from my previous article with the use of a rather simple context handle. There is no better time than now.

// File ContextExample.idl
[
// A unique identifier that distinguishes this// interface from other interfaces.uuid(00000003-EAF3-4A7A-A0F2-BCE4C30DA77E),
// This is version 1.0 of this interface.version(1.0),
// This interface will use explicit binding handle.explicit_handle
]
interface ContextExample // The interface is named ContextExample
{
// To fully use context handles we need to do a typedef.typedef [context_handle] void* CONTEXT_HANDLE;
// Open a context on the server.
CONTEXT_HANDLE Open(
// Explicit server binding handle.
[in] handle_t hBinding,
// String to be output on the server.
[in, string] const char* szString);
// Output the context string on the server.void Output(
// Context handle. The binding handle is implicitly// used through the explicit context handle.
[in] CONTEXT_HANDLE hContext);
// Closes a context on the server.void Close(
// Context handle. The binding handle is implicitly// used through the explicit context handle.
[in, out] CONTEXT_HANDLE* phContext);
}

What has changed in this example from the previous one? We have added a typedef of a context handle named CONTEXT_HANDLE ("Oooh", the masses roar). We have also added two functions to open and close the context handle. The Output function has been changed so that it takes a context handle instead of a string. And that's it, nothing else has changed.

As you can see we are using explicit binding handles, but the Output and the Close functions do not refer to the binding handle directly. They both use the binding handle indirectly through the context handle. A client side context handle contain the binding handle it is connected to, so there is no real need to send both the binding handle and the context handle to the functions.

Now the server implementation is rather big compared to our first standalone application, but not so much bigger than the server example in the previous article.

So what has changed? The implementation of the Open and Close functions were added. As you can see the context handle is in fact a pointer to a std::string but disguised as a CONTEXT_HANDLE (that in turn is a pointer of type void*). The server is now more verbose, it writes what it is doing and any errors to the console window. The actual functionality to listen to incoming RPC calls is now implemented in a thread, this in turn allows the server to be shutdown by pressing enter, instead of killing it by closing the window. The memory allocation and de-allocation routines remain the same.

Something that I haven't talked about yet is the rundown routine. What is a rundown routine, you may ask. A rundown routine is a chance for the server to free any resources allocated by a context handle, if the the client is disconnected from the server. The rundown routine is automatically called by the RPC runtime for each open context handle in the client, if the client somehow is disconnected from the server.

What has changed since the last time? We are checking the state of the binding handle before we are using it by using RpcEpResolveBinding. This will try to verify that the server is running (or not) before we use any of it's exposed RPC functions. Then we create a context, outputs the string using this context and finally closes the context. The client is now more verbose, it writes what it is doing and any errors to the console window. The memory allocation and de-allocation routines remain the same.

To test the rundown routine in the server, I have added some points in the code where it waits for the user to press enter. If you kill the application by closing the window instead of pressing enter, you will see the rundown in effect.

The example showed in this article is not thread-safe. If two threads does things in the server at the same time, things could start behaving strange or even crash. In this simple example it does not matter, but it could easily be fixed by using some sort of mutual exclusive synchronization objects (critical sections). This will be addressed in a future article.

Using context handles in RPC is a very powerful thing, it helps you to develop object oriented applications with RPC. An object on the server can be represented by a context handle on the client, and using encapsulation, the implementation of an object on the client can often map functions directly to the server, by using context handles.

Still we have only scratched the surface of the world of RPC and client/server applications. In my future articles, we will dig even deeper.

Comments and Discussions

Thank you for your good examples! I tried your example, they are so good! But I can't send unsigned char array by your two examples. I tried some function include remove MIDL [string] and to define the function like:
CONTEXT_HANDLE Open(
// Explicit server binding handle.
[in] handle_t hBinding,
[in, out, size_is(1048576), string] unsigned char* szString);
But still can't transmit the char array include '\0'. I tried to convert my image Mat data to another char array, but to the server side will get a error.
I tried it almost one week... waiting for your any suggestion. Thanks!

I want to use an operation from the lsarpc interface (lsarpc),
the operation is "CredrEnumerate" it is the #62 operation (I know there is a Windows API called "CredEnumerate").
is it possible to call an RPC interface that was not developed by me? I mean that I don't have the interface file (idl file).
if it is please help me implement it.

Hi
I have a server application running in one machine and client application is running in another machine. RpcServerListen function is running in a thread function.
I have a Shutdown function in server which contains RpcMgmtStopServerListening(NULL) and CloseHandle(hThread). I made sure that RpcServerListen function returned with no error after calling Shutdown function from server.

My problem is after calling shutdown function, if I make any call from client application, server and client both applications are abruptly closed. I checked "netstat -a" in command prompt, I could see my port is still in LISTENING state after calling Shutdown function (Port is not supposed to listen after calling RpcMgmtStopServerListening since there is no pending calls).

The port is closed only if I close server application. I tried calling RpcServerUnregisterIf function in Shutdown function but no change in result. How to resolve this issue ?

I having problem by reaching a server in a dll. I really at the beginning of exploring the RPC world, but I made some experiments based this great introduction. I get everything to work but if I put the server in my dll I can not reach it. I am sure I over see something simple but would be nice to get a direction. thanks.

For example I generated proxy and stub for COM object interface written in IDL. I implemented COM object.
Can I avoid COM activation (Windows Registry, Running Object Table, CoInitialize, etc.) stuff and do activation and hosting of COM object via RPC routines directly? I know that COM goes to RPC to talk to another process.

Is such feature possible in RPC?
Or http://en.wikipedia.org/wiki/Microsoft_RPC is not very true saying "inheritance of interfaces" supported?
Or there some hack exsits, like generate to interfaces separately but merge C code later?

thank you for answering me.
I change the character set to Use Multi-Byte Character Set but it donot solve the error so i change the code .
unsigned char str[20];
memcpy(str,"hello world",20);
CONTEXT_HANDLE hContext = Open(hBinding, str);

but when i run the program i get this error rpcmgmt is serverlistening failed.access is denied.<5>