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.

In the prototype you will see specifiers that tell your idl compiler (i.e. MIDL) how much memory an array requires and how much data to transmit.
The first argument dwLength is the number of array elements to send when MyFunc is called. size_is(dwLength) says that dwLength is the number of bytes required for the array and length_is(dwLength) says to consult dwLength to determine how many array elements to send.

hi,
i am developing application using RPC.Inthis application multiple client calling the remoteprocedure from server. My code is work properly ,but if two client call procedure at same time then one of the client is getting error.
please suggest solution for how to handle multiple client procedure calls.

Hi,
Interesting sample. An academical question though ... If you use RpcServerUseProtseqEp(), that means you will not be able to start a server, shut it down and start it again without having to terminate the server process right ? As far as I understand enpoint you specify in the call to RpcServerUseProtseqEp will stick around and there is no way to "unregister" that endpoint without terminating the process.