Introduction to RPC - Part 1

Download source files - 13.1 Kb

Download demo project - 314 Kb

Contents

Introduction

IDL, RPC and you
Interface Definition Language (IDL)

Remote Procedure Call (RPC)

Are you scared yet?

The standalone application
Hello Lonely World!

The IDL file
Hello IDL World!

What's next?

How may I serve you?
Hello Server World!

Let me be your client
Hello Client World!

Putting it all together

Appendix
Debugging and RPC

Implicit and explicit handles

Application Configuration File (ACF)

Don't fiddle with the generated files

Shutting down the server

Conclusion

References

Revision history

Introduction

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 will split it into
several articles of different levels of difficulty. This first one is
at beginner level.

IDL, RPC and you

In order to use RPC, you need to have some knowledge about IDL, but don't you worry, this article will help you.

Interface Definition Language (IDL)

IDL stands for Interface Definition Language and it's a language for
defining interfaces (no kidding). Writing an IDL file is somewhat like
writing a C header file with some additional keywords and constructs.
IDL is an attributed programming language and thus it can describe
parameters, functions and interfaces in more detail than C.

Remote Procedure Call (RPC)

Remote Procedure Call (RPC) defines a powerful technology for
creating distributed client/server programs. The RPC runtime libraries
manage most of the details relating to network protocols and
communication. This enables you to focus on the details of the
application rather than the details of the network.

With RPC a client can connect to a server running on another
platform. For example: The server could be written for Linux and the
client could be written for Win32.

Are you scared yet?

If you're not scared, I think it's good time for an example.

The standalone application

This standalone application will not use RPC and it is a simple
HelloWorld application that we later will transform into a RPC
client/server application.

Hello Lonely World!

Collapse

// File Standalone.cpp

#include <iostream>

// Future server function.

void Output(const char* szOutput)
{
std::cout << szOutput << std::endl;
}

int main()
{
// Future client call.

Output("Hello Lonely World!");
}

I don't think anyone can think of anything to say about the above application. It outputs the string

"Hello Lonely World!"

to the standard output.

The IDL file

It is time to define our interface in IDL.

Hello IDL World!

Collapse

// File Example1.idl

[
// A unique identifier that distinguishes this

// interface from other interfaces.

uuid(00000001-EAF3-4A7A-A0F2-BCE4C30DA77E),

// This is version 1.0 of this interface.

version(1.0),

// This interface will use an implicit binding

// handle named hExample1Binding.

implicit_handle(handle_t hExample1Binding)
]
interface Example1 // The interface is named Example1

{
// A function that takes a zero-terminated string.

void Output(
[in, string] const char* szOutput);
}

Here you see the attribute programming used by IDL. The above
example defines an interface with an universally unique identifier (

uuid

) and version (

version

) that is named

Example1

. The

Example1

interface defines one function named

Output

that takes a

const char*

argument named

szOutput

as input (

in

) that is zero-terminated (

string

).

The

implicit_handle

attribute for the interface will be discussed later, leave it there for now.

What's next?

In order to use the IDL in our application we need to run it through a compiler (midl.exe)
that will translate the IDL to a client proxy and a server stub in C.
The proxy/stub will later be compiled using your favorite compiler (cl.exe in my case).

How may I serve you?

It's time to take the generated files and put them to use in our server application.

Hello Server World!

Collapse

// File Example1Server.cpp

#include <iostream>

#include "Example1.h"

// Server function.

void Output(const char* szOutput)
{
std::cout << szOutput << std::endl;
}

int main()
{
RPC_STATUS status;

// Uses the protocol combined with the endpoint for receiving

// remote procedure calls.

status = RpcServerUseProtseqEp(
reinterpret_cast<unsigned char*>("ncacn_ip_tcp"), // Use TCP/IP

// protocol.

RPC_C_PROTSEQ_MAX_REQS_DEFAULT, // Backlog queue length for TCP/IP.

reinterpret_cast<unsigned char*>("4747"), // TCP/IP port to use.

NULL); // No security.

if (status)
exit(status);

// Registers the Example1 interface.

status = RpcServerRegisterIf(
Example1_v1_0_s_ifspec, // Interface to register.

NULL, // Use the MIDL generated entry-point vector.

NULL); // Use the MIDL generated entry-point vector.

if (status)
exit(status);

// Start to listen for remote procedure

// calls for all registered interfaces.

// This call will not return until

// RpcMgmtStopServerListening is called.

status = RpcServerListen(
1, // Recommended minimum number of threads.

RPC_C_LISTEN_MAX_CALLS_DEFAULT, // Recommended

//maximum number of threads.

FALSE); // Start listening now.

if (status)
exit(status);
}

// Memory allocation function for RPC.

// The runtime uses these two functions for allocating/deallocating

// enough memory to pass the string to the server.

void* __RPC_USER midl_user_allocate(size_t size)
{
return malloc(size);
}

// Memory deallocation function for RPC.

void __RPC_USER midl_user_free(void* p)
{
free(p);
}

This is a bit different from the standalone application, but not
much. It has some initialization code for registering the interface but
the

Output

function remains the same.

Let me be your client

Time has come to write our client application that will connect to the server.

Hello Client World!

Collapse

// File Example1Client.cpp

#include <iostream>

#include "Example1.h"

int main()
{
RPC_STATUS status;
unsigned char* szStringBinding = NULL;

// Creates a string binding handle.

// This function is nothing more than a printf.

// Connection is not done here.

status = RpcStringBindingCompose(
NULL, // UUID to bind to.

reinterpret_cast<unsigned char*>("ncacn_ip_tcp"), // Use TCP/IP

// protocol.

reinterpret_cast<unsigned char*>("localhost"), // TCP/IP network

// address to use.

reinterpret_cast<unsigned char*>("4747"), // TCP/IP port to use.

NULL, // Protocol dependent network options to use.

&szStringBinding); // String binding output.

if (status)
exit(status);

// Validates the format of the string binding handle and converts

// it to a binding handle.

// Connection is not done here either.

status = RpcBindingFromStringBinding(
szStringBinding, // The string binding to validate.

&hExample1Binding); // Put the result in the implicit binding

// handle defined in the IDL file.

if (status)
exit(status);

RpcTryExcept
{
// Calls the RPC function. The hExample1Binding binding handle

// is used implicitly.

// Connection is done here.

Output("Hello RPC World!");
}
RpcExcept(1)
{
std::cerr << "Runtime reported exception " << RpcExceptionCode()
<< std::endl;
}
RpcEndExcept

// Free the memory allocated by a string.

status = RpcStringFree(
&szStringBinding); // String to be freed.

if (status)
exit(status);

// Releases binding handle resources and disconnects from the server.

status = RpcBindingFree(
&hExample1Binding); // Frees the implicit binding handle defined in

// the IDL file.

if (status)
exit(status);
}

// Memory allocation function for RPC.

// The runtime uses these two functions for allocating/deallocating

// enough memory to pass the string to the server.

void* __RPC_USER midl_user_allocate(size_t size)
{
return malloc(size);
}

// Memory deallocation function for RPC.

void __RPC_USER midl_user_free(void* p)
{
free(p);
}

Other than connecting to the server and some cleanup, the actual
call is the same, except that I've changed the string to be outputted.

Putting it all together

First we need to compile the IDL file to get the client proxy, the
server stub and the common header file. The proxy and the stub is
compiled, as are the client and server implementation. We link the two
applications and run them. If everything works, we can be really glad
as we have done our first RPC client/server application.

Appendix

This section describes some techniques useful when writing RPC applications.

Debugging and RPC

If you get into trouble when debugging and the problem seem to be in
a MIDL generated file, the real problem will most likely be in the
client or in the server. I have sometime run into problems with
pointers, but in a follow up article I will describe these things more
thoroughly.

Implicit and explicit handles

When using RPC, the binding handles can be implicit (as in the
example in this article) or explicit. I always use explicit handles as
I sometime are connected to multiple servers, and that does not work
with the implicit handle. To use explicit handles, you'll have to
change the IDL file, the server and the client:


Collapse

// File Example1Explicit.idl

[
// A unique identifier that distinguishes this

// interface from other interfaces.

uuid(00000002-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 Example1Explicit // The interface is named Example1Explicit

{
// A function that takes a binding handle and a zero-terminated string.

void Output(
[in] handle_t hBinding,
[in, string] const char* szOutput);
}

Collapse

// File Example1ExplicitServer.cpp

#include <iostream>

#include "Example1Explicit.h"

// Server function.

void Output(handle_t hBinding, const char* szOutput)
{
std::cout << szOutput << std::endl;
}

// main - same as before.

Collapse

// File Example1ExplicitClient.cpp

#include "Example1Explicit.h"

int main()
{
// Call to RpcStringBindingCompose - same as before.

handle_t hExample1ExplicitBinding = NULL;

// Validates the format of the string binding handle and converts

// it to a binding handle.

// Connection is not done here either.

status = RpcBindingFromStringBinding(
szStringBinding, // The string binding to validate.

&hExample1ExplicitBinding); // Put the result in the explicit

// binding handle.

if (status)
exit(status);

RpcTryExcept
{
// Calls the RPC function. The hExample1ExplicitBinding binding handle

// is used explicitly.

// Connection is done here.

Output(hExample1ExplicitBinding, "Hello RPC World!");
}
RpcExcept(1)
{
std::cerr << "Runtime reported exception " << RpcExceptionCode()
<< std::endl;
}
RpcEndExcept

// Call to RpcStringFree - same as before.

// Releases binding handle resources and disconnects from the server.

status = RpcBindingFree(
&hExample1ExplicitBinding); // Frees the binding handle.

if (status)
exit(status);
}

There are also something called

auto_handle

, but I've never ever used that. It somehow takes care about connecting to the server automatically.

Application Configuration File (ACF)

In this example I used

implicit_handle

and

explicit_handle

directly in the IDL file, but that is a Microsoft extension. One
usually need to use a separate Application Configuration File that
contain these. The sample code in the zip file does use a separate ACF
file, but I felt like, writing that in the article would only confuse
you even more.

Don't fiddle with the generated files

You should not fiddle with the generated files to make them compile, they are (should be) correct. Check the switches to midl.exe
if you feel that they are incorrect. When compiling them you may on the
other hand get a lot of warnings, but when lowering the warning level
to 2, they are silent.

Shutting down the server

The example server will run until it is shut down by closing it
somehow. That ain't the best way of doing it, another better way is to
call the

RpcMgmtStopServerListening

function. But how would you call it? You could add another function in the interface (perhaps named

Shutdown

?) that will call

RpcMgmtStopServerListening

or you could create another thread in the server before calling

RpcServerListen

that will call

RpcMgmtStopServerListening

after a minute or so. More on this in another article.

Conclusion

This is only the entry door to the world of RPC and client/server
applications. If you step through and read my other (future) articles
on this matter, you'll be fully prepared for the world at hand.

This was my first ever article on CodeProject, I hope you enjoyed reading it as much as I enjoyed writing it.

References

MSDN - Microsoft Interface Definition Language [^]

MSDN - MIDL and RPC [^]

MSDN - Remote Procedure Call [^]

The OSF Distributed Computing Environment [^]

Revision history

2003-08-25:
Updated demo and source.

Changed from Named Pipe to TCP/IP (suggestion by Hector Santos).

2003-08-23:
Original article.

License

This article, along with any associated source code and files, is licensed under The Code Project Open License (CPOL)

About the Author

Anders Dalvander

Occupation: Web Developer Location: Sweden

From: http://www.codeproject.com/KB/IP/rpcintro1.aspx