(navigation image)
Home American Libraries | Canadian Libraries | Universal Library | Community Texts | Project Gutenberg | Children's Library | Biodiversity Heritage Library | Additional Collections
Search: Advanced Search
Anonymous User (login or join us)
Upload
See other formats

Full text of "Microsoft RPC programming guide"

Distributed Applications 




Microsoft RFC 



Programming Guide 



A NUTSHELL* 




HANDBOOK 



John Shirley & Ward Rosen berry 

O Reilly & Associates, Inc. 



Microsoft RFC Programming Guide 



Microsoft RFC Programming Guide 



John Shirley and Ward Rosenberry 

Digital Equipment Corporation 



O Reilly & Associates, Inc. 

103 Morris Street, Suite A 

Sebastopol, CA 95472 



Microsoft RFC Programming Guide 

by John Shirley and Ward Rosenberry 

Copyright 1995 O Reilly & Associates, Inc. All rights reserved. 
Printed in the United States of America. 

ditor Andy Oram 

Production Editor: Clairemarie Fisher O Leary 

Printing History: 

March 1995: First Edition. 



O Reilly & Associates and the author specifically disclaim all warranties, expressed or implied, 
including but not limited to implied warranties of merchantability and fitness for particular purpose 
with respect to the diskettes and the programs therein contained, and in no event shall O Reilly & 
Associates or the author be liable for any loss of profit or any other commercial damage, including 
but not limited to special, incidental, consequential, or other damages. 

Nutshell Handbook and the Nutshell Handbook logo are registered trademarks of O Reilly & 
Associates, Inc. 

Many of the designations used by manufacturers and sellers to distinguish their products are claimed 
as trademarks. Where those designations appear in this book, and O Reilly & Associates, Inc. was 
aware of a trademark claim, the designations have been printed in caps or initial caps. 

While every precaution has been taken in the preparation of this book, the publisher assumes no 
responsibility for errors or omissions, or for damages resulting from the use of the information 
contained herein. 



This book is printed on acid-free paper with 85% recycled content, 15% post-consumer waste. 
O Reilly & Associates is committed to using paper with the highest recycled content available 
consistent with high quality. 



ISBN: 1-56592-070-8 



Table of Contents 



Preface xi 

Conventions xii 

Book Organization xii 

How to Use This Book xiii 

Obtaining the Example Programs xiv 

CompuServe xiv 

FTP xvi 

FTPMAIL xvii 

BITFTP xvii 

Acknowledgments xviii 

Joint Venture xix 

1: Overview of an RFC Application 1 

A Simple -Interface 4 

Universal Unique Identifiers 5 

The Interface Definition 6 

Stub and Header Generation Using the MIDI Compiler 7 

A Simple Client 8 

A Minimal Server 11 

Remote Procedure Implementation 11 

A Distributed Application Environment 13 

Server Initialization 18 

Producing the Application 21 

Microsoft RFC Libraries . .21 



vi Microsoft RFC Programming Guide 

Compile and Link the Client and Server Code 21 

Running the Application 23 

2: Using a Microsoft RFC Interface 27 

Microsoft Interface Definition Language (MIDI) 28 

Attributes 28 

Structure of an Interface Definition 29 

Interface Header Attributes 29 

The Inventory Application 30 

Type Definitions, Data Attributes, and Constants 30 

Procedure Declarations and Parameter Attributes 38 

Using the MIDI Compiler 40 

Generating Client Files 42 

Generating Server Files 42 

Using an ACF to Customize Interface Usage 42 

Selecting a Binding Method 43 

Controlling Errors and Exceptions 44 

Excluding Unused Procedures 44 

3: How to Write Clients 45 

Binding 45 

Implementing a Binding Method 46 

Automatic Binding Management 49 

Implicit Binding Management 50 

Explicit Binding Management 52 

Steps in Finding Servers 55 

Finding a Protocol Sequence 56 

Finding a Server Host 58 

Finding an Endpoint 59 

Interpreting Binding Information 60 

Finding a Server from a Name Service Database 6l 

Finding a Server from Strings of Binding Data 64 

Customizing a Binding Handle 66 

Authentication 71 

Error Parameters or Exceptions 72 

Using Exception Handlers in Clients or Servers 72 

Using Remote Procedure Parameters to Handle Errors 72 

Compiling and Linking Clients 74 

Local Testing 76 



Table of Contents vii 

4: Pointers, Arrays, and Memory Usage 79 

Kinds of Pointers 79 

Pointers as Output Parameters 80 

Pointers as Input Parameters 82 

Using Pointers to Pointers for New Output 84 

Pointers as Procedure Return Values 86 

Pointer Summary 87 

Kinds of Arrays 90 

Selecting a Portion of a Varying Array 90 

Managing the Size of a Conformant Array 91 

Memory Usage 94 

Node-By-Node Allocation and Deallocation 96 

Using Contiguous Server Memory 97 

Allocating Buffers with the Client Application 97 

Persistent Storage on the Server 98 

5: How to Write a Sewer 99 

Some Background on Call Processing 99 

Initializing the Server 101 

Registering Interfaces 102 

Creating Server Binding Information 104 

Advertising the Server 107 

Managing Server Endpoints 109 

Listening for Remote Procedure Calls 110 

Writing Remote Procedures 112 

Managing Memory in Remote Procedures 113 

Allocating Memory for Conformant Arrays 116 

Compiling and Linking Servers 117 

6: Using a Name Service 121 

Naming 122 

DefaultEntry 122 

Server Entries 123 

Creating a Server Entry and Exporting Binding Information 125 

Some Rules for Using the Microsoft Locator 126 



viii Microsoft RFC Programming Guide 

7: Context Handles 729 

The Remote_file Application 129 

Declaring Context in an Interface Definition 130 

Using a Context Handle in a Client 131 

Binding Handles and Context Handles 133 

Managing Context in a Server 133 

Writing Procedures That Use a Context Handle 134 

Writing a Context Rundown Procedure 136 

A: MIDI and ACF Attributes Quick Reference 13 7 

B: RFC Runtime Routines Quick Reference 143 

C: The Arithmetic Application 149 

How to Build and Run the Application 149 

Application Files 150 

D: The Inventory Application 757 

How to Run the Application 158 

Application Files 159 

E: The Rfile Application 191 

How to Run the Application 191 

Application Files 192 

F: The Windows Phonebook Application 201 

How to Build and Run the Application 201 

Application Files 201 

Index . 223 



Table of Contents 



List of Figures 



1-1 Client-server model 2 

1-2 RFC mechanism 3 

1 ~3 Application development 3 

1-4 Arithmetic application: interface development 5 

1-5 Arithmetic application: client development 9 

1-6 Arithmetic application: server development 12 

1-7 Binding 13 

1-8 Binding information 13 

1-9 Server initializing 15 

1-10 Client finding a server 16 

1-11 Completing a remote procedure call 17 

1-12 Arithmetic application: complete development 25 

2-1 Producing an interface 41 

3-1 A comparison of binding management methods 47 

3-2 How a customized binding handle works 67 

3~3 Producing a client 75 

5-1 How the server runtime library handles a call 100 

5-2 Producing a server 118 

6-1 Server entries in the name service database 123 

6-2 A simple use of a name service database 125 



xii Microsoft RPC Programming Guide 

Conventions 

Throughout the book we use the following typographic conventions: 

Constant width 

indicates a language construct such as a MIDI keyword, a code example, 
system output, or user input. Words in constant width also represent 
application-specific variables and procedures. 

Constant Bold 

is used in examples to indicate text that is literally typed by the user. 

Bold introduces new terms or concepts. 

Italic in command syntax or examples indicates variables for which the user 
supplies a value. Italicized words in the text also represent system ele 
ments such as filenames and directory names, and user functions or RFC- 
specific routines. 

[] enclose attributes in interface definitions and Attribute Configuration Files 

(ACFs) and are part of the syntax. Note that this is different from the com 
mon convention in which brackets enclose optional items in format and 
syntax descriptions. 

C:\> represents system prompts. 

C:\SERVER> 

represents a server system prompt to distinguish it from a client system 
prompt. 

C : \CLIENT> 

represents a client system prompt to distinguish it from a server system 
prompt. 

Book Organization 

This book is divided into the following seven chapters and six appendices: 

Chapter 1, Overview of an RPC Application, shows a complete, simple RPC applica 
tion. 

Chapter 2, Using a Microsoft RPC Interface, shows how to read an RPC interface 
definition (a file ending in .idl}, which is a file that declares the remote proce 
dures of an interface. 

Chapter 3, How to Write Clients, discusses how to develop client programs for RPC 
interfaces. Topics include binding methods, finding servers, customizing binding 
handles, handling errors or exceptions, and compiling clients. 

Chapter 4, Pointers, Arrays, and Memory Usage, shows how pointers and arrays 
are defined in an interface and how to develop applications to use them. 



Preface xiii 

Chapter 5, How to Write a Server, discusses how to develop a server program for 
an RFC interface. Topics include initializing a server, writing remote procedures, 
and compiling servers. 

Chapter 6, Using a Name Service, describes a name service database and how to 
use it with distributed applications. 

Chapter 7, Context Handles, shows how to maintain a state (such as a file handle) 
on a specific server between remote procedure calls from a specific client. 

Appendix A, MIDI and ACF Attributes Quick Reference, shows all the attributes in 
the Microsoft Interface Definition Language (MIDL) and Attribute Configuration File 
(ACF). 

Appendix B, RFC Runtime Routines Quick Reference, shows all the RFC runtime 
routines organized into convenient categories. 

Appendix C, The Arithmetic Application, is a small application that shows the 
basics of remote procedure calls. 

Appendix D, The Inventory Application, is a somewhat richer application than that 
in Appendix C, showing different MIDL data types, how to use ACFs, and how to 
find servers by importing information from a name service database. 

Appendix E, The Rfile Application, shows how to use context handles and how to 
find servers using strings of network location information. 

Appendix F, The Windows Phonebook Application, offers a simple Windows-based 
client that uses RFC to get phone numbers from a database on the server. 

How to Use This Book 

If you are developing just a client for an existing RFC interface and server, read the 
following chapters first: 

Chapter 1, Overview of an RFC Application 

Chapter 2, Using a Microsoft RFC Interface 

Chapter 3, -How to Write Clients 

Read other chapters as needed to learn how to develop applications that use more 
features of interface definitions. 

If you are developing a network interface with accompanying server, read the fol 
lowing: 

Chapter 1, Overview of an RFC Application 

Chapter 2, Using a Microsoft RFC Interface 

Chapter 3, How to Write Clients 



xvi Microsoft RFC Programming Guide 

Enter choice !off 

Thank you for using CompuServe! 

Off at 06:59 EST 11 -Jan- 95 
Connect time = 0:06 

FTP 

To use FTP, you need a machine with direct access to the Internet. A sample ses 
sion is shown, with what you should type in boldface. 

% ftp ftp.uu.net 

Connected to ftp.uu.net. 

220 ftp.UU.NET FTP server (Version 6.34 Thu Oct 22 14:32:01 EOT 1992) read/. 

Name (ftp.uu.net:andyo) : anonymous 

331 Guest login ok, send e-mail address as password. 

Password: janetv@xyz.ccm (use your user name and host here) 

230 Guest login ok, access restrictions apply. 

ftp> cd /published/oreilly/nutshell/ms_rpc 

250 CWD command successful. 

ftp> binary (Very important 1 . You must specify binary transfer for compressed files.) 

200 Type set to I. 

ftp> prompt (Convenient, so you are not queried for every file transferred) 

Interactive mode off. 

ftp> mget * 

200 PORT command successful. 



ftp> quit 
221 Goodbye. 
% 

Each .Z archive contains all source code and configuration information required 
for building one example. Extract each example through a command like: 

% zcat arith.dec94.tar.Z I tar xf - 

System V systems require the following tar command instead: 

% zcat arith.dec94.tar.Z | tar xof - 

If zcat is not available on your system, use separate uncompress and tar com 
mands. 

The tar command creates a subdirectory that holds all the files from its archive. 
The README. dec94 file in this subdirectory describes the goals of the example 
and how to build and run it; the text is an ASCII version of the introductory mate 
rial from the corresponding appendix in this book. 



Preface xvn 

FTPMAIL 

FTPMAIL is a mail server available to anyone who can send electronic mail to and 
receive it from Internet sites. This includes any company or service provider that 
allows email connections to the Internet. Here s how you do it. 

You send mail to ftpmail@online.ora.com. In the message body, give the FTP com 
mands you want to run. The server will run anonymous FTP for you and mail the 
files back to you. To get a complete help file, send a message with no subject and 
the single word "help" in the body. The following is an example mail session that 
should get you the examples. This command sends you a listing of the files in the 
selected directory, and the requested example files. The listing is useful if there s a 
later version of the examples you re interested in. 

% mail ftpmail@online.ora. com 

Subject: 

reply-to janetv@xyz.com Where you want files mailed 

open 

cd /published/oreilly/nutshell/ms_rpc 

dir 

get REAEME.dec94 

mode binary 

uuencode (or btoa if you have it) 

get arith.dec94.tar.Z 

get inv.dec94.tar.Z 

get rfile.dec94.tar.Z 

get phnbk.dec94.tar.Z 

quit 

A signature at the end of the message is acceptable as long as it appears after 
"quit." 

All retrieved files will be split into 60KB chunks and mailed to you. You then 
remove the mail headers and concatenate them into one file, and then uudecode 
or atob it. Once you ve got the desired .Z files, follow the directions under FTP to 
extract the files from the archive. 

BITFTP 

BITFTP is a mail server for BITNET users. You send it electronic mail messages 
requesting files, and it sends the files back to you by electronic mail. BITFTP cur 
rently serves only users who send it mail from nodes that are directly on BITNET, 
EARN, or NetNorth. BITFTP is a public service of Princeton University. Here s how it 
works: 

To use BITFTP, send mail containing your ftp commands to BITFTP@PUCC. For a 
complete help file, send HELP as the message body. 



xviii Microsoft RFC Programming Guide 

The following is the message body you should send to BITFTP: 

FTP ftp.uu.net NETDATA 

USER anonymous 

PASS your Internet email address (not your bitnet address) 

CD /published/oreilly/nutshell/ms_rpc 

DIR 

GET README 

BINARY 

GET arith.dec94.tar.Z 

GET inv.dec94.tar.Z 

GET rfile.dec94.tar.Z 

GET phnbk.dec94.tar.Z 

QUIT 

Once you ve got the desired .Z files, follow the directions under FTP to extract the 
files from the archive. Since you are probably not on a UNIX system, you may 
need to get versions of uudecode, uncompress, atob, and tar for your system. 

Questions about BITFTP can be directed to Melinda Varian, MAINT@PUCC on BIT- 
NET. 



Acknowledgments 



This book can be traced back to the DCE documentation set put out by Digital 
Equipment Corporation. John Shirley, working with Steve Talbott and Andy Oram 
from O Reilly & Associates, wrote a DCE version of this book called Guide to Writ 
ing DCE Applications. Ward Rosenberry then took it over and thoroughly revised it 
to cover Microsoft RFC. While at first glance, it might seem that relatively little 
effort was required to write this new version, the work put into it was nevertheless 
considerable and required the cooperation and support of many individuals. 

First off, I want to thank my editor at O Reilly & Associates, Andy Oram, for his 
excellent advice and his persistence on this lengthy project. 

For supporting this project I want to thank folks at Digital Equipment Corporation, 
in particular Jeff Shrieshiem, Frank Willison, and Michelle Chambers for funding 
various portions of the project. Also at Digital Equipment corporation, other major 
contributors to this book include Neil Miranda, who converted several DCE appli 
cations to Microsoft RPC Version 1.0 for use in this book. Riaz Zolfonoon later 
modified these applications for use with Microsoft RPC Version 2.0. Riaz also pro 
vided helpful advice on numerous aspects of Microsoft RPC. 

Others at Digital who played central roles in developing the book include Jerry 
Harrow and Will Lees, who provided painstaking reviews of various drafts of sec 
tions of the book. Jim Teague provided a Microsoft RPC version of the phonebook 
application which was originally written for another O Reilly book titled Distribut 
ing Applications Across DCE and Windows NT. Jim is a co-author of that book. 
Larry Friedman, Dick Annicchiarico, Michael Blackstock, Rob Philpott, and Andy 
Ferris provided bits and pieces of technical advice along the way. I also want to 



Preface xix 

thank Ladan Pooroshani, Beth Benoit, and Brian Shimpf for their cooperation and 
support. 

Credit for logistical support goes to several folks at Digital including Gerry Fisher, 
Evelyn McKay, Lisa Cozins, and Madeline Cormier, all of whom made sure I had 
what I needed to get things done. 

Several people at Microsoft Corporation also deserve thanks for providing various 
inputs to the book. These people include Debbie Black, Dave Tanaguchi, and 
Craig Link (from Microsoft s Win32 SDK forum on CompuServe). 

Additional help and support for the DCE version of the book came from Tony 
Hinxman, Al Simons, David Magid, Margie Showman, Ken Ouellette, Mary Orcutt, 
Marll McDonald, Mark Heroux, Clem Cole, Marty Port, Ram Sudama, Diane Sher 
man, Susan Scott, David Strohmeyer, Karol Mclntyre, Wei Hu, Susan Hunziker, 
Vicki Janicki, Beth Martin, Dan Cobb, Lois Frampton, Steve Miller, Eric Jendrock, 
Gary Schmitt, Ellen Vliet, Judy Davies, Judy Egan, Collis Jackson, David Kenney, 
Suzanne Lipsky, Darrell Icenogle, Terry Tvrdik, Howard Mayberry, and John 
Shirley s wife, Linda McClary. 

Joe Scandora was very helpful on the Microsoft version of the book. 

Book design and production credits go to lots of the folks at O Reilly & Associates 
who artfully turned many pieces of a stark manuscript into a real book. Edie 
Freedman designed the cover. Jeff Robbins and Chris Reilley created the figures. 
Kismet McDonough, Eileen Kramer, and Clairemarie Fisher O Leary did the copy- 
editing and production management. Kiersten Nauman assisted with the produc 
tion work. Seth Maislin refined the index. 

Finally, I want to thank Frank Willison for giving me the opportunity to work on 
this book. 



Joint Venture 



This book was produced as a cooperative effort between Digital Equipment Cor 
poration and O Reilly & Associates. While we at O Reilly & Associates frequently 
work closely w r ith vendors of hardware and software, this book gave us an oppor 
tunity for much more extensive cooperation and mutual support than is custom 
ary. It is a model we like, and we believe the end result testifies to the value of 
sharing one s resources in this way. 




In this Chapter: 
A Simple Interfac 
A Simple Client 
A Minimal Server 
Producing the 
Application 
Running the 
Application 

Overview of an 



RFC Application 



A traditional application is a single program running on a single computer system, 
where a procedure and its caller execute in the same address space. In contrast, 
the client-server model for distributed applications embodies a client program and 
a server program, usually running on different systems of a network. The client 
makes a request to the server, which is usually a continuously running daemon 
process, and the server sends a response back to the client (see Figure 1-1). 

The remote procedure call (RFC) mechanism is the simplest way to implement 
client-server applications, because it keeps the details of network communications 
out of your application code. The idea is that each side behaves, as much as possi 
ble, the way it would within a traditional application: the programmer on the 
client side issues a call, and the programmer on the server side writes a procedure 
to carry out the desired function. To convey the illusion that you are working in a 
single address space, some hidden code has to handle all the networking. Many 
related issues are also involved, such as converting data between formats for dif 
ferent systems, and detecting communication errors. 

Figure 1-2 shows the relationship between your application code and the RFC 
mechanism during a remote procedure call. In client application code, a remote 
procedure call looks like a local procedure call, because it is actually a call to a 
client stub. (A stub is surrogate code that supports remote procedure calls. Later in 
this chapter we ll discuss how stubs are created and what they do.) The client stub 
communicates with the server stub using the RFC runtime library, which is a set of 
standard runtime routines that supports all Microsoft RFC applications. 

The server s RFC runtime library receives the remote procedure call and hands the 
client information to the server stub. The server stub invokes the remote proce 
dure in the server application. 



Microsoft RFC Programming Guide 




Request to server 



Network 



Server System 



Server 




Response from server 




Figu re 1-1. Client-server model 

When the server finishes executing the remote procedure, its stub communicates 
output to the client stub, again by using the RFC runtime library. Finally, the client 
stub returns to the client application code. 

Figure 1-3 shows the three phases required to develop a distributed application. 
An essential part of the RFC mechanism is an interface, which is a set of remote 
procedure declarations. Given the same interface, client and server development 
of an application can occur in parallel and on separate systems of the network. 

In this chapter we will create an entire RFC application from scratch. Naturally, 
we ll use every shortcut and simplification the system offers to accomplish this 
feat. When you are done with the chapter, you will know the place of all the 
major RFC features, and how an application is developed. 

You may not need to develop an entire application as shown in this chapter. If the 
interface and server already exist, your development may require only the client. 



Chapter 1: Overview of an RFC Application 



Client 

Pro 
Application 
Code 


Remote 
cedure Call 

t 


Stub Code 






RFC 
Runtime 
Library . 


id 





Input 




p^ 

Output 


Network 









Server Remote 


procedure 


Application , ""X 


Code i 


r i 


L 


Stub Code 






RFC 






Runtime 






Library . 


L_ 




1 





Figure 1-2. RFC mechanism 




Figure 1~3- Application development 

The arithmetic example in this chapter demonstrates a very simple one-client/one- 
server RFC application. Suppose a remote server system uses special hardware, 
such as an array processor. In our example, the client performs an arithmetic oper 
ation on arrays by calling a remote procedure that uses the array processor. The 
remote procedure executes on the server system, taking two arrays as arguments 
and adding together the elements of the arrays. The remote procedure returns the 
results to the client in a third array argument. Finally, the results of the remote pro 
cedure are displayed on the client system. 



Microsoft RFC Programming Guide 



The arithmetic example is deliberately limited to demonstrate the basics of a dis 
tributed application implemented with RFC. We describe each portion of the appli 
cation in this chapter, and Appendix C shows the complete code. The Preface tells 
you how to obtain source code online for this and other examples in the book. 



A Simple Interface 



When writing a local application, should you start by deciding exactly what func 
tions you ll call and what arguments they take? Well, if you were dividing the work 
among multiple programmers and needed to clarify the interfaces between their 
work, you probably would proceed that way. The same reasoning applies to a dis 
tributed program: the client and server are being developed separately. Since the 
boundary or interface between them is the procedure call itself, you have to spec 
ify its attributes at the start. 

So an interface consists of what the client and the server have to agree on; it con 
tains some identifying information and a few facts about the remote procedures. 
Each procedure declaration includes the name of the procedure, the data type of 
the value it returns (if any), and the order and data types of its parameters (if any). 
An interface definition contains a set of procedure declarations and data types. 

Just as programmers select functions from libraries, client application writers use 
interface definitions to determine how to call remote procedures. Server applica 
tion writers use interface definitions to determine the data type of the remote pro 
cedure s return value, and the number, order, and data types of the arguments. 
The interface definition is like a design document that ties the client and server 
application code together. It is a formal definition describing the set of procedures 
offered by the interface. 

You write the interface definition in Microsoft Interface Definition Language 

(MIDL). The MIDL closely resembles the declaration syntax and semantics of C, 
with the addition of attributes that allow information to be sent over a network. 

You may think that we have introduced an unnecessary level of complexity here, 
but you will see that keeping the salient features of a distributed application in 
one file the interface definition makes it easier to scale up development to mul 
tiple servers and many clients for those servers. 

Figure 1-4 shows the utilities used and the files produced when developing the 
arithmetic interface. The uuidgen utility generates a universal unique identifier 
(UUID) used in the interface definition to distinguish this interface from any other 
interface on the network. You use a text editor to write the rest of the interface 
definition, arith.idl. When the interface definition is complete, compile it with the 
MIDL compiler (midt) to generate stubs and a C header file that you use to 
develop the client and server programs. 



Chapter 1: Overview of an RFC Application 



Generate a universal 
unique identifier. 



Write an interface 
definition. 



uuidgen 



Text 
Editor 



arith.idl 




Compile the interface 
definition to generate 
the application header 
and stub files. 



f 
midl 




1 



arith.h 



J 




Figure 1-4. Arithmetic application: interface development 

Universal Unique Identifiers 

When you write a new interface, you must first generate a UUID with uuidgen. A 
UUID is simply a number that the uuidgen utility generates using time and net 
work address information so that no matter when or where it is generated, it is 
guaranteed to be unique. A UUID is like a fingerprint that uniquely identifies some 
thing such as an interface across all network configurations. 

An interface UUID is an excellent example of how you tie a client and server 
together through the MIDL file. When a client makes a remote procedure call, its 
UUID has to match that of the server. The RFC runtime library performs this check; 
this way you don t get unexpected results. 



Microsoft RFC Programming Guide 



Generating a UUID in an interface definition template 

To generate and display a UUID in a template for an interface definition, type the 
following command: 

C:\> uuidgen -i 
[ 

uuid(6AF85260-A3A4-10lA-BlAE-08002B2E5B76), 
version (1.0) 
] 
interface USTTERFACENAME 



In this example, the output appears at the terminal, but generally you save it in a 
file with the extension .idl. Replace the template name INTERFACENAME with a 
name you choose for the new interface. In the next section, we use a template like 
this to develop the arithmetic interface definition. 

The Interface Definition 

Now we are ready to write an interface definition. Here we put data type defini 
tions and procedure declarations that need to be shared between server and client. 
Later, the MIDI compiler creates the header file and stubs from the interface defini 
tion, for use in your application. 

The interface definition includes syntax elements called attributes, which specify 
features needed for distributed applications. Attributes convey information about 
the whole interface or items in the interface, including data types, arrays, pointers, 
structure members, union cases, procedures, and procedure parameters. For exam 
ple, the in attribute specifies an input parameter for a remote procedure. You can 
pick out attributes in the file because they re enclosed in square brackets. 

Example 1-1 shows a simple interface definition. The text consists of a header and 
body. The header contains a uuid attribute and the name assigned to the interface. 
The body specifies all procedures for the interface; it contains the procedure dec 
larations with their data types and constants. There is only one procedure declared 
in our example. It adds two input arrays and returns the results in a third array. 

Example 1-1: A Simple Interface Definition 

I* FILE NAME: arith.idl */ 

/* This Interface Definition Language file represents a basic arithmetic */ 
/* procedure that a remote procedure call application can use. */ 
[ 

uuid(6AF85260-A3A4-10lA-BLAE-08002B2E5B76) , /* Universal Unique ID O */ 
pointer_default(ref) /* default pointer type is reference @ */ 

] 

interface arith /* interface name is arith */ 

{ 

const unsigned short AKRAY_SIZE = 10; /* unsigned integer constant O */ 



Chapter 1: Overview of an RPC Application 



Example 1-1: A Simple Interface Definition (continued) 

typedef long long_array [ARRAY_SIZE] ; /* array type of long integers*/ 

void sum_arrays ( /* sum_arrays procedure does not return a value */ 
[in] long_array a, /* 1st parameter is passed in */ 

[in] long_array b, /* 2nd parameter is passed in */ 

[out] long_array c /* 3rd parameter is passed out */ 



O The uuid attribute specifies the interface UUID. The interface definition 
header for any distributed application requires a uuid attribute. 

RPC provides three types of pointer, offering varying levels of complexity and 
overhead. Here, the point er_default attribute specifies reference pointers as 
the default, because they offer the lowest overhead and are sufficient for our 
purposes. 

The last part of the interface definition header contains the keyword inter 
face followed by the name chosen for the interface (arith). 

O You can define constants for type definitions and application code. In this 
example, we define AKRAY_SIZE to set the bounds of arrays. 

You can define data types for use in other type definitions and procedure 
declarations. In this example, we define a data type that is an array of ten 
long integers. The indexes of arrays begin at zero, so the index values for this 
array range from zero to nine. 

The remainder of this interface definition is a procedure declaration. A proce 
dure of type void does not return a value. The in and out parameter 
attributes are necessary so the MIDL compiler knows in which direction the 
data need to be sent over the network. 

[in] : A value is passed in to the remote procedure when it is called from the 
client. 

[out] : A value is passed back from the server to the calling procedure on the 
client when the procedure returns. A parameter with the out directional 
attribute must be a pointer or array so that the parameter can be passed to the 
client stub by reference. Note that the MIDL compiler requires more complex 
pointer types to have [in, out] attributes. 

Stub and Header Generation Using the MIDL Compiler 

When the interface definition is complete, you compile it with the MIDL compiler, 
which creates the following: 

AC language header file that contains definitions needed by the stubs and 
your application code. You can now include the header file in client and 
server application code. 



Microsoft RFC Programming Guide 



A client stub file, which you will link with the client portion of the applica 
tion. During a remote procedure call, the client stub code is intermediate 
between your client application code and the RFC runtime library. 

A server stub file, which you will link with the server portion of the applica 
tion. During a remote procedure call, the server stub code is intermediate 
between your server application code and the RFC runtime library. 

Client and server auxiliary stub files linked with the client and server portions 
of the application. The auxiliary stub files convert complex data structures like 
pointers to and from a data stream suitable for transmission over the network. 

When you invoke the MIDL compiler, it generates the header file and intermediate 
C language stub files. Although we show a midl command by itself here, we rec 
ommend that you use a tool like nmake and a makefile to automate your entire 
build procedure. Such tools can hide differences between different hardware plat 
forms making your code more portable. They can also relieve you from the 
drudgery of typing in long command strings over and over. Later, we ll show a 
makefile for use in building client and server applications. 

To invoke the MIDL compiler and create the header and stub files for the arith 
metic interface, type the following: 

C:\> midl arith.idl 

In this example, we generate the header file and the C language stub files of the 
client and server in one operation. The MIDL compiler produces auxiliary stub files 
by default, but you may suppress their generation by using appropriate MIDL com 
piler options. 

If you develop the client and server on different systems, copies of the interface 
definition and the MIDL compiler must reside on both the client and server sys 
tems. To generate code correctly for different kinds of systems, compile the inter 
face definition for the client stub on the client system, and for the server stub on 
the server system. 



A Simple Client 



We ll start our coding with the client, because it s so simple. In fact, you will not 
be able to detect any difference between our client and a traditional, single-system 
program! That s one of the beauties about Microsoft RFC it hides most of the net 
working complexity from the client developer. 

To develop a client, you must be able to read and interpret the interface definition. 
To use all the capabilities of RFC, you must also know the RFC runtime routines. 
The client in our simple example, however, requires no RFC runtime routines. 

Figure 1-5 shows the files and utilities needed to produce a client. You write the 
client application code ( client. c) in C. Currently, Microsoft RFC provides libraries 
only for C. Remote procedure calls in a client look like local procedure calls. (The 



Chapter 1: Overview of an RFC Application 



server portion of the application implements the remote procedures themselves.) 
You must include the header file (arith.h) produced by the MIDI compiler, so that 
its type and constant definitions are available. 



Write the client 
application file. 



Text 
Editor 



Include the header file 
produced by interface 
compilation. 



Generate the client 
application object file and 
client stub object file. 



midl 



Create the executable client 
by linking the client 
application and stub object 
files with the Microsoft RFC 
library. 




Linker 



client 



J 



Figure 1-5. Arithmetic application: client development 

After compiling client. c and arith_c.c with the C compiler, you can create the exe 
cutable client by linking the client stub (arith_c.o) with the client object file and 
the Microsoft RFC library. Example 1-2 shows a simple client. 

Example 1-2: A Simple Client 

I* FILE NAME: client. c */ 

/* This is the client module of the arithmetic example. */ 

#include <stdio.h> 

#include <stdlib.h> 

#include "arith.h" /* header file created by MIDL compiler O */ 



Microsoft RFC Programming Guide 



Example 1-2: A Simple Client (continued) 

long_array a ={100,200,345,23,67,65,0,0,0,0}; 
long_array b ={4,0,2,3,1,7,5,9,6,8}; 

main () 
{ 

long_array result; 

int i; 

sum_arrays (a, b, result) ; /* A Remote Procedure Call */ 

puts ( "sums: ") ; 

forfi =0; i < ARRAY_SIZE; i++) 
printf ( "%ld\n" , result [i] ) ; 



/*** mi dl_user_al locate / midl_user_free ***/ 

void * RPC.__API 

midl_user_al locate /* Procedures called by the stubs */ 



size_t size; 

{ 

unsigned char * ptr; 
ptr = malloc ( size ) ; 
return ( (void *)ptr ) 



void RPC API 
midl_user_free 
( 

obj ect 
) 

void * object; 
{ 

free (object) ; 
} 

O The client code includes the header file produced by the MIDL compiler. 

The client calls the remote procedure sum_arrays using the two initialized 
arrays as input. It then displays the elements of the resulting array. 

Two programmer-supplied procedures midl_user_allocate and midl_user_ 
free may be called by client and server stubs for certain memory manage 
ment functions. Although this simple application does not require these rou 
tines, they are essential parts of many Microsoft RPC applications. Usually 
these are just wrapper routines for malloc and free. Chapter 4, Pointers, 
Arrays, and Memory Usage, contains more information about these proce 
dures. 



Chapter 1: Overview of an RFC Application 



The following section shows how to write the server for the arithmetic application. 

A Minimal Server 

Developing a server requires you to know the interface definition and some RFC 
runtime routines. You write two distinct portions of code: 

The actual remote procedures this portion is sometimes called the manager 

Code to initialize the server 

You make calls to the RFC runtime routines mainly in the server initialization, 
which prepares the server to listen for remote procedure calls. For our arithmetic 
application, server initialization is the only code that requires the use of runtime 
routines. 

Figure 1-6 shows the files and utilities needed to produce a server. You must write 
the remote procedures (manager.c) and server initialization code (seruer.c) in C. 
You need the header file (arith.h) produced by the MIDI compiler because it con 
tains definitions required by the remote procedures and runtime calls. 

After compiling the server application with the C compiler, you create the exe 
cutable server by linking the server stub (arith_s.o) with the server application 
object files and the Microsoft RFC library. 

Remote Procedure Implementation 

The programmer who writes a server must develop all procedures that are 
declared in the interface definition. Refer to the interface definition (aritb.idl) and 
the header file generated by the MIDI compilation (aritb.h) for the procedure s 
parameters and data types. Example 1-3 shows the code for the remote procedure 
of the arithmetic application. 

Example 1-3: A Remote Procedure Implementation 

I* FILE NAME: procedure. c */ 

/* Implementation of procedure defined in the arithmetic interface. */ 

ttinclude <stdio.h> 

#include "arith.h" /* header file produced by MIDL compiler O */ 

void sum_arrays(a, b, c) /* implementation of sum_arrays procedure ) */ 
long_array a; 
long_array b; 
long_array c; 
{ 
int i; 

for(i =0; i < ARRAY_SIZE; i++) 

c[i] = a[i] + b[i]; /* array elements are each added together */ 



12 



Microsoft RFC Programming Guide 



Write server application files 
containing initialization code 
and remote procedures. 



Include the header file 
produced by interface 
compilation. 



Text 
Editor 



Generate the server 
application object files and 
client stub object files. 



Create the executable 
server file by linking the 
server application and 
stub object files with the 
Microsoft RFC library. 



midl 




Figure 1-6. Arithmetic application: server development 

O The server code includes the header file produced by the MIDL compiler. 

The procedure definition matches its corresponding declaration in the inter 
face definition. 

) The procedure implementation is completed. 

So far, the client and server application code has been much like any other appli 
cation. In fact, you can compile and link the client and remote procedures, and 
run the resulting program as a local test. 



Chapter 1: Overview of an RFC Application 



13 



Before going on to write the server initialization code, we found it useful to dis 
cuss how the arithmetic application works in a distributed environment. This is the 
subject of the next section. 

A Distributed Application Environment 

When a client makes a remote procedure call, a binding relationship is established 
with a server (see Figure 1-7). Binding information is network communication and 
location information for a particular server. Conveniently, in the arithmetic applica 
tion, the client stub and the RFC runtime library automatically find the server for 
you during the remote procedure call. Figure 1-8 illustrates how binding informa 
tion acts like a set of keys to a series of gates in the path a remote procedure call 
takes toward execution. 



Client 



Binding 




Figure 1-7. Binding 



protocol *? server *? *? endpoint 
sequence * host k k 




Binding 




Figure 1-8. Binding information 



14 Microsoft RFC Programming Guide 

Binding information includes the following: 

1 . Protocol Sequence 

A protocol sequence is an RFC-specific name containing a combination of 
communication protocols that describe the network communication used 
between a client and server. For example, ncacn_ip_tcp represents the pro 
tocol sequence for a Network Computing Architecture connection-oriented 
protocol, over a network with the Internet Protocol and the Transmission 
Control Protocol for transport. 

2. Server Host 

The client needs to identify the server system. The server host is the name or 
network address of the host on which the server resides. 

3. Endpoint 

The client needs to identify a server process on the server host. An endpoint 
is a number representing a specific server process running on a system. 

To help clients find servers in a flexible and portable manner, Microsoft RFC pro 
vides a name service to store binding information. Name service is a general term 
for a database service that stores information for distributed applications that is, 
a service that offers the same information to applications running on different sys 
tems. Using the name service, a server can store binding information that a client 
on another system can retrieve later. The particular name service offered with 
Microsoft RFC is called the Locator. 

The RFC runtime library contains a general set of functions called name service 
independent (NSI) routines. Thus, to store binding information, your server calls 
an NSI routine. This routine internally communicates with the Locator to put infor 
mation into the database. NSI routines are a level of abstraction above the particu 
lar name service on a system, and thus can be used to access whatever name 
service your system uses. For instance, if you shared a network with DCE systems, 
you could configure your Microsoft RFC system to use the DCE Cell Directory Ser 
vice (CDS). 

Distributed applications do not require the name service database, but we recom 
mend that you use it. Alternatives to using the name service are to manage bind 
ing information directly in client and server code, or to create your own 
application-specific method of advertising and searching for servers. These alterna 
tives present more maintenance problems than if you use the name service rou 
tines. 

Figures 1-9, 1-10, and 1-11 show how the arithmetic application uses binding 
information, and how the remote procedure call completes. 

A server must make certain information available to clients. Figure 1-9 shows the 
typical steps needed each time a server starts executing. A server first registers the 
interface with the RFC runtime library, so that clients later know whether they are 



Chapter 1: Overview of an RFC Application 



15 



Client System 



Don 


am Controller 


^ 




Microsoft 
Locator 









Sem 


ir System 






\ 






Initialization 


n 


/- 

r 


/ 


s 


f- 


interface 

-Q Create 
binding 
information 

-Q Advertise 
server 
location 

-Q Register 
endpoints 

-0 Listen for 
calls 






\ 


RFC Runtime 
Library 

r 










r 


Endpoint Map 















Figure 1-9. Server initializing 

compatible with the server. The runtime library creates binding information to 
identify this server process. The server places the binding information in appropri 
ate databases so that clients can find it. The server places communication and host 
information in the name service database. The server also places process informa 
tion (endpoints) in a special database on the server system called the local end- 
point map, which is a database used to store endpoints for servers running on a 
given system. In the final initialization step, a server waits while listening for 
remote procedure calls from clients. 



16 



Microsoft RFC Programming Guide 



When the server has completed initialization, a client can find it by obtaining its 
binding information, as illustrated in Figure 1-10. A remote procedure call in the 
client application code transfers execution to the client stub. The client stub looks 
up the information in the name service database to find the server system. The RFC 
runtime library finds the server process endpoint by looking up the information in 
the server system s endpoint map. The RFC runtime library uses the binding infor 
mation to complete the binding of the client to the server. Chapter 3, How to Write 
Clients, discusses variations on how to obtain server binding information. 



Cli 


tat System 






( 

Application 
Code i 


) Make remote 
procedure call 

r 


Stub 


i 

i 

1 


Mind 
L server 
system 

r 


RFC 

Runtime 
Library 


( 

i 

\ 


)Fi 
^ P 

c 

r i 


nd server 
ocess 

) Bind to 

r server 
























Domain Control 


Microsoft 
Locator 



Server System 




Figure 1-10. Client finding a server 



Chapter 1: Overview of an RFC Application 



17 



As shown in Figure 1-11, the remote procedure executes after the client finds the 
server. The client stub puts arguments and other calling information into an inter 
nal RFC format that the runtime library transmits over the network. The server run 
time library receives the data and transfers it to the stub, which converts it back to 
a format the application can use. When the remote procedure completes, the con 
version process is reversed. The server stub puts the return arguments into the 
internal RFC format, and the server runtime library transmits the data back to the 
client over the network. The client runtime library receives the data and gives it to 
the client stub, which converts the data back for use by the application. 



Client System 




Application * 
Code 


L 


1 Stub 


) Prepare 
input 

C 

i 


\ Convert 
output 


RFC 
I Runtime 
1 Library 


i 
) Transmit 
input 

i 


> Receive 
, output 


\ 


r 













Sera 


r System 






Execute remote 
procedure 




t 


i 


1 
( 


r 
$ Prepare 
output 

( 

I 


) Convert 
i input 


i 
( 


r 

) Transmit 
output 


) Receive and 
L dispatch to 
stub 


1 


r 




Endpoint Map 













Domain Controller 



Microsoft 
Locator 



Figure 1-11. Completing a remote procedure call 



18 



Microsoft RFC Programming Guide 



Server Initialization 

As illustrated in Figure 1-9, a server must make certain information available to the 
RFC runtime library and clients before it can accept remote procedure calls. Exam 
ple 1-4 contains the server initialization code for the arithmetic application, illus 
trating the sequence of steps to initialize a typical RFC server. 

Example 1-4: A Minimal Server Initialization 



/* FILE NAME: server. c */ 
Mnclude <stdio.h> 
ttinclude "arith.h" 
# inc lude " status . h " 

main () 



/* header created by the MIDL compiler */ 
/* header with the CHECK_STATUS macro */ 



unsigned long status; 
rpc_binding_vector_t *binding_vector ; 
unsigned char *entry_name; 



/* error status */ 

/*set of binding handles */ 

/*entry name for name service */ 



status = 
RpcServerRegisterlf ( 

arith_vl_0_s_i f spec , 

NULL, 

NULL 



/* error status */ 

/* register interface with the RFC runtime O */ 
/* interface specification (arith.h) */ 



CHECK_STATUS( status, "Can t register interface", ABORT); 



status = 
RpcServerUseAllProtseqs ( 

RPC_C_PROTSEO_MAX_REQS_DEFAULT , 

NULL 



/* create binding information */ 

/* queue size for calls */ 

/* no security descriptor is used */ 



CHECK_STATUS( status, "Can t create binding information", ABORT); 

status = 

RpcServerlnqBindings ( /* obtain this server s binding information*/ 
&binding_vector 

CHECK_STATUS( status, "Can t get binding information", ABORT); 

entry_name = (unsigned char *)getenv("ARITHMETIC_SERVER_ENTRY" ) ,- 

status = 

RpcNsBindingExport ( /* export entry to name service database O */ 



RPC_C_NS_SYNTAX_DEFAULT , 
entry_name, 
arith_vl_0_s_i f spec , 
binding_vector , 
NULL 



/* syntax of the entry name 
/* entry name for name service 
/* interface specification (arith.h) 
/* the set of server binding handles 



CHECK_STATUS( status, "Can t export to name service database", ABORT); 



status = 
RpcEpRegister ( 

arith_vl_0_s_if spec , 



/* register endpoints in local endpoint map */ 
/* interface specification (arith.h) */ 



Chapter 1: Overview of an RFC Application 75? 

Example 1-4: A Minimal Server Initialization (continued) 

binding_vector, /* the set of server binding handles */ 

NULL, 

NULL 
); 
CHECK_STATUS( status, "Can t add address to the endpoint map", ABORT); 

status = 

RpcBindingVectorFree ( /* free set of server binding handles */ 

&binding_vector 
); 
CHECK_STATUS( status, "Can t free binding handles and vector", ABORT); 

puts ( "Listening for remote procedure calls. . . " ) ; 

status = 

RpcServerListen ( /* listen for remote calls */ 

1, /* minimum number of threads */ 

RPC_C_LISTEN_MAX_CALLS_DEFAULT, /* concurrent calls to server */ 
NULL /* continue listening until explicitly stopped */ 

); 

CHECK_STATUS( status, "rpc listen failed", ABORT); 
} 

/*** midl_user_allocate / midl_user_free ***/ 

void * _RPC_API 

midl_user_al locate /* Procedures called by the stubs */ 



size_t size; 
{ 

unsigned char * ptr; 
ptr = malloc ( size ) ; 
return ( (void *)ptr ) ; 



void __RPC_API 
midl_user_free 
( 

object 
) 

void * object; 
{ 

free (object) ; 
} 

O Register the interface. Register the interface with the RPC runtime library using 
the RpcServerRegisterlf routine. The arith_vl_0_s_ifspec variable is called 
an interface handle. It is produced by the MIDL compiler and refers to infor 
mation that applications need, such as the UUID. We describe the NULL argu 
ments in Chapter 5, How to Write a Server. 



20 Microsoft RFC Programming Guide 

The CHECK_STATUS macro is defined in the status. h header file for the appli 
cations in this book. It is used to interpret status codes from runtime calls. 
(See Example 3-12 in Chapter 3.) Figure 1-9, step 1 is now complete. 

@ Create binding information. To create binding information, you must choose 
one or more network protocol sequences. This application, like most, calls 
RpcServerUseAllProtseqs so that clients can use all available protocols. During 
this call, the RFC runtime library gathers together information about available 
protocols, your host, and endpoints to create binding information. The system 
allocates a buffer for each endpoint, to hold incoming call information. 
Microsoft RFC sets the buffer size when you use the RPC_C_PROTSEQ_ 
MAX_CALLS_DEFAULT argument. 

@ Obtain the binding information. When creating binding information, the RFC 
runtime library stores binding information for each protocol sequence. A bind 
ing handle is a reference in application code to the information for one possi 
ble binding. A set of server binding handles is called a binding vector. You 
must obtain this information through the RpcServerlnqBindings routine in 
order to pass the information to other runtime routines. Figure 1-9, step 2 is 
now complete. 

O Advertise the server location in the name service database. In this example, the 
server places (exports) all its binding information in the name service 
database using the RpcNsBindingExport runtime routine. 

The RPC_C_NS_SYNTAX_DEFAULT argument tells the routine how to interpret an 
entry name. (The current version of Microsoft RFC has only one syntax.) The 
entry_name is a string obtained in this example from an environment variable 
set by the user specifically for this application, ARITHMETIC_SERVER_ENTRY 
(discussed at the end of this chapter when the application is run). The inter 
face handle, arith_Server If HANDLE, associates interface information with 
the entry name in the name service database. The client later uses name ser 
vice routines to obtain binding information by comparing the interface infor 
mation in the name service database with information about its own interface. 
Figure 1-9, step 3 is now complete. 

Register the endpoints in the local endpoint map. The RFC runtime library 
assigns endpoints to the server as part of creating binding information. The 
RpcEpRegister runtime routine lets the endpoint map on the local host know 
that the process running at these endpoints is associated with this interface. 
Figure 1-9, step 4 is now complete. 

Free the set of binding handles. Memory for the binding handles was allocated 
with a call to the RpcServerlnqBindings routine. When you have finished 
passing binding information to the other routines, release the memory using 
the RpcBindingVectorFree routine. 



Chapter 1: Overview of an RFC Application 21 

O Listen for remote calls. Finally, the server must wait for calls to arrive. Each 
system has a default for the maximum number of calls that a server can 
accept at one time. Microsoft RFC sets this maximum default number when 
you use the RPC_C_LISTEN_MAX_CALLS_DEFAULT argument. Figure 1-9, step 5 is 
now complete. 

Two programmer-supplied procedures midl_user_allocate and midl_user_ 
free may be called by client and server stubs for certain memory manage 
ment functions. Although this simple application does not require these rou 
tines, they are essential parts of many Microsoft RFC applications. Usually 
these are just wrapper routines for malloc and free. Chapter 4 contains more 
information about these procedures. 

All of the server code is now complete. The compilation of the application is 
shown in the next section. 



Producing the Application 



So far we have written the interface definition, produced the stubs and header file 
from the interface definition with the MIDL compiler, and written the client and 
server portions of the application. To produce the application, compile and link 
the client and server separately, each on the system where you want its executable 
to run. 

Microsoft RFC Libraries 

Microsoft RFC-distributed applications must be linked with the Microsoft RFC 
libraries, which may vary depending on your system and vendor. This book uses 
the following libraries for a link on a Microsoft Windows NT system: 

rpcrt4 . lib 
rpcns4 . lib 
libont.lib 
kerne!32.1ib 

The rpcrt4.lib library provides Windows runtime library functions. The rpcns4.lib 
library provides -name service functions. The libcmt.lib library provides standard C 
library functions. The kernel32.lib library provides threads functions. 

The following sections assume that your client and server files are available to the 
respective client and server systems. 

Compile and Link the Client and Server Code 

Recall that Figures 1-5 and 1-6 show the utilities used and files produced when 
developing a client and a server. Here, we show a portion of a makefile we use 



22 Microsoft RFC Programming Guide 

with nmake to compile and link the client and server code. The order in which 
these commands execute is: 

O A midl command builds .c and .h files from the j d/file. 
The compiler generates object files for the client and server. 
@ The linker produces client and server executables. 
Example 1-5: A Makefile for Building a Client and Server 

# FILE NAME: Makefile 

# Makefile for the arithmetic application 
# 

# definitions for this makefile 
# 

APPL=arith 

NTRPCLIBS=rpcrt4 . lib rpcns4.1ib libcmt.lib keme!32.1ib 

# Include Windows NT macros # 
! include <ntwin32 .mak> 

# NT c flags 

cflags = -c -WO -Gz -D_X86_=1 -DWIN32 -DMT /nologo # @ 

# NT nmake inference rules 

c.obj: # 

$(cc) $(cdebug) $ (cflags) $(cvarsmt) $< 
$(cvtomf ) 

# 

# COMPLETE BUILD of the application 
# 

all: client.exe server.exe # Q 

# 

# CLIENT BUILD 
# 

client: client.exe 

client.exe: client. obj $ (APPL)_c.obj $ (APPL)_x.obj # 

$(link) $(linkdebug) $(conflags) -out: client.exe -map: client. map \ 

client. obj $ (APPL)_c.obj $ (APPL)_x.obj \ 

$(NTRPCLIBS) 

# 

# SERVER BUILD 
# 

server : server . exe 

server.exe: server. obj manager. obj $ (APPL)_s.obj $ (APPL)_x.obj # 
$(link) $(linkdebug) $(conflags) -out.-server.exe -map: server. map \ 

server. obj manager. obj $ (APPL)_s.obj $(APPL)_x.obj\ 

$ (NTRPCLIBS) 

# client and server sources # Q 
client. obj: client. c $(APPL).h 

manager . obj : manager . c $ (APPL) . h 
server . obj : server . c $ (APPL ) . h 



Chapter 1: Overview of an RFC Application 23 

Example 1-5: A Makefile for Building a Client and Server (continued) 

# client and server stubs # 
$(APPL)_c.obj: $(APPL)_c.c 

$(APPL)_x.obj: $(APPL)_x.c 
$(APPL)_s.obj : $(APPL)_s.C 

# generate stubs, auxiliary and header file from the MIDL file # 
$(APPL).h $(APPL)_c.c $(APPL)_x.c : $(APPL).idl 

midl $(APPL) .idl 

O ntwin32.mak contains machine specific-variables for portability. 

This line defines compiler options. 

The inference rules assign values to nmake options and flags. 

O This line builds client and server executables. 

Link the client object files with the runtime libraries defined by S(NTRPCLIBS) 
to produce the executable client application. 

Link the server object files with the runtime libraries defined by S(NTRPCLIBS) 
to produce the executable server application. 

Compile the client and server application C source files to produce applica 
tion object files. The server sources include both the remote procedure imple 
mentation and the server initialization, to create the server object files. 

Compile the client and server C language stub files to produce stub object 
files. 

Use the midl compiler to produce the client and server stub files and the 
header file. 



Running the Application 



We designed the arithmetic application for simplicity. One of our short-cuts was to 
let the client automatically find the server by using the name service to retrieve 
server binding information. The client stub obtains the binding information 
exported by the server to the name service database, and the client RFC runtime 
library completes the remote procedure call. 

To run the distributed arithmetic application, follow these steps: 

1. This server exports binding information to a name service database. Make 
sure a Microsoft Locator is running in your Windows NT domain. 

2. Execute the server. For this example, the application-specific environment 
variable, ARITHMETIC_SERVER_ENTRY, is set prior to running the server. This 
variable represents a name for the entry that this server uses when exporting 
the binding information to the name service database. The usual convention 
for entry names is to concatenate the interface and host names. We use an 



24 Microsoft RFC Programming Guide 

environment variable here because the name can vary depending on which 
host you use to invoke the server. If you do not supply a valid name, the 
binding information will not be placed in the name service database, and the 
program will fail. The prefix /.:/ (or alternatively / . . . /, represents the 
global portion of a name and is used for compatibility with OSF DCE naming 
conventions. For this example, assume that the server resides on the system 
moxie. 

C:\SERVER> set ARITHMETIC_SERVER_ENrRY=/. : /arithmetic_moxie 
C:\SERVER> server 

3. After the server is running, execute the client on the client system: 

C : \CLIENT> client 

sums: 

104 

200 

347 

26 

68 

72 

5 

9 

6 

8 

4. The server is still running and, for now, should be terminated by typing "C 
(Ctrl-C). In Chapter 5 we ll show a way to gracefully terminate your server so 
that it removes its endpoint information from the local endpoint map. 

Figure 1-12 summarizes the development of the arithmetic application. 



Chapter 1: Overview of an RFC Application 



25 



uuidgen 




Linker 



Linker 



Figure 1-12. Arithmetic application: complete development 




In this Chapter: 

Microsoft Interface 
Definition Language 
(MIDI) 

Using the MIDI 
Compiler 

Using an ACF to 
Customize Interface 

Usa s e Using a Microsoft 



RFC Interface 



As we discussed in Chapter 1, Overview of an RFC Application, the first step in cre 
ating a distributed application is to write an interface definition. This is also known 
as an IDL or MIDI file because it is written in the Microsoft Interface Definition 
Language and ends in the suffix .idl. This file contains definitions that the client 
and server share, and a list of all the procedures offered by the server. This chap 
ter explains what interface definitions need to contain. 

An interface definition is usually written by the person developing the server 
because it describes the procedures offered by that server. Client developers need 
to read and interpret the definition. All servers that support the interface must 
implement the remote procedures using the same data types and parameters. All 
clients must call the remote procedures consistently. 

A procedure declaration in an interface definition specifies the procedure name, 
the data type of the value it returns (if any), and the number, order, and data types 
of its parameters (if any). 

Interface definitions are compiled with the MIDI compiler (midl) to create the 
header and stub files. Use the header file with your application C code, and link 
the stub files with your application object code and the RFC runtime library to cre 
ate a distributed application. If you make a mistake when writing an interface defi 
nition, the MIDL compiler gives useful messages to help you correct what is wrong. 



27 



Microsoft RFC Programming Guide 



Microsoft Interface Definition Language 
(MIDI) 

Use the Microsoft Interface Definition Language (MIDL) to define the necessary 
data types and declare the remote procedures for an interface. Declarations in 
MIDL are similar to declarations in C,* with the addition of attributes. 

Attributes 

Interface definition attributes are special keywords that offer information to help 
distribute an application. They are enclosed in square brackets in the MIDL file. All 
of them facilitate network use in one way or another: 

Some attributes distinguish one interface from another on a network. They 
guarantee that a client finds the servers that implement the proper remote 
procedures. For example, the uuid attribute declares the UUID for the inter 
face. 

Some attributes explicitly describe data transmitted over a network. Some 
aspects of data in C that you take for granted must be described explicitly for 
a distributed application. For example, a union is a data structure that allows 
different data types in the same area of memory. Your application uses 
another variable to keep track of which data type is valid. In a distributed 
program, this additional variable must be specified in MIDL so it is transmitted 
with a union parameter. 

Some attributes make data transmission more efficient. In a local application, 
procedures have access to both parameters and global variables so that any 
amount of data can be accessed efficiently. In a distributed application, all 
data used by the client and the remote procedure must be passed as parame 
ters and transmitted over the network. Since most parameters are passed in 
only one direction, you use attributes to specify whether each parameter is 
used for input, output, or both. 

Tables A-l through A-8 in Appendix A, MIDL and ACF Attributes Quick Reference, 
show all MIDL attributes with brief descriptions of each. In this chapter, we discuss 
the MIDL attributes so you know how to write an interface definition. But to really 
understand how those attributes reflect your use of data in an application, you 
have to see them along with the application s C code and that will appear in later 
chapters. 



* MIDL is currently designed to work with C. However, MIDL has features such as boolean 
and byte data types, so that it will work in future versions for languages other than C. 



Chapter 2: Using a Microsoft RFC Interface 29 

Structure of an Interface Definition 

An interface definition includes some or all of the following: 

The interface header 

Interface header attributes 
Interface name 

The interface body 

Import statements 
Constant definitions 
Data type definitions 
Procedure declarations 

Interface Header Attributes 

Interface header attributes specify 7 RFC features that apply to an entire interface. 
One is the name that you have chosen, such as arith in the application shown in 
Chapter 1. But choosing a name is not enough, because someone could easily cre 
ate another application called arith, and a client would be confused about which 
to use. That is where the interface UUID and the version number come in. 

As we saw in Chapter 1, you generate a UUID through uuidgen. This distinguishes 
your arith even when someone else steals your name to create a different inter 
face. But the creators of DCE and Microsoft RFC recognized that an interface does 
not stay the same forever; you are likely to update it regularly. So they also allow 
for a version number in the interface header. A complete version number consists 
of a major and minor version number. For example, if a version number is 2.1, the 
major version is 2 and the minor version is 1 . 

During a remote procedure call, the following rules determine whether a client 
can use an interface that a server supports: 

The UUID of the client and server must match. 

The major version number of the client and server must match. 

The minor version number for the client must be less than or equal to the 
minor version number for the server. A client minor version number that is 
less than the server minor version number indicates an upwardly compatible 
change to the interface on the server. 

When you create new versions of an interface by adding new declarations and 
definitions, increase the minor version number. Any other changes to an interface 
require a major version number change, essentially creating a different interface. 



30 Microsoft RFC Programming Guide 

The Inventory Application 

The application we use in this chapter is a simple inventory: a product database is 
stored on the server system, and a client makes inquiries based on a part number. 
The complete application is shown in Appendix D, The Inventory Application. 

Example 2-1 shows the header in the interface definition of the inventory applica 
tion. 

Example 2- 1. Interface Header Attributes 

I* FILE NAME: inv.idl */ 

[ /* brackets enclose attributes O */ 

uuid(008B3C84-93A5-HC9-85BO-08002B147A61) ,/* universal unique identifier*/ 
version ( 1 . ), /* version of this interface*/ 

pointer_default (unique) /* pointer default O */ 

] interface inventory /* interface name */ 

{ 

/* The body of an interface definition consists of iitport statements, */ 

/* constant definitions, data type definitions, and procedure declarations. */ 



O Brackets enclose attributes in interface definitions. 

The uuid is a required attribute that uniquely identifies an interface. All 
copies of this interface definition contain the same UUID. 

The version is an optional attribute used to identify different versions of an 
interface. In this example the major version number is 1 and the minor ver 
sion number is 0. 

O The pointer_def ault is an optional attribute needed by some interface defi 
nitions so that pointer data is efficiently transmitted. 

The keyword interface and a name are required to identify the interface. 
The MIDI compiler uses this name to construct data structure names. Client 
and server code use these data structures to access information about the 
interface. 

Table A-l in Appendix A lists and describes all interface header attributes. 

Type Definitions, Data Attributes, and Constants 

In C, a data type can map to different sizes on different systems. For example, a 
long data type in C may be 16, 32, or 64 bits, depending on the system. The size 
of a MIDI data type, however, must be the same on all systems so that Microsoft 
applications can exchange data. Consequently, you might need to change data 
types if you port your application code platforms with differing data type sizes. 



Chapter 2: Ush^ a Microsoft KPC Interface 37 



7able2-l WLi Basic Data Types 



MIDL Data Type - zc 



bc/slear - - : 

byte 8 bits 

zhar 
void 

"."1. i "i * 



e - - r _ -. -. - -_ :=_- 32 bit* 

. . -_-;.-- 

ssall 

r- ~.v 
Fktttir^Pomt 

Ooat 32 bits 

:ic-J:le - : 



ImernatkiruJ Characters 

; 






..-- -.-_-_ - - .;.. . > 

MIDL_T>pe Notes 



byte Data is not automatics - " 



i"_i: - 



32 Microsoft RFC Programming Guide 

Table 2-2: Notes on MIDI Data Types (continued) 
MIDL_Type Notes 



void * Used with the context_handle attribute to define context 

handles. It refers to opaque data, the details of which are hid 
den from you. See Chapter 7, Context Handles . 

handie_t Data that denotes a binding handle. Chapter 3, How to Write 

Clients, describes how to use this data type to define binding 
handles in an interface definition. 

error_status_t Data that denotes an RFC communication status. 

wchar_t 1 6-bit unsigned data element. 

How do the MIDL data types help to distribute an application? The explanation lies 
in how the client and server stubs handle data that might need to change as it 
moves from one computer system to another. 

During a remote procedure call, the client stub prepares input parameters for 
transmission, and the server stub converts the data for use by the server applica 
tion. When the remote procedure completes execution on the server system, the 
server stub prepares the output parameters for transmission and the client stub 
converts the data for the client application. 

Marshalling is the process during a remote procedure call that prepares data for 
transmission across the network. Marshalling converts data into a byte-stream for 
mat and packages it for transmission using a Network Data Representation (NDR). 
NDR allows successful data sharing between systems with different data formats. It 
handles differences like big-endian versus little-endian (byte order), ASCII charac 
ters versus EBCDIC characters, and other incompatibilities. 

Data transmitted across the network undergoes a process called unmarshalling. If 
the data format of sender and receiver is different, the receiver s stub converts the 
data to the correct format for that system, and passes the data to the application. 

Example 2-2 shows a constant and two type definitions for the inventory interface. 

Example 2-2: MIDL Type Definitions 

[ 

/* The header of an interface definition consists of interface header */ 

/* attributes and the name of the interface. */ 



] interface inventory 
{ 

const long MAX_STRING =30; /* constant for string size O */ 

typedef long part_num; /* inventory part number */ 

typedef [string] char part_name[MAX_STRING+l] ; /* name of part*/ 



Chapter 2: Using a Microsoft RFC Interface 33 

Example 2-2: MIDI Type Definitions (continued) 



/* The remainder of the interface definition consists of other data */ 
/* type definitions and the procedure declarations. */ 

} 

O Use the keyword const followed by a data type to declare a constant to use 
in type definitions and application code. 

@ Use the keyword typedef followed by a data type to define a new data type. 

A data type is not sufficient to completely describe some kinds of data. 
Attributes provide the necessary extra information. In this example, the 
string attribute enclosed in brackets applies to the character array 
part_name, so that it becomes a null-terminated string. 

Table A-4, in Appendix A, lists and describes all the data type attributes. So far we 
have seen only basic MIDI data types. Now we will explain how to construct more 
complex data types in an interface definition. 

Pointers 

In a distributed application, a pointer does not provide the same convenience and 
efficiency that it does in a local application because there is stub overhead such as 
memory allocation, copying, and transmitting all the data the pointer refers to. 
MIDL contains three kinds of pointers to balance efficiency with more complete 
pointer capabilities. 

A full pointer has all of the capabilities associated with pointers. They can be null 
or point to existing data. They can contain cycles or loops and they can be aliased 
to another pointer in the argument list. The full pointer attribute is the default 
pointer type. You can override this setting by using the pointer_default attribute. 

A unique pointer can be null or point to existing data. But unique pointers cannot 
contain cycles or loops and they cannot be aliased to another pointer in the argu 
ment list. In Microsoft Extension mode, the unique pointer attribute is the default 
pointer type assigned to pointers that are not parameters. You can override this 
setting using the pointer_default attribute. 

A reference pointer is a simpler pointer that refers to existing data. A reference 
pointer has a performance advantage, but limited capabilities compared to a 
unique pointer. No new memory can be allocated for the client during the remote 
procedure call, so memory for the data must exist in the client before the call is 
made. 

The unique attribute represents a unique pointer and the ref attribute represents 
a reference pointer. Chapter 4, Pointers, Arrays, and Memory Usage, discusses how 
to use pointers. 



Microsoft RFC Programming Guide 



Arrays 

Array index values begin at in MIDI, as in C. For example, the array arr[10] 
defined in an interface definition has elements arr[0] , arr[l] , . . . , arr[9] 
when you use it in the client or server code. 

Arrays are expensive to transmit, so MIDI provides some sophisticated ways to 
keep down the amount of data actually sent over the network. Here are the kinds 
of arrays provided: 

fixed array A fixed array has constant index values for its dimensions. 

This is like a standard C array. 

varying array A varying array has a maximum size determined at compile 

time, just like a fixed array. But it also has subset bounds 
represented by variables. Only the portion of the array you 
need is transmitted in a remote procedure call. 

conformant array The size of a conformant array is represented by a dimen 

sion variable so that the actual size is determined when the 
application is running. 

Chapter 4 discusses arrays in more detail. 

Strings 

In C code it is convenient to use strings to manipulate character data. C library 
routines, such as strcpy, recognize a null character as the end of a string in the 
character array. In MIDL, all characters in an array are transmitted, including null 
characters. Therefore, you must explicitly define strings with the string attribute, 
so that only the characters up to a null character are transmitted. Example 2-3 
shows some string definitions. 

Example 2~3: Defining Strings in MIDL 

const long MAX_STRING = 30; /* a constant for string size */ 



typedef [string] char part_name[MAX_STRING+l] ; /* name of part O */ 
typedef [string, unique] char *paragraph; /* description of part */ 

To specify a string, apply the string attribute to a character or byte array. In 
this example, the string size is 31 in order to accommodate the terminating 
null byte, but the maximum string length is 30. The data type of the array ele 
ments must be a char or byte, or defined with a type definition that resolves 
to a char or byte. The data type can also be a structure whose fields all 
resolve to a char or byte. 

This example specifies a conformant string by applying the string attribute 
to a pointer to a char or byte data type. 



Chapter 2: Using a Microsoft RFC Interface 35 

A conformant string has the maximum length allocated in the application code. 
You can also specify a conformant string using array syntax. For example, the fol 
lowing is another way to define the conformant string paragraph: 

typedef [string] char paragraph^]; 

When you use a conformant string as an input parameter to a remote procedure, 
the amount of data that is transmitted is determined from the current string length. 
If the string parameter is both input and output, however, apply an array attribute 
size_is or max_is to the string so the length can increase when the remote pro 
cedure completes. Chapter 4 discusses array attributes in greater detail. 

Enumerated types 

MIDL provides an enumerated type, just as modern versions of the C language do. 
The idea is to provide a set of symbolic names to make source code more self- 
documenting. These names are associated by the compiler to a set of integer val 
ues, but the values usually have no more significance than to distinguish one 
name from another. In Example 2-4, the keyword enum, followed by a list of iden 
tifiers, maps the identifiers to consecutive integers starting with 0. For this exam 
ple, we use enumeration to specify more than one kind of measurement unit for 
parts in the inventory. Some parts are counted as whole items, while other parts 
are measured by weight. 

Example 2-4: Defining an Enumerated Type in MIDL 

typedef enum { 

ITEM, GRAM, KILOGRAM 
} part_units; /* units of measurement */ 

Microsoft RFC extensions allow you to attach specific integer values to identifiers 
in an enumeration. In Example 2-5, flight numbers are attached to specific flights 
in an air traffic application. 

Example 2-5: Attaching Specific Integer Values to Enumerators 

typedef enum { 

BOS-CHI=716, BOS-DEN=432, BOS-SFO510 /* flight numbers */ 

} flights; 

Structures 

You define structures in MIDL the same way you do in C. In Example 2-6 the 
struct keyword is followed by a list of typed members that define a structure. For 
this example, two structures are shown. The structure part_price contains a 
units-of-measurement member and a price-per-unit member. The part_units data 
type is an enumerated type. The structure part_record represents all the data for 
a particular part number. As in C, any user-defined types such as part_num must 
be defined before they are used. 



36 



Microsoft RFC Programming Guide 



Example 2-6: Defining Structures in MIDI 

typedef struct part_price { 

part_units units; 

double per_unit ; 
} part_price; 



/* price of part */ 



typedef struct part_record { 

part_num number; 

part_name name ; 

paragraph description; 

part_price price; 

part_quantity quantity; 

par t_l i st subpart s ; 
} part_record; 



/* data for each part */ 



Discriminated unions 

In C a union is a data structure that stores different types and sizes of data in the 
same area of memory. For example, this union stores a long integer or a double 
precision floating-point number: 

typedef union { 

long int number; 

double weight ; 
} quant ity_t; 

To keep track of what type is stored in the union, the application must use a dis 
criminator variable that is separate from the union data structure. This creates a 
special requirement for a distributed application. If a remote procedure call 
includes a union parameter, the remote procedure has no way of knowing which 
member of the union is valid unless it receives the discriminator along with the 
union. 

In MIDL, a discriminated union includes a discriminator as part of the data struc 
ture itself, so that the currently valid data type is transmitted with the union. When 
you define a discriminated union, it looks like a combination of a C union and a 
switch statement. The switch defines the discriminator, and each case of the switch 
defines a valid data type and member name for the union. 

Example 2-7 shows how to define a discriminated union. 
Example 2- 7: Defining a Discriminated Union in MIDL 



typedef enum { 

ITEM, GRAM, KILOGRAM 
} part_units; 



/* units of measurement */ 



Chapter 2: Using a Microsoft RFC Interface 37 

Example 2- 7: Defining a Discriminated Union in MIDI (continued) 
O 

typedef union switch (part_units units) total { /* quantity of part */ 

case ITEM: long int number; 

case GRAM: O 

case KILOGRAM: double weight; 
} part_quantity; 

O You begin the definition of a discriminated union data type with the key 
words typedef union. 

Use the keyword switch to specify the data type and name of the discrimina 
tor variable, units. The data type part_units is a previously defined enu 
merated type. A discriminator can be Boolean, character, integer, or an 
enumerated type. 

Define the name of the union, total, prior to listing the union cases. 

O Use the keyword case followed by a value to specify the data type and name 
of each union member. The case value is the same type as the discriminator 
variable. In this example, a union defines the quantity of a part in an inven 
tory. Some parts are counted as whole items while other parts are weighed. 
This union offers a choice between defining the quantity as a long integer or 
as a double precision floating-point number. The union case GRAM has the 
same data type and name as the case KILOGRAM. 

The name of the new data type is part_quantity, which you use in applica 
tion code to allocate a discriminated union variable. 

In application code, the discriminated union is a C structure. The MIDI compiler 
generates a C structure with the discriminator as one member and a C union as 
another member. Example 2-8 shows the structure in the generated header file for 
the corresponding discriminated union in Example 2-7. 

Example 2-8: A Discriminated Union Generated by the MIDI Compiler 

typedef struct { 
part_units units; 
union { 

/* case(s) :.0 */ 
idl_long_int number; 
/* case(s) : 1, 2 */ 
idl_long_float weight; 
} total; 
} part_quantity; 

You must set the union discriminator in the application code to control which 
union case is valid at any time in the application. Example 2-9 shows how you can 
use the discriminated union in application code. 



Microsoft RFC Programming Guide 



Example 2-9: Using a Discriminated Union in Application Code 

part_record part; /* structure for all data about a part */ O 



result = order_part (part. number" "& (part. quantity ), account); 
if (result > 0) { 

if (part. quantity. units == ITEM) 

printf ("ordered %ld items \n" , part. quantity. total. number ); O 
else if (part. quantity. units == GRAM) 

printf ("ordered %10.2f grams\n", part. quantity. total. weight ); 
else if (part. quantity. units == KILOGRAM) 

printf ("ordered %10.2f kilos\n", part. quantity. total. weight ); 
} 

O In the inventory application the part_quantity discriminated union is a 
member of the part_record structure shown in Example 2-5. 

The part. quantity structure member is the discriminated union. In this 
example, you request a quantity of a part to order, and the remote procedure 
returns the actual quantity ordered. 

The part. quantity. units member is the discriminator for the union. 

O The part. quantity. total member is the union, which contains number and 
weight cases. 

If you omit the union name (total in Example 2-7), then the MIDL compiler gen 
erates the name tagged_union for you. You can access the structure members in 
application code as follows: 

part. quantity. units = ITEM; 

part. quantity. tagged_union . number = 1; 

Procedure Declarations and Parameter Attributes 

At the heart of an interface definition are the procedures that a server offers. The 
inventory application contains several remote procedures; you can find them in 
the interface definition in Appendix D. 

Each parameter of a remote procedure is declared with its own attributes. The 
most important ones are the directional attributes in and out. 

In the C language parameters of procedure calls are passed by value, which means 
a copy of each parameter is supplied to the called procedure. The variable passed 
is an input-only parameter because any manipulation of the procedure s copy of 
the variable does not alter the original variable. For a variable to be a parameter, a 
pointer to the variable is passed. 

With a remote procedure call, we must be concerned with whether a parameter is 
input, output, or both. It is more efficient if the RFC runtime library can transmit 
data only in the relevant direction. The attributes in and out are used in an 



Chapter 2: Using a Microsoft RFC Interface 



39 



interface definition to distinguish data transmission direction for a parameter. All 
parameters must have at least one directional attribute. An output parameter must 
be a pointer or an array, as it must be in C. 

Complex pointer types must have both directional attributes (in and out). This 
enables the client and server stubs to coordinate duplication of the unique or full 
pointer in the server s address space. 

Example 2-10 shows procedure declarations and some associated parameter 
attributes. 

Example 2-10: Procedure Declarations and Parameter Attributes 



] interface inventory 

{ 

/* The beginning of the interface definition body usually contains */ 

/* constant and type definitions (and sometimes import declarations).*/ 



y****************** ****** Procedure Declarations ************************/ 
boolean is_part_available ( /* return true if in inventory O */ 
[in] part_num number /* input part number */ 



void whatis_part_name ( 

[in] part_num number, 
[in, out] part_name name 



/* get part name from inventory 
/* input part number */ 
/* output part name */ 



paragraph get_part_description( 
[in] part_num number 



/* return a pointer to a string ) */ 



void what is_part_pr ice ( 

[in] part_num number, 
[out] part_price *price 



/* get part price from inventory */ 



void whatis_part_quantity ( /* get part quantity from inventory */ 
[in] part_num number, 
[out] part_quantity *quantity 



void whatare_subparts ( 

[in] part_num number, 
[out] part_list **subparts 



/* get list of subpart numbers */ 
/* structure containing the array O */ 



/* Order part from inventory with part number, quantity desired, and 

/* account number. If inventory does not have enough, output lesser */ 

/* quantity ordered. Return values: l=ordered OK, 

/* -l=invalid part, -2=invalid quantity, -3=invalid account. 



40 Microsoft RFC Programming Guide 

Example 2-10: Procedure Declarations and Parameter Attributes (continued) 

long order_part ( /* order part from inventory, return OK or error code */ 

[in] part_num number, 

[in, out] part_quantity *quantity, /* quantity ordered */ 

[ in] account_num account 
); 
} /* end of interface definition */ 

O As in C, a MIDL procedure can return a value. In this example, the 
is_part_available procedure returns a Boolean value of idl_true if the part 
number is available in the inventory. 

Procedures defined with the void type do not return a value. Input parame 
ters have the in directional attribute and output parameters have the out 
directional attribute. Here, Microsoft RFC is treating this pointer to the array 
element as a unique pointer because the pointer_default was set to unique 
(see Example 2-1). MIDL does not allow unique or full pointers to have only 
the [out] directional attribute because the client and server stubs need to 
coordinate the establishment of complex pointers in the server address space. 
Consequently, the directional attribute is set to [in, out] . As in C, arrays and 
strings are implicitly passed by reference, so the string name does not need a 
pointer operator. 

Some procedures return a data structure or a pointer to a data structure. In 
this example, the data type paragraph has been defined in the interface defi 
nition as a char * type. It is a full pointer to a string representing the descrip 
tion of the part. This remote procedure allocates new memory on the client 
side. 

O Output parameters require pointers to pointers when new memory is allo 
cated. Pointers to pointers are discussed in Chapter 4. 

Parameters that are changed by the remote procedure call use both in and 
out. In this example, a part is ordered with the part number, the quantity, and 
an account number. If the input quantity units are wrong or the quantity 
requested is more than the inventory can supply, the remote procedure 
changes the quantity on output. 

Table A-7 in Appendix A shows all parameter attributes and Table A-8 shows all 
procedure attributes. 



Using the MIDL Compiler 



The MIDL compiler generates the header and stub files needed to incorporate the 
interface in a client or server. The input for a MIDL compilation is an interface defi 
nition file, ending in .idl. Figure 2-1 shows the utilities used and files produced 
during interface production. 



Chapter 2: Using a Microsoft RFC Interface 



41 



An attribute configuration file (ACF) is an optional file, ending in .acf. It contains 
information that changes how the MIDI compiler interprets the interface definition. 
We ll look at the ACF file later in this chapter. 



Generate a universal 
unique identifier. 

Write an interface definition 
and an optional attribute 
configuration file (ACF). 



uuidgen 



Text 
Editor 



f 



app/.idl 



JL 

appl.atf 




Compile the interface 
definition to generate the 
application header, stub, 
and auxiliary files. 



T 

midl 




Figure 2-1. Producing an interface 

Depending on which compiler options you use, the MIDL compiler produces the C 
language client stub, server stub, or both sets of stub files. The stub file names 
contain the _c suffix for clients and the _s suffix for servers. By default, the MIDL 
compiler also produces the header file (ending in .h) which will be used by both 
the client and server: 

The MIDL compiler produces auxiliary files automatically when certain features are 
used. Auxiliary file names contain the _x suffix for clients and the _y suffix for 
servers. 

Auxiliary files contain special routines required for certain complex data types, 
such as unique pointers, to prepare the data for transmission. You have to link the 
auxiliary object files with your application when these data types are used. The 
routines are placed in auxiliary files rather than in the stub, so that you can use 
the data types in other interface definitions without linking in the entire stub. 



42 Microsoft RFC Programming Guide 

Generating Client Files 

To generate the interface header file and client stub file for the inventory interface, 
type the following command: 

C:\> invntry> midl inv.idl /server none /I explicit /out explicit 

Here is an explanation of the options: 

/server none This option suppresses the generation of stub none and auxiliary 
files for the server. 

/I explicit The /I option causes the MIDL compiler to use the additional 

directory when it searches for files. For one of the clients of the 
inventory application an ACF in the explicit directory is needed. 

/out explicit This option places the output files in the chosen directory, 
explicit. 

Generating Server Files 

To generate the interface header file and server stub file for the inventory inter 
face, type the following command: 

C:\> invntry> midl inventory. idl /client none 

Here is an explanation. 

/client none This option suppresses the generation of stub and auxiliary files 
for the client. 

Using an ACF to Customize Interface Usage 

You can control some aspects of RFC on the client side without affecting the 
server. The opposite is also true. These aspects should not be in the interface defi 
nition because we do not want to force them on all clients and servers. A client or 
server developer can use an optional attribute configuration file (ACF) to modify 
the way the MIDL compiler creates stubs without changing the way the stubs inter 
act across the network. This assures that all copies of an interface behave the same 
when clients and servers interact. 

The most significant effect an ACF has on your application code can be the addi 
tion of parameters to remote procedure calls not declared in the interface defini 
tion. For example, the explicit_handle attribute adds a binding handle as the 
first parameter to some or all procedures. Also, the comm_status and 
fault_status attributes can add status parameters to the end of a procedure s 
parameter list. See Table A-9 in Appendix A for a complete list of ACF attributes. 

If you develop both clients and servers for an interface, you can use different ACFs 
(or no ACF) for the client and server. Since this can cause differences between the 



Chapter 2: Using a Microsoft RFC Interface 43 

header files generated for the client and server, it is good development practice to 
separate the client and server output when using ACFs. 

You do not specify an ACF when you compile an interface; instead, the MIDL com 
piler automatically uses an ACF if one is available in the search directories. The 
name of an ACF must match the name of the MIDL file it is associated with. The file 
extension must be .acf. 

An ACF is useful for a number of situations: selecting binding methods, controlling 
errors, excluding procedures, and controlling marshalling. 

Selecting a Binding Method 

As will be explained in Chapter 3, three different binding methods exist. You can 
choose how much to let the stub do for you and how much to control binding 
within your own code. 

The auto_handle ACF attribute selects the automatic binding method which 
causes the client stub to automatically select the server for your client. In the arith 
metic application in Chapter 1, for instance, any server found by the client stub 
would be sufficient. An additional advantage offered by automatic binding is error 
recovery: if server communication is disrupted, the client stub can sometimes find 
another server, transparent to the application code. 

The irtplicit_handle ACF attribute selects the implicit binding method which 
allows you to select a specific server for your remote procedure calls. For exam 
ple, if many inventory servers representing different warehouses are available on 
the network, you may want your client to select a specific one. 

The explicit_handle ACF attribute selects the explicit binding method which lets 
you select a specific server for each remote procedure call. For example, if your 
client needs data from many servers simultaneously, you need a way to control 
which remote procedure call uses which server. 

Example 2-11 is an ACF used by the MIDL compiler to produce the header and 
stub files for the implicit client example of the inventory application. 

Example 2-11: An Attribute Configuration File (ACF) 

/* FILE NAME: inv.acf (implicit version)*/ 

/* This Attribute Configuration File is used in conjunction with the */ 

/* associated MIDL file (inv.idl) when the MIDL conpiler is invoked. */ 

[ 

implicit_handle (handle_t global_binding_h) /* implicit binding method O */ 

] 

interface inv /* The interface name must match the MIDL file. */ 



O The irtplicit_handle attribute applies to the entire interface. A global bind 
ing handle of type handle_t is established in the client stub to refer to bind 
ing information a client uses to find a server. 



44 Microsoft RFC Programming Guide 

@ The interface name (inv) must match the interface name in the corresponding 
MIDI file. 

Controlling Errors and Exceptions 

An exception is a software state or condition that forces the application to go out 
side its normal flow of control. Such an event may be produced by hardware 
(such as memory access violations) or software (such as array subscript range 
checking). Microsoft RFC applications cause communication and server errors to be 
raised as exceptions. Unless you design your program to handle the exceptions, 
the program will exit. 

An ACF can save you the trouble of writing extra layers of exception handling 
code. 

The coirm_status and fault_status attributes apply to procedure parameters or 
procedure return results of the type error_status_t. If this attribute is present 
and you ve added a variable of the data type error_status_t to the argument list 
of your remote procedure call communication and server errors are communicated 
to the client as values in the named parameter rather than raised as exceptions. 
Error codes for comm_status and fault_status are different to allow correct 
interpretation of the error codes. Chapter 3 discusses error and exception control 
in greater detail. 

Excluding Unused Procedures 

The code and nocode ACF attributes allow you to define which procedures the 
client stub supports. For example, if a client uses only four out of twenty remote 
procedures declared in the interface, the client stub code does not need the over 
head of the other procedures. However, all the procedures of an interface defini 
tion must be implemented by the server. 





In this Chapter: 
Binding 
Steps in Finding 
Servers 

Customizing a 
Binding Handle 
Authentication 
Error Parameters or 

^^0^ How to Write Clients 

Compiling and 
Linking Clients 



In this chapter we discuss how to develop client programs for Microsoft RFC inter 
faces. It is a good idea to read Chapter 1, Overview of an RFC Application, for a 
complete overview of a distributed application, and Chapter 2, Using a Microsoft 
RFC Interface , to familiarize yourself with features of interface definitions. 

We discuss client development before server development because you may 
develop a client for an existing interface and server. We describe server develop 
ment in Chapter 5, How to Write a Server. The code for all applications is shown in 
Appendices C through F. 



Binding 



The first question that probably comes to mind when you begin to develop a 
client is: How does a remote procedure call find the server it needs? Essentially, 
the client must create a binding, as described in Chapter 1, and load it with infor 
mation that lets the RFC runtime library find the server. 

Binding information mainly includes a communication protocol sequence, a host 
name or address, and a server process address on the host (endpoint). If you are 
familiar with using named pipes, these are similar to a protocol family, a computer 
name, and a pipe name. 

Binding information can be obtained automatically and be completely invisible to 
your client application code. To the other extreme, you can obtain binding infor 
mation by calling RFC runtime routines and using a binding handle as a parameter 
in a remote procedure call. The level of control you need depends on the needs 
of your client program. 

A binding handle is the data structure that manages binding in applications. The 
handle is a reference (pointer) to information for one possible binding. 



45 



46 Microsoft RFC Programming Guide 

Microsoft RFC supplies the Locator as a simple and convenient name service 
database to store names and locations of network services. Servers use RFC run 
time routines to store binding information in the name service database. Clients 
use other RFC runtime routines to retrieve binding information from the name ser 
vice database and create binding handles for remote procedure calls. 

A server s binding information can also be stored in an application-specific 
database or supplied to client programs by some other means, for example, as 
arguments when the client is invoked. If your client would not benefit from a 
name service (or your client system does not have a running name service), you 
can use RFC runtime routines in applications to convert strings of binding informa 
tion to binding handles used by remote procedure calls. 

Implementing a Binding Method 

For each remote procedure call, the binding handle is managed in one of the fol 
lowing ways. 

Automatic method 

The client stub automatically manages bindings after the application calls a remote 
procedure. The client stub obtains binding information from a name service 
database and passes the binding handle to the RFC runtime library. If the connec 
tion is disrupted, new binding information can sometimes be automatically 
obtained and the call is tried again. 

Implicit method 

A binding handle is held in a global area of the client stub. After the application 
calls a remote procedure, the stub passes the binding handle to the RFC runtime 
library. You write application code to obtain the binding information and set the 
global binding handle with RFC runtime routine calls. 

Explicit method 

An individual remote procedure call in the application passes a binding handle 
explicitly as its first parameter. You write application code to obtain the binding 
information and set the binding handle with RFC runtime routine calls. 

Figure 3-1 shows a comparison of binding methods in relation to the client code. 
For each method, the top portion of the box represents the client application code 
you write. The bottom portion of each box represents the client stub code that the 
MIDI compiler generates. The shading represents the portion of the client where 
binding handles are managed. For any given client instance, different methods 
may be employed for different remote procedure calls. For example, one remote 
procedure call can use the automatic method and another remote procedure call 
can use the explicit method. 



Chapter 3: How to Write Clients 



47 



Client 
Application 
Code 

Client 
Stub 


Automatic 




Implicit 




Explicit 




Call remote 
procedure 


Obtain binding 
information and 
set global binding 
handle 

Call remote 
procedure 


Obtain binding 
information and 
set binding handle 

Call remote procedure 
and pass binding 
handle to stub as first 
parameter 


Binding information 
obtained and binding 
handle set 

Binding handle 
passed to RPC 
runtime library 




Binding handle 
defined as global 
variable 

Binding handle 
passed to RPC 
runtime library 




Binding handle 
passed to RPC 
runtime library 




I 1 = Code that manages binding handle 



Figure 3~1- A comparison of binding management methods 

The automatic and implicit methods apply to an entire interface. If you use either 
the automatic or implicit method for an interface, you can also use the explicit 
method for some or all remote procedure calls to that interface. The explicit 
method takes precedence over the automatic and implicit methods because the 
binding handle is visible as the first parameter in the procedure. 

If a client uses more than one interface, you can use the automatic method for all 
remote procedure calls to one interface and the implicit method for all remote pro 
cedure calls to the other interface. However, a client cannot use the automatic and 
implicit methods simultaneously, for remote procedure calls to the same interface. 

The implicit and explicit methods require that your application code obtain bind 
ing information and manage the binding handles. Binding handles need to be 
obtained and managed in the client application code under the following circum 
stances: 

The client uses a specific server. 

The client needs to set authentication and authorization information for spe 
cific binding handles. 

The server has more than one implementation of the same remote procedure. 
An application uses object UUIDs to distinguish between different remote pro 
cedure implementations. 



48 Microsoft RFC Programming Guide 

Use an attribute configuration file (ACF) to establish a binding method with the 
attributes auto_handle, irrplicit_handle, or explicit_handle. 

A context handle is a special remote procedure parameter defined in an interface 
definition with the context_handle attribute. Applications use a context handle in 
a sequence of remote procedure calls to refer to a context (state) on a specific 
server. We mention context handles briefly here with binding methods because 
they carry with them binding information and thus can act as a binding handle for 
remote procedure calls. When the context handle is active, it carries with it the 
binding information necessary to find the same server as it did before, and the 
server maintains the context for that particular client. (Chapter 7, Context Handles, 
describes context handle use.) 

Deciding on binding methods 

Automatic binding does the most work for you, so MIDL makes it the default. 
Another binding method is chosen in the following situations: 

The first parameter of a procedure declaration is a binding handle (in that 
case, the binding method has to be explicit) 

The procedure declaration has an input context handle 

An ACF establishes a different binding method 

You can force explicit binding when you re sure that you want every client to 
specify a server when calling a particular procedure. Make a binding handle the 
procedure s first parameter in the MIDL file. A client cannot take away a parameter 
declared in the interface definition, so this remote procedure cannot use either the 
automatic or implicit methods. For the same reason, a context handle forces the 
client to use explicit binding. 

The next decision is whether to use the automatic or implicit method for other 
procedures. If you re satisfied with using any valid server for your remote proce 
dure calls any server that exports the interface described in your MIDL file the 
automatic method should be adequate. In particular, the automatic method works 
fine if the network is relatively small. However, you have no control over which 
server you get, so applications that use servers scattered over a wide area may be 
inefficient. If most of your remote procedure calls need to use a specific server, 
the implicit method is appropriate. 

Suppose you have determined that individual remote procedure calls need control 
over which server each uses. For example, if you use a print server application, 
one call may request a server near you to print a file. Your next call may request a 
server in a different location to print another copy for your department manager. If 
you have determined that you need this kind of binding control for individual 
remote procedure calls, use the explicit method. 

The explicit method is also necessary for clients that make multi-threaded remote 
procedure calls. For example, a commodity trade application may request a 



Chapter 3: How to Write Clients 49 

commodity price with remote procedure calls to many locations at the same time. 
This server selection control also lets you balance network load in your applica 
tion. All the clients in this book are single-threaded. 

Automatic Binding Management 

The automatic binding management method is the simplest because you don t 
have to manipulate the binding handle in your interface definition, ACF, or appli 
cation code. The binding handle and the complexity of its management is hidden 
from you in the client stub and the RFC runtime library. If you lose a server con 
nection, the automatic method will try to rebind for you. With this method there is 
a relatively short learning curve to get a distributed application running. 

Many applications do not require that you control binding, so it is easier to let the 
underlying RFC mechanism find a server. The server is selected from a set of 
servers that support the interface. If the particular server makes no difference, use 
the automatic method. For example, for a mathematics interface, the first server 
that supports it is probably sufficient. 

The automatic method is demonstrated in the arithmetic application and shown in 
detail in Chapter 1. For this chapter, however, we use one of the clients for the 
inventory application, so you can compare client development between different 
methods for the same application. The application is shown in detail in Appendix 
D, The Inventory Application . 

Interface development for automatic binding 

There are no special requirements in the interface for automatic binding. If you 
wish, you can use the auto_handle attribute in an ACF for documentation. 

Client development for automatic binding 

The client requires you to: 

1. Include the MIDL-generated header file with the #include compiler directive 
in the client application code: 

/* FILE NAME: client. C */ 

/****** Client of the inventory application ******/ 

#include <stdio.h> 

#include <stdlib.h> 

#include "inv.h" /* header file created by the MIDL conpiler */ 



50 Microsoft RFC Programming Guide 

2. Link the client application object code with the client stub, client stub auxil 
iary file (if available), and the following Microsoft RFC libraries: 

rpcrt4.1ib 
rpcns4 . lib 
libcmt.lib 
kerne!32.1ib 

The client system must have access to a Microsoft Locator name service database 
on the network. Your system administrator can tell you if you have access to a 
name service. 

The remote procedure call looks just like a local procedure call. The procedure 
returns a Boolean value of true if the part number is in the inventory or false if 
it is not: 

case a : if (is_part_avail able (part .number) ) /* Remote Procedure Call */ 

puts ( " available : Yes " ) ; 
else 

puts ( "available : No" ) ; 
break; 

If your client uses the automatic method for an interface, you can override it for 
specific procedures by using a binding handle as the first parameter in the call. 

See Chapter 6, Using a Name Service, for more information on the name service. 

Server development for automatic binding 

For clients to use the automatic method, a server must advertise binding informa 
tion to a name service entry with the RpcNsBindingExport runtime routine in the 
server initialization code. 

Implicit Binding Management 

Implicit binding gives you the control of binding management in the client appli 
cation without a visible binding handle parameter in a remote procedure call. Use 
the implicit method for applications that need the same server for all or most 
remote procedure calls of an interface. An ACF defines the binding handle, and the 
MIDI compiler generates it as a client-global variable in the client stub. The client 
application code sets the binding handle before any remote procedure calls. Dur 
ing a remote procedure call, the client stub uses the global binding handle to com 
plete the call to the RFC runtime library. 

In this part of the chapter, we ll develop a client for the inventory application that 
uses the implicit method. The rationale is that, in this application, you may need to 
choose a specific server to access the right data base. Once a server is found, the 
rest of the remote procedure calls can use the same one. 



Chapter j; How to Write Clients 57 

Interface development for implicit binding 

Use the irtplicit_handle attribute in an ACF to declare the global binding handle 
for the client, as shown in Example 3-1. When you compile the interface definition 
with the ACF available, a global binding handle is defined in the client stub. The 
stub uses the handle every time the client calls a remote procedure for this inter 
face. 

Example 3-1: An ACF for the Implicit Binding Method 

I* FILE NAME: inv_i.acf (implicit version)*/ 

/* This Attribute Configuration File is used in conjunction with the */ 

/* associated MIDL file (inv.idl) when the MIDL compiler is invoked. */ 

[ 

implicit_handle(handle_t global_binding_h) /* irrplicit binding method */ 

] 

interface inv /* The interface name must match the MIDL file. */ 



The handle_t type is a MIDL data type that is used to define a binding handle 
named global_binding_h. 

Client development for implicit binding 

The client code includes the MIDL-generated header file, obtains a binding handle, 
and assigns the binding handle to the global binding handle. (See Example 3-2.) 

Example 3-2: A Client with the Implicit Binding Method 

I* FILE NAME: client. c */ 

/***** Client of the inventory application with implicit method *****/ 

#include <stdio.h> 

#include <stdlib.h> 

ttinclude "inv.h" /* header file created by the MIDL compiler O */ 



do_import_binding ( " inventory_" , &global_binding_h) ; /* seek matching */ 

/* uuid @ */ 

status = RpcBindingReset (global_binding_h) ; /* remove endpoint */ 
CHECK_STATUS { status, "Can t reset binding handle", ABORT); 



case a : if ( is_part_available( part. number )) /* */ 

puts ( "available: Yes" ) ; 
else 

puts ( "available: No" ) ; 
break; 

The MIDL-generated header file must be included with the ^include compiler 
directive. 



52 Microsoft RFC Programming Guide 

The client must obtain binding information and assign its handle to the global 
binding handle. The binding information can be obtained from the name ser 
vice database as in this example, or it can be constructed from strings of bind 
ing information. The do_import_binding procedure is developed later in this 
chapter. 

@ The Microsoft Locator included with our pre-release version of Microsoft RFC 
unexpectedly returned server endpoints. Sometimes the endpoints were stale 
(left from previous server instances) and caused communication problems. We 
used the RpcBindingReset function which removes the endpoint, forcing the 
client to look in the server host s endpoint map for a fresh endpoint. Your 
application should not need this function if the Locator does not return server 
endpoints. 

O A remote procedure call looks just like a local procedure call. 

If your client uses the implicit method for an interface, you can override it for spe 
cific procedures by including a binding handle as the first parameter of the proce 
dures in the MIDI file. 

Server development for implicit binding 

Although there are no special requirements in server development, a server must 
export to a name service database if the clients use a name service to find servers. 
The server for the inventory application exports binding information. 

Explicit Binding Management 

Explicit binding manages each remote procedure call separately. The first parame 
ter of the remote procedure call is a binding handle. Use the explicit method 
when your application needs to make remote procedure calls to more than one 
server. This method is the most visible in an application because a binding handle 
is passed as the first parameter of the remote procedure. You completely control 
the binding management in the client application code. 

If the procedure declaration in the interface definition file has a binding handle as 
the first parameter, you must use the explicit method. If the procedure declaration 
does not have a binding handle parameter, you can add one by using an ACF. In 
this case, after you compile the interface definition, the remote procedure is 
defined in the header file with an additional binding handle as the first parameter. 

We ll use another client from the inventory application to demonstrate the explicit 
method. 



Chapter j; How to Write Clients 53 

Interface development for explicit binding 

An interface definition or an ACF uses the handle_t data type to define binding 
handle parameters. Application code uses the rpc_binding_handle_t data type 
to represent and manipulate binding information.* 

Suppose we want to use the explicit method for a remote procedure that has no 
explicit binding handle as the first parameter. We use an ACF with the 
explicit_handle attribute, making the MIDL compiler add a binding handle as 
the first parameter. At the time this book went to press, we were not able to com 
pletely test the use of the explicit_handle attribute. Keep in mind that the final 
release of Microsoft RFC Version 2.0 might differ slightly from the behavior 
described here. 

The is_part_available procedure is defined in the interface as follows: 

boolean is_part_available ( /* return true if in inventory */ 

[in] part_num number /* input part number */ 
); 

An ACF that adds a binding handle parameter is shown in Example 3-3. 

Example 3~3: Adding Binding Handles with an ACF 

I* FILE NAME: inv.acf (explicit version)*/ 

/* This Attribute Configuration File is used in conjunction with the */ 

/* associated MIDL file (inv.idl) when the MIDL compiler is invoked.*/ 

[ 

explicit_handle /* explicit binding method */ 

] 

interface inventory /* The interface name must match the MIDL file. */ 



When the MIDL compiler uses this ACF, all procedure declarations in the header 
file have a binding handle of type handle_t added as the first parameter. If you 
use the explicit_handle attribute this way, none of the remote procedure calls 
to this interface can use the automatic or implicit method for this client instance. 

You can also use the explicit_handle attribute on a specific procedure in the 
ACF to add a binding handle as the first parameter. For example, this ACF associ 
ates a binding handle parameter only with the is_part_available procedure: 

interface inventory 
{ 

[explicit_handle] is_part_available() ; 
} 

Example 3-4 defines a binding handle explicitly in the interface definition. Other 
clients cannot use the automatic or implicit methods of binding for the procedure. 



* The handle_t and rpc_binding_handle_t data types are equivalent. The handle_t data 
type exists for compatibility with earlier RFC versions. The rpc_binding_handle_t data 
type exists for consistency in data type naming for the RFC runtime routines. 



54 Microsoft RFC Programming Guide 

(The is_part_available procedure is not declared this way for the inventory inter 
face.) 

Example 3~4: Defining a Binding Handle in the Interface Definition 

boolean is_part_available( /* return true if in inventory */ 

[in] handle_t binding_h, /* explicit, binding handle */ 

[in] part_num number /* input part number */ 
); 

Later in this chapter we ll show how to create an application-specific, customized 
binding handle in the interface definition through the handle attribute. 

Client development for explicit binding 

Before making the remote procedure call, the client must obtain binding informa 
tion and set the binding handle. The methods of obtaining binding information for 
the explicit method are almost the same as for the implicit method. For the explicit 
method, you use a specific binding handle instead of assigning the binding infor 
mation to the implicit global binding handle. 

Example 3- 5: A Client with the Explicit Binding Method 

/* FILE NAME: client. c */ 

/***** Client of the inventory application with explicit method *********/ 

#include <stdio.h> 

ftinclude <stdlib.h> 

Mnclude "inv.h" /* header file created by the MIDL compiler O */ 



rpc_binding_handle_t binding_h; /* declare a binding handle */ 



do_import_binding ("/.:/ inventory", &binding_h) ; /* find server */ 
status = RpcBindingReset (global_binding_h) ; /* remove endpoint O */ 
CHECK_STATUS ( status, "Can t reset binding handle", ABORT); 



case a : if (is_part_available(binding_h, part. number )) /* */ 

puts ( " available : Yes " ) ; 
else 

puts ( "available : No" ) ; 
break; 

O Include the MIDL-generated header file with the tfinclude compiler directive. 
Declare binding handles of type rpc_binding_handle_t in the application. 

The client must obtain binding information from the name service database, 
or it can be constructed from strings of binding information. Example 3-7 



Chapter 3: How to Write Clients 55 

shows how the application-specific procedure do_inport_binding uses the 
name service database. 

The RpcBindingReset function fixes a problem we discovered with the 
Microsoft Locator. See Example 3-2 for more information. 

The first parameter is the binding handle. 

Server development for explicit binding 

To use explicit binding, the ACF must include the explicit_binding attribute or 
the interface definition must have a binding handle parameter for the remote pro 
cedure. Servers use the binding handle parameter to obtain client binding informa 
tion for use in authentication and authorization. 

Example 3-6 shows how to include a binding handle parameter in a server remote 
procedure. 

Example 3~6: Manager Procedures with the Explicit Binding Method 

I* FILE NAME: manager. c */ 

/** Implementation of the remote procedures for the inventory application. **/ 

#include <stdio.h> 

# include <stdlib.h> 

# inc lude " inv . h " 

boolean is_part_available(binding_h, number) /* */ 

handle_t binding_h; /* */ 

part_num number; 
{ 

part_record *part; /* a pointer to a part record */ 

int found; 

found = read_part_record( number, &part) ; 
if (found) 

return (TRUE) ; 
else 

return (FALSE); 
} 

O Include a binding handle as the first parameter in a remote procedure imple 
mentation.. 

Declare a binding handle as a parameter. 



Steps in Finding Servers 



Recall that Figure 1-10, in Chapter 1, shows one way to find a server. In this figure, 
the client stub and the RFC runtime library handle all binding management outside 
of the application code. The client stub automatically finds the server system bind 
ing information in a name service database. The binding handle is set and passed 
to the RFC runtime library, which finds the server process binding information 



56 Microsoft RFC Programming Guide 

(endpoint) in the server system s endpoint map. The RFC runtime library uses the 
complete binding information to bind to the server. 

The key to finding a server is to obtain a protocol sequence, a server host name or 
address, and an endpoint. A binding handle for the remote procedure call is set to 
point to this binding information. 

The following discussion is a generalization of what happens during the server 
finding process. It includes the choices you (or the RFC runtime library) have 
about where to obtain the necessary binding information. Where these steps are 
executed (client application, client stub, or RFC runtime library) depends on the 
kind of binding handle and binding method used. 

Finding a Protocol Sequence 

A client and server can communicate over a network if they both use the same 
network communication protocols. A protocol sequence is found in one of two 
ways: 

The preferred method is to use a name service database to import or look up 
both a host address and protocol sequence at the same time. To set the bind 
ing handle, use the RFC runtime routines that begin with RpcNsBindinglmport 
or RpcNsBindingLookup . If your application uses the automatic method, the 
client stub does this for you. 

The other method is to use a protocol sequence string obtained from your 
application or from a call to the RpcNetivorklnqProtseqs routine. Use the RFC 
runtime routines RpcStringBindingCompose and RpcBindingFromString- 
Binding to set the binding handle. 

A protocol sequence is a character string containing three items that correspond to 
options for network communications protocols. RFC represents each valid combi 
nation of these protocols as a protocol sequence. The protocol sequence consists 
of a string of the options separated by underscores. The only current, valid option 
combinations are shown in Table 3-1. 

Table 3~1: Valid Protocol Sequences 

Protocol Sequence Common Name Description 



ncacn_ip_tcp Connection Network Computing Architecture con- 

protocol nection over an Internet Protocol with a 



sequence 



ncadg_ip_udp Datagram 

protocol 
sequence 



Transmission Control Protocol for trans 
port. 

Network Computing Architecture data 
gram over an Internet Protocol with a 
User Datagram Protocol for transport. 



Chapter 3- How to Write Clients 



57 



Table 3~1: Valid Protocol Sequences (continued) 
Protocol Sequence Common Name Description 



ncacn_dnet_nsp 


DECnet (TM) 


Network Computing Architecture con 






nection over DECnet (TM). The underly 






ing software that implements DECnet 






must be purchased separately. 


ncacn_nb_tcp 


NetBIOS over 


Network Computing Architecture con 




TCP/IP 


nection using NetBIOS over TCP/IP. 


ncacn_nb_nb 


NetBIOS over 


Network Computing Architecture con 




NetBEUI 


nection using NetBIOS over the NetBEUI 






transport. 


ncacn_np 


Named pipes 


Network Computing Architecture con 






nection using named pipes. 


ncacn_spx 


Connection- 


Network Computing Architecture con 




oriented SPX 


nection using SPX. 


ncalrpc 


Local Windows 


Network Computing Architecture using 




NT communi 


local communications only. 




cations 





The three protocols of a protocol sequence are for RPC communication, network 
host addressing, and network transport. 

1. The RPC protocol for communications has two options: 

Network Computing Architecture connection-oriented protocol (ncacn) 

Network Computing Architecture local interprocess communication 
(ncalrpc) 

The network address format used as part of the binding information has three 
options: 

the Internet protocol (ip) 

the DECnet (TM) protocol (dnet) 

the NetBIOS (Artisoft s Network Basic Input Output System) protocol (nb) 

2. The transport protocol for communications has five options: 

Transmission control protocol (tcp) 

Network services protocol (nsp) 

NetBEUI (NetBIOS Extended User Interface) 



5S Microsoft RFC Programming Guide 

Named pipes (np) 

spx (sequenced packet exchange) 

Most servers should use all available protocol sequences so clients using the inter 
face will have every opportunity to find and use a server. 

In general, your choice of protocols on the client side should not be a big con 
cern. If most traffic on your network is TCP/IP, use that protocol. When several 
protocols are available to clients, you can usually just pick the one most com 
monly used for communications in your network. 

If you want to be selective, here are some guidelines to help you choose a suit 
able protocol. 

Use TCP/IP or DECnet when clients and servers must communicate over a 
wide-area network (WAN). These protocols have long timeouts that can han 
dle the network delays inherent in WANs. Use TCP/IP when debugging your 
client during remote procedure calls. Otherwise, the process could time out 
when the debugger stops it. Clients can control timeouts using the RPC run 
time routines RpcMgmtSetComTimeout and RpcMgmtlnqComTimeout . 

Use UDP/IP when clients need to bind to many servers. That s because this 
protocol has relatively low overhead. If a remote procedure broadcasts its call 
to all hosts on a local network, it must use UDP/IP. The broadcast attribute on 
the procedure declaration in the interface definition declares the broadcast 
capability. 

Use NetBIOS over NetBEUI for local area network (LAN) connections because 
it can be faster than TCP/IP or DECnet in some networks. Avoid using NetBIOS 
over NetBEUI when clients and servers are separated by network routers. 

Use named pipes (ncacn_np) in local area networks when you want to rely 
on the security built in to named pipes. Named pipes extra security overhead 
can slow down remote procedure calls, so use it only when you need secu 
rity. 

Use Local Windows NT RPC Communication (ncalrpc) when clients and 
servers reside on the same system, because it s generally faster than other pro 
tocols for interprocess communication. 

Finding a Server Host 

You can find a server host name or network address in two different ways: 

Use a name service database to import or look up a host address and at the 
same time get a protocol sequence. Use the RPC runtime routines that begin 
with RpcNsBindinglmport or RpcNsBindingLookup to set the binding handle. 
If your application uses the automatic method, the client stub does this for 
you. 



Chapter 3: How to Write Clients 59 

Use a host name or host network address string obtained from your applica 
tion. Use the RFC runtime routines called RpcStringBindingCompose and Rpc- 
BindingFromStringBinding to set the binding handle. 

A partially bound binding handle is one that contains a protocol sequence and 
server host, but not an endpoint. This handle is what you get from the Microsoft 
Locator. It means you have identified the server s system, but not the server pro 
cess on that system. The binding to a server cannot complete until an endpoint is 
found. 

When a partially bound binding handle is passed to the RFC runtime library, an 
endpoint is automatically obtained for you from the interface or the endpoint map 
on the server s system. 

Finding an Endpoint 

A binding handle that has an endpoint as part of its binding information is called a 
fully bound binding handle. Endpoints can be well-known or dynamic. A well- 
known endpoint is a pre-assigned system address that a server process uses every 
time it runs. Usually a well-known endpoint is assigned by the authority responsi 
ble for a transport protocol. A dynamic endpoint is a system address of a server 
process that is requested and assigned by the RFC runtime library when a server is 
initialized. Most applications should use dynamic endpoints to avoid the network 
management needed for well-known endpoints. 

You can use your application code to obtain an endpoint, but it is best to let the 
RFC runtime library find an endpoint for you. An endpoint is found in one of four 
ways: 

If the binding information obtained during an import or lookup of the proto 
col sequence and host in the name service database includes an endpoint, the 
binding handle is fully bound in one step. The name service database can be 
used to store well-known endpoints. But dynamic endpoints are never stored 
in the name service database because their temporary nature requires signifi 
cant management of the database, which degrades name service performance. 

A well-known endpoint is found that was established in the interface defini 
tion with the endpoint attribute. The RFC runtime library (or your applica 
tion) finds the endpoint from an interface-specific data structure. 

An endpoint is found from the endpoint map on the server system. These 
endpoints can be well-known or dynamic. The RFC runtime library first looks 
for an endpoint from the interface specification. If one is not found, the RFC 
runtime library looks in the server s endpoint map. When an endpoint is 
found, the binding to the server process completes. To obtain an endpoint 
from a server s endpoint map, use the RpcEpResolveBinding routine or rou 
tines beginning with RpcMgmtEpEltlnq in your application. 



60 Microsoft RFC Programming Guide 

You can use a string from your application that represents an endpoint, and 
then you can use the RFC runtime routines RpcStringBindingCompose and 
RpcBindingFromStringBinding to set the binding handle. These endpoints 
can be well-known or dynamic. 

Interpreting Binding Information 

This section reveals what goes on in the do_import_binding procedure shown ear 
lier in the chapter. When you use implicit or explicit binding, you need to interpret 
the binding information. To take a simple case, suppose you want to use a server 
on a particular host this means you need to extract the host from the binding 
handles you get from CDS and isolate the host name in each handle. 

Binding handles refer to the following binding information: 

Object UUID 

Protocol sequence 

Network address or host name 

Endpoint 

Network options 

Object UUIDs are part of an advanced topic not discussed in this book. Network 
options are specific to a protocol sequence. 

Example 3-7 shows how to use RFC runtime routines to interpret binding informa 
tion. You use these routines in either a server or client. The do_interpret_binding 
procedure is called in the do_import_binding procedure. 

Example 3~ 7: Interpreting Binding Information 

/* FILE NAME: intbind.c */ 

/* Interpret binding information and return the protocol sequence. */ 

ftinclude <stdio.h> 

# include <rpc.h> 

include " status . h " 

void do_interpret_binding( binding, protocol_seq) 

rpc_binding_handle_t binding; /* binding handle to interpret */ 

char *protocol_seq; /* protocol sequence to obtain */ 

{ 

unsigned long status; /* error status */ 

unsigned char *string_binding; /* string of binding info. */ 

unsigned char *protseq; /* binding conponent of interest */ 

status = 

RpcBindingToStringBinding ( /* convert binding information to string O */ 
binding, /* the binding handle to convert */ 

&string_binding /* the string of binding data */ 

); 

CHECK_STATUS( status, "Can t get string binding :", RESUME); 



Chapter 3: How to Write Clients 



Example 3~ 7: Interpreting Binding Information (continued) 

status = 

RpcStringBindingParse ( /* get components of string binding*/ 

string_binding, /* the string of binding data */ 

NULL, /* an object UUID string is not obtained */ 

&protseq, /* a protocol sequence string IS obtained */ 

NULL, /* a network address string is not obtained */ 

NULL, /* an endpoint string is not obtained */ 

NULL /* a network options string is not obtained */ 

); 

CHECK_STATUS( status, "Can t parse string binding:", RESUME); 

strcpy (protocol_seq, (char *)protseq) ; 

/* free all strings allocated by other runtime routines */ 

status = RpcStringFree(&string_binding) ; 

status = RpcStringFreef&protseq ) ; 

return; 

O The RpcBindingToStringBinding routine converts binding information to its 
string representation. The binding handle is passed in and the string holding 
the binding information is allocated. 

The RpcStringBindingParse routine obtains the binding information items as 
separate allocated strings. The components include an object UUID, a protocol 
sequence, a network address, an endpoint, and network options. If any of the 
components are null on input, no data is obtained for that parameter. 

The RpcStringFree routine frees strings allocated by other RFC runtime rou 
tines. 

Finding a Server from a Name Service Database 

The usual way for a client to obtain binding information is from a name service 
database using the name service RFC runtime routines (routines beginning with 
RpcNs). This method assumes that the server you want has exported binding infor 
mation to the name service database. 

The name service database contains entries of information, each identified by a 
name used in programs, environment variables, and commands. Clients can use a 
name called a server entry name to begin a search for compatible binding informa 
tion in the database. Entries contain binding information about specific servers. 
Use RFC name service runtime routines to search entries in the name service 
database for binding information. The example in this section does a very simple 
search. See Chapter 6 for a more detailed name service description. 

Importing a binding handle 

Since the same interface can be supported on many systems of the network, a 
client needs a way to select one system. The runtime import routines obtain 



62 Microsoft RFC Programming Guide 

information for one binding handle at a time from the name service database, 
selecting from the available list of servers supporting the interface. 

Example 3-8 shows how an application obtains binding information from a name 
service database. 

Example 3~8: Importing a Binding Handle 

/* FILE NAME: getbind.c */ 

/* Get binding from name service database. */ 

ttinclude <stdio.h> 

ttinclude "inv.h" 

# include " status. h" 

void do_iinport_binding(entry_name, binding_h) 

char entry_name [ ] ; /* entry name to begin search */ 

rpc_binding_handle_t *binding_h; /* a binding handle */ 

{ 

unsigned long status; /* error status */ 

RPC_NS_HANDLE import_context ; /* required to import */ 

char protseq[20] ; /* protocol sequence */ 

status = 

RpcNsBindinglmportBegin ( /* set context to import binding handles O */ 

RPC_C_NS_SYNTAX_DEFAULT, /* use default syntax */ 

(unsigned char *)entry_name, /* begin search with this name */ 

inv_Vl_0_c_ifspec, /* interface specification (inv.h) */ 

NULL, /* no optional object UUID required */ 

&import_context /* import context obtained */ 

); 

CHECK_STATUS( status, "Can t begin import:", RESUME); 

while (1) { 
status = 
RpcNsBindinglmportNext ( /* import a binding handle */ 

import_context , /* context from RpcNsBindinglmportBegin */ 

binding_h /* a binding handle is obtained */ 

); 
if (status != RPC_S_OK) { 

CHECK_STATUS( status, "Can t import a binding handle:", RESUME); 

break; 
} 

/** application specific selection criteria (by protocol sequence) */ 

do_interpret_binding ( *binding_h ,protseq) ; 

if (strcmp(protseq, "ncacn_ip_tcp" ) == 0) /*select connection protocol*/ 

break; 
else { 

status = 

RpcBindingFree ( /* free binding information not selected*/ 
binding_h 

); 

CHECK_STATUS( status, "Can t free binding information:", RESUME); 
} 
} /*end while */ 



Chapter 3: How to Write Clients 63 

Example 3~8: Importing a Binding Handle (continued) 

status = 

RpcNsBindinglnportDone ( /* done with import context */ 

&inport_context /* obtained from RpcNsBindinglmportBegin */ 
); 

return; 
} 

O The RpcNsBindinglmportBegin routine establishes the beginning of a search 
for binding information in a name service database. An entry name syntax of 
RPC_C_NS_SYNTAX_DEFAULT uses the syntax in the RFC-specific environment 
variable Def aultSyntax. 

In this example, the entry to begin the search is / . : /inventory_, which is 
passed as a parameter. If you use a null string for the entry name, the search 
begins with the name in the RFC environment variable Def aultEntry. 

If you use a null string for the entry name, and the DefaultEntry is null, the 
Locator searches for an entry name that offers the interface UUID. 

In this example, an object UUID is not required, so we use a null value. The 
interface handle Inv_Vl_0_c_ifspec refers to the interface specification. It is 
generated by the MIDI compiler and defined in file inv.h. 

Finally, the import context and error status are output. You use the import 
context in other import routines to select binding information from the name 
service database, or to free the context memory when you are done with it. 

@ The RpcNsBindinglmportNext routine obtains binding information that sup 
ports the interface, if any exists. The routine accesses the database and does 
not communicate with the server. The import handle, established with the call 
RpcNsBindinglmportBegin, controls the search for compatible binding han 
dles. 

Once binding information is obtained, any criteria required by the application 
may be used to decide whether it is appropriate. In this example, the applica 
tion-specific procedure, do_interpret_binding, shown in Example 3-6, is used 
to interpret binding information by returning the protocol sequence in a 
parameter. The do_import_binding procedure then selects the binding infor 
mation if it contains the connection protocol. 

O Each call to RpcNsBindinglmportNext requires a corresponding call to the 
RpcBindingFree routine that frees memory containing the binding information 
and sets the binding handle to null. Free the binding handle after you finish 
making remote procedure calls. 

@ The RpcNsBindinglmportDone routine signifies that a client has finished look 
ing for a compatible server in the name service database. This routine frees 
the memory of the import context created by a call to RpcNsBindinglmport 
Begin. Each call to RpcNsBindinglmportBegin must have a corresponding call 
to RpcNsBindinglmportDone. 



64 Microsoft RFC Programming Guide 

Looking up a set of binding handles 

Runtime routines whose names begin with RpcNsBindingLookup obtain a set of 
binding handles from the name service database. You can then select individual 
binding handles from the set with the RpcNsBindingSelect routine or you may use 
your own selection criteria. Lookup routines give a client program a little more 
control than import routines because RpcNsBindinglmportNext returns a random 
binding handle from a list of compatible binding handles. Use the lookup routines 
when you want to select a server or servers by more specific binding information; 
for example, to select a server that is running on a system in your building or to 
use servers supporting a specific protocol sequence. 

Finding a Server from Strings of Binding Data 

If you bypass the name service database, you need to construct your own binding 
information and binding handles. Binding information may be represented with 
strings. You can compose a binding handle from appropriate strings of binding 
information or interpret information that a binding handle refers to. 

The minimum information required in your application to obtain a binding handle 
is: 

A protocol sequence of communication protocols 

A server network address or host name 

Remember that an endpoint is required for a remote procedure call to complete, 
but you can let the RFC runtime library obtain one for you. To set a binding han 
dle, obtain and present the binding information to RFC runtime routines. 

Example 3-9 shows a procedure to set a binding handle from strings of binding 
information. The rfile application uses this procedure. A network address or host 
name is input for this procedure and the protocol sequence is obtained. This pro 
cedure creates a partially bound binding handle, so the RFC runtime library obtains 
the endpoint when a remote procedure uses the binding handle. 

Example 3~9: Setting a Binding Handle from Strings 

/* FILE NAME: strbind.c */ 

/* Find a server binding handle from strings of binding information */ 

/* including protocol sequence, host address, and server process endpoint. */ 

#include <stdio.h> 

#include "rfile. h" 

# include " status. h" /* contains the CHECK_STATUS macro */ 

int do_string_binding(host, binding_h) /*return=0 if binding valid, else -1 */ 
char host [ ] ; / * server host name or network address input O * / 

rpc_binding_handle_t *binding_h; /* binding handle is output */ 
{ 

RPC_PROTSEQ_VECTOR *protseq_vector; /* protocol sequence list */ 
unsigned char *string_binding; /* string of binding information */ 
unsigned long status; /* error status */ 



Chapter 3: How to Write Clients 65 

Example 3~9: Setting a Binding Handle from Strings (continued) 

int i, result; 

status = 

RpcNetworklnqProtseqs ( /* obtain a list of valid protocol sequences */ 
&protseq_vector /* list of protocol sequences obtained */ 

); 
CHECK_STATUS( status, "Can t get protocol sequences:", ABORT); 

/* loop through protocol sequences until a binding handle is obtained */ 
for(i=0; i < protseq_vector->Count; i++) { 

status = 

RpcStringRindingCompose ( /* make string binding from components @ */ 
NULL, /* no object UUIDs are required */ 

protseq_vector->Protseq[i] , /* protocol sequence */ 

(unsigned char *)host, /* host name or network address */ 
NULL, /* no endpoint is required */ 

NULL, /* no network options are required */ 

&string_binding /* the constructed string binding */ 

); 

CHECK-STATUS (status, "Can t compose a string binding:", RESUME); 

status = 

RpcBindingFromStringBinding ( /* convert string to binding handle O */ 

string_binding, /* input string binding */ 

binding_h /* binding handle is obtained here */ 

); 

CHECK_STATUS( status, "Can t get binding handle from string:", RESUME); 
if (status != RPC_S_OK) { 

result = -1; 

CHECK_STATUS( status, "Can t get binding handle from string:", RESUME); 
} 
else 

result = 0; 

status = 

RpcStringFree ( /* free string binding created*/ 

&string_binding 
); 

CHECK_STATUS( status, "Can t free string binding :", RESUME); 
if (result == 0) break; /* got a valid binding */ 

} 

status = 

RpcProtseqVectorFree ( /* free the list of protocol sequences*/ 

&protseq_vector 
); 

CHECK_STATUS( status, "Can t free protocol sequence vector:", RESUME); 
return ( result ) ; 
} 

O The network address or host name on which a server is available is required 
binding information. For this example, the information is input as a parame 
ter. 



66 Microsoft RFC Programming Guide 

@ The RpcNetworklnqProtseqs routine creates a list of valid protocol sequences. 
This example uses each protocol sequence from the list until a binding handle 
is created. 

The RpcStringBindingCompose routine creates a string of binding information 
in the argument string_binding from all the necessary binding information 
components. The component strings include an object UUID, a protocol 
sequence, a network address, an endpoint, and network options. 

O The RpcBindingFromStringBinding routine obtains a binding handle from the 
string of binding information. The string of binding information comes from 
the RpcStringBindingCompose routine or from the RpcBindingToString- 
Binding routine. 

When you are finished with the binding handle, use the RpcBindingFree rou 
tine to set the binding handle to null and to free memory referred to by the 
binding handle. In this example, another part of the application frees the 
binding handle. 

The RpcStringFree routine frees strings allocated by other RFC runtime rou 
tines. This example frees the string string_binding allocated by the Rpc 
StringBindingCompose routine. 

The RpcProtseqVectorFree routine is called to free the list of protocol 
sequences. An earlier call to RpcNetworklnqProtseqs requires a corresponding 
call to RpcProtseqVectorFree. 

Customizing a Binding Handle 

The basic binding handles we have seen so far are primitive binding handles. A 
customized binding handle adds some information that your application wants to 
pass between client and server. You can use a customized binding handle when 
application-specific data is appropriate to use for finding a server, and the data is 
also needed as a procedure parameter. 

For example, in an application that acts on remote files, a structure could contain 
a host name and a remote filename. The application creates the necessary binding 
information from the host name, and the filename is passed with the binding infor 
mation so the server knows what data file to use. You can use a customized bind 
ing handle with the explicit or implicit binding methods, but the automatic method 
uses only primitive binding handles. 

Figure 3-2 shows how a customized binding handle works during a remote proce 
dure call. To define a customized binding handle, apply the handle attribute to a 
type definition in an interface definition. 

You can use a customized binding handle in a client just like a primitive binding 
handle, but you must write special bind and unbind procedures. Your code does 
not call these procedures; the client stub calls them during each remote procedure 



Chapter 3: How to Write Clients 



67 









Client , 
< 

Application 
Code ^ 


& Set customized binding information 

* Call remote procedure 
A 


Bind Unbind 
procedure procedure 










I 


Bind procedure 
called to obtain 
primitive binding 
handle 


< 


7 Unbind 
procedure 
called 






Call completed ( 
with primitive 
Stub binding handle 

**^, -rt**** 


> , 

** 


k 


N* 




^MIMMVMMRRMMMM^^ 


pp- 
l 


r 







Figure 3~2. How a customized binding handle works 

call. For a primitive binding handle, the client stub already has the necessary code 
to prepare the binding information for the call. For application-specific binding 
information, you must supply the code. The tasks of the bind and unbind proce 
dures are to obtain a primitive binding handle and do application cleanup when 
finished with the binding handle. 

Manipulate the data structure in your application the same as any structure, includ 
ing passing data in the remote procedure call. However, the client stub uses the 
special procedures to manage the binding. The customized binding handle must 
be the first parameter in a remote procedure (or the global handle for the implicit 
method) to act as the binding handle for the call. A customized handle acts as a 
standard parameter if it is not the first parameter. 

Example 3-10 shows how to define a customized binding handle in an interface 
definition. 

Example 3~10: Defining a Customized Binding Handle 

I* FILE NAME: search. idl */ 
[ 

uuid(2450F730-5170-10lA-9A93-08002B2BC829), 

version (1.0) , 

pointer_default (ref ) ] 
interface search /* Search remote file for data */ 



const long LINESIZE = 100; 



/* Constant for maximum line size */ 



6# _ Microsoft RPC Programming Guide 

Example 3~ 10 - Defining a Customized Binding Handle (continued) 

const long FILENAME_SIZE = 100; /* Constant for file name length */ 

const long BINDING_SIZE = 32; /* Constant for host name size */ 

const short FILE_ERROR = -1; /* Status for search file error */ 

const short NO_MATCH =0; /* Status for no match found */ 

/* 

** Customized binding handle definition 

** contains the file name and the string 

** binding to use. 

*/ 

typedef [handle] struct { /* customized handle type O */ 

unsigned char binding [BINDING_SIZE] ; 

unsigned char filename [FILENAME_SIZE] ; 
} search_spec; /* */ 

/* 

** Search for a string match on the file specified 

** in the customized binding handle above. 

*/ 

short searchit( /* search a file on the server */ 

[in] search_spec custom_handle , /* customized binding handle*/ 
[in, string] char search_string[LINESIZE] , /* target string */ 
[out, string] char return_string[LINESIZE] , /* results */ 

[out] error_status_t * error /* comm/ fault status */ 



O Use the handle attribute in the interface definition to associate a customized 
binding handle with a data type. 

The f ile_spec data type is a structure whose members are file specifications. 
This is application-specific information used by the bind procedure to obtain 
server binding information. 

The customized binding handle is the first parameter of a procedure declara 
tion. This is an example of explicit binding. 

You must implement bind and unbind procedures. Example 3-11 shows how you 
can implement these procedures inside a client file. 

Example 3~ 1 1: Bind and Unbind Procedures 

I* FUNCTION: search_spec_bind */ 

handle_t RPC API 

search_spec_bind(custom_handle) /* bind procedure for customized handle O */ 

search_spec custom_handle; 

rpc_binding_handle_t binding_h; 

printf ("\n\t ( Selecting server binding: %s)\n\n", /* Display server binding*/ 
custom_handle . binding) ; 

status = 

RpcBindingFromStringBinding ( /* Convert the character string */ 

custom_handle. binding, /* binding into an RPC handle */ 

&binding_h, 



Chapter 3: How to Write Clients 69 

Example 3~H: Bind and Unbind Procedures (continued) 

); 

CHECK_STATUS( status, "Invalid string binding", RESUME); 
exit (EXIT_FAILURE) ; 
return (binding_h) ; 
} 

/* FUNCTION: search_spec_unbind */ 
void RFC API 

search_spec_unbind ( /* unbind procedure for customized handle */ 

custom_handle , 
binding_h) 

search_spec custom_handle; 
handle_t binding_h; 
{ 

status = 

RpcBindingFree ( /* Free the binding handle */ 

&binding_h) ; 

CHECK_STATUS( status, "Can t free binding handle :", RESUME); 
return; 
} 

O The bind procedure takes an input parameter of the customized handle data 
type, and returns a primitive binding handle. You construct the procedure 
name from the data type name, search_spec, to which you append _bind. In 
this example searcb_spec_bind constructs a binding handle from arguments 
passed on the client command line to obtain a primitive binding handle. 

The unbind procedure takes input parameters of the customized handle data 
type and a primitive binding handle. You construct the procedure name from 
the data type name, search_spec, to which you append _unbind. In this 
example search >_spec_unbind calls the RFC runtime routine, RpcBindingFree, 
to free the binding handle. 

Example 3-12 shows how an application client can use a customized binding han 
dle. 

Example 3~12: A Client with a Customized Binding Handle 

I* FILE NAME: client_send.c */ 



int 

MAIN_DECL main(ac, av) 

int ac ; 

char *av [ ] ; 

{ 

short search_status ; /* status from search */ 

idl_char match [LINESIZE] ; /* string to look for */ 
search_spec custom_handle; /* customized binding handle O */ 

match[0] = \0 ; /* Initialize some strings */ 

custom_handle . binding [ ] = \ ; 
custom_handle.filename[0] = \0 ; 



70 Microsoft RFC Programming Guide 

Example 3~12: A Client with a Customized Binding Handle (continued) 

I* 

** There should be 4 parameters to searchit: 

** 

** searchit <hostname> <filename> <matchstring> 
** 

** where 
** 

** <hostname> is the hostname where the file to be searched 

** exists. 

** 

** <filename> is the name of the file to be searched. 
** 

** <matchstring> is the string to search <filename> for. 
** 

*/ 

if (ac != 4) /* Exit if not the right number of parameters */ 

{ 

printf ( "\t\nUsage: searchit <hostname> <filename> <matchstring>\n\n" ) ; 

exit (EXIT_FAILURE) ; 

} 

/* 

** Set up the string binding, the filename, and the 

** match string from the command line. 

*/ 

strcpy ((char * ) custom_handle . binding, "ncacn_ip_tcp: ") ; /* */ 

strcat ((char * ) custom_handle . binding, av[l]); 

strcpy ( ( char * ) custom_handle . f i lename , av [ 2 ] ) ; 

strcpy ((char *)match, av[3] ) ; 

/* 

** Search the given file on the given host for the 

** given string. . . 

*/ 

search_status = searchit ( /* Remote procedure with input */ 

custom_handle , 

match, 

result , 

&rpc_status 



O The application allocates the customized binding handle. 

@ Initialize the customized binding information in the client before calling the 
remote procedure. For this example, when we invoke the client, we input the 
server host name, remote data filename, and search string as arguments. 

The remote procedure is called with the customized binding handle as the 
first parameter. 



Chapter 3: How to Write Clients 77 

Authentication 

Authentication in a distributed environment is a broad topic that is outside the 
scope of this book. Although we do not provide details on implementing security 
in Microsoft RFC applications, we will mention the major aspects and some trade 
offs involved in selecting various models. 

Microsoft RFC can use the security features of Microsoft Windows NT which are 
built into the named pipes (ncacn_np) and local RFC (ncalrpc) transports. You 
must restrict your application to using one of the two listed transports to use this 
security system. 

You can use the Windows NT security features by specifying options to the end- 
point parameter in a string binding. Options have names such as anonymous, 
identification, or impersonation, controlling which level of security to use. 

Alternatively, you can use RFC security available in Microsoft RFC. This form of 
security is transport-independent so your application can use other transports in 
addition to named pipes and local RFC. Microsoft RFC security currently uses the 
Windows NT Security Service as the only supported security provider. 

RFC security offers three kinds of protection: authentication, data integrity, and 
data privacy. Data integrity and data privacy involve extra encryption and decryp 
tion cycles which can be time consuming, so use these features only when neces 
sary. 

On client systems you can use RFC security by including the RpcBindingSetAuth- 
Info routine in your client program. Briefly, this routine places the client s identity 
information into the binding handle which is passed to the server as the first 
parameter in a remote procedure call. 

Servers extract the client authentication information from the client binding handle 
using the RpcBindinglnqAuth Client routine. Servers use this information to verify 
a client s authenticity. 

The server system supplies its identity information to clients by registering it with 
the RpcServerRegisterAuthlnfo routine. Clients or other servers can extract this 
information to authenticate the server s identity. Use the RpcBindinglnqAuthlnfo 
routine to extract server authentication information from the server binding han 
dle. 

To recap, using the transport level security built into named pipes and local RFC 
does not necessarily add lots of new code to an application. If you want to use 
security over transports other than named pipes or local RFC (for instance, TCP/IP 
or DECnet), you ll need to use RFC security features which can require extra pro 
gramming overhead. 



72 Microsoft RFC Programming Guide 

Error Parameters or Exceptions 

Microsoft RFC client applications require special error-handling techniques to deal 
with errors that may occur during a remote procedure call. The following discus 
sion pertains to both client and server development. 

Server and communication errors are raised to the client as exceptions during a 
remote procedure call. RFC exceptions are similar to the RFC error status codes. 
Errors have names with S as the second component, as in RPC_S_ADDRESS_ERROR. 
Exceptions have X as the second component, as in RPC_X_NO_MEMORY. 

Types of exceptions include the following: 

Exceptions raised on the client system, such as when the client process is out 
of memory (RPC_X_NQ_MEMORY). 

Exceptions raised to the client application by the client stub, such as when 
the stub has received bad data (RPC_X_BAD_STUB_DATA). 

Exceptions raised by the client stub on behalf of the server. These errors can 
occur in the server stub, in the remote procedures, or in the server s RFC run 
time library. The server transport layer does not return exceptions to the 
client. 

A distributed application can have errors from a number of sources, so you will 
need to decide whether you want to handle errors with exception handling code 
or error parameters. This may simply be a matter of personal preference or consis 
tency. 

Using Exception Handlers in Clients or Servers 

You can handle exceptions by writing exception handler code in the application to 
recover from an error or gracefully exit the application. Microsoft RFC supplies a 
set of macros as a framework to handle exceptions in your client or server code. 
(Example 5-6, in Chapter 5, uses RFC exception handling macros.) If your applica 
tion is written for Win32 only, use the Win32 versions of these macros. 

Using Remote Procedure Parameters to Handle Errors 

In your ACF, you can add error parameters to remote procedures in order to con 
veniently handle communication and server errors. The RFC runtime library then 
stores errors values in these parameters rather than raising exceptions. You can 
also use a combination of exception handlers and error parameters. 

When the simple arithmetic application in Chapter 1 encounters some errors, it 
returns a hexadecimal number. You must convert this number to a decimal error 
code number and then look it up to find out what happened. By making three 
simple changes to the arithmetic application you can get it to return the actual RFC 
error code: 



Chapter 3: How to Write Clients 73 

Add an error_status_t parameter to the remote procedure declaration in 
the MIDL file. 

Add an error_status_t parameter to the remote procedure implementation 
in the server. 

Declare the variable in the client file. 

The sum_arrays procedure declaration in the following MIDL file has an [out] 
parameter of the type error_status_t. 

void sum_arrays ( /* The sum_arrays procedure doesn t return a value */ 
[in] long_array a, /* 1st parameter is passed in */ 

[in] long_array b, /* 2nd parameter is passed in */ 

[out] long_array c, /* 3rd parameter is passed out */ 

[out] error_status_t *rpc_status /* error parameter is passed out */ 

We ve added the error_status_t parameter to the remote procedure in man 
ager. c. The initialized status value can be changed by the stubs if an error occurs. 

void sum_arrays (a, b, c, rpc_status) /* sum_arrays implementation */ 
long_array a; 
long_array b; 
long_array c; 
error_status_t *rpc_status ; /* error status parameter */ 

int i; 

*rpc_status = RPC_S_OK; /* initializes the status value */ 
for(i = 0; i < ARRAY_SIZE; i++) 

c[i] = a[i] + b[i]; /* array elements are added together */ 

The client code declares the variable along with the rest of the variables. Then a 
CHECK_STATUS macro converts the RFC error code to a status message. 

/* FILE NAME: client. c */ 

/* This is an arithmetic client module with error handling. */ 

#include <stdio.h> 

#include <stdlib.h> 

Mnclude "ari,th.h" /* header file created by MIDL compiler */ 

ttinclude "status. h" /* needed for CHECK_STATUS macro */ 

long_array a ={100,200,345,23,67,65,0,0,0,0}; 
long_array b ={4,0,2,3,1,7,5,9,6,8}; 

main () 

long_array result ; 

int i; 

/* declare variable and initialize */ 

error_status_t rpc_status=RPC_S_OK; 

/* remote procedure with status */ 
sum_arrays(a, b, result, &rpc_status ) ; 



74 Microsoft RFC Programming Guide 

I* report error and abort */ 

CHECK_STATUS (rpc_status, "ERROR:", ABORT); 

puts ("sums: ") ; 

for(i =0; i < ARRAY_SIZE; i++) 

printf ( "%ld\n" , result [i] ) ; 
} 

The CHECK_STATUS macro shown in Example 3-13 converts the RFC error code to 
an error message. 

Example 3~ 13: The CHECK_STATUS Macro 

/* FILE NAME: status. h */ 

ttinclude <stdio.h> 

ttinclude <stdlib.h> 

#include "..\rpcerror.h" /* maps error codes to error messages O */ 

#def ine RESUME 
#def ine ABORT 1 

#define CHECK_STATUS ( input_status , comment, action) \ 
{ \ 

if (input_status != RPC_S_OK) { \ 

error_stat = DceErrorinqText ( input_status , error_string) ; \ /* */ 
fprintf (stderr, "%s %s\n", comment, error_string) ; \ 
if (action == ABORT) \ 

exit(l); \ 
} \ 



static int error_stat; 

static unsigned char error_string[DCE_C_ERROR_STRING_LEN] ; 

O The file rpcerror.h is shown in Appendix C, The Arithmetic Application. 

Although Microsoft RFC does not support the DCE RFC routine 
dce_error_inq_text , we ve emulated its function here. 

Compiling and Linking Clients 

Figure 3-3 shows the files and libraries required to produce an executable client. 
When complex data types are used, the MIDL compiler produces the client stub 
auxiliary file (appl_x.c) when the interface is compiled. Example 3-14 shows the 
portion of a makefile that: 

Compiles the C language stubs and client code along with the header file pro 
ducing server object files 

Links the server object files to produce the executable server file 



Chapter 3: How to Write Clients 



75 



Write client 
application files. 



Include the header 
file(s) produced by 
interface compilation. 



Generate client application 
and stub object files. 



Use the client stub and 
auxiliary files produced 
by interface compilation. 



Create the executable client 
file by linking the client 
application, stub, and 
auxiliary object files with 
the Microsoft RFC library. 



Text 
Editor 




Figure 3~3- Producing a client 

Example 3~14: Using a Makefile to Compile and Link a Client 

# FILE NAME: Makefile 

# Makefile for the inventory application implicit client 
# 

# definitions for this make file 
# 

APPL=inv 

IDLCMEfcmidl 

NTRPCLIBS=rpcrt4 . lib rpcns4.1ib libcmt.lib kerne!32.1ib 

! include <ntwin32 .mak> 



## NT c flags 

cflags = -c -WO -Gz -D_X86_=1 -EWIN32 -EMT /I. /I., /nologo 



76 Microsoft RFC Programming Guide 

Example 3~14: Using a Makefile to Compile and Link a Client (continued) 

## NT nmake inference rules 

$(cc) $(cdebug) $(cflags) $(cvarsmt) $< 
$(cvtomf ) 



# 

# CLIENT BUILD 
# 

client: client.exe 

client.exe: client. obj getbind.obj intbind.obj $ (APPL)_c.obj $ (APPL)_x.obj 
$(link) $(linkdebug) $(conflags) -out : client . exe -map: client. map \ 

client. obj getbind.obj intbind.obj $(APPL)_c.obj $ (APPL)_x.obj \ 

$(NTRPCLIBS) 



# client and server sources 
client. obj: client. c $(APPL).h 
getbind . obj : getbind . c 
intbind . obj : intbind . c 



Local Testing 

You can compile a local version of your client to test and debug remote proce 
dures without using remote procedure calls. To do a local test, compile the client 
object files and remote procedure implementations without the stub or auxiliary 
files. The code that finds a server is also unnecessary for a local test. Applications 
in this book use the compiler directive, /DLOCAL, to distinguish a test compilation 
used in a local environment from a compilation used in a distributed environment. 
Example 3-15 shows the portions of a makefile that produce the inventory applica 
tion for local testing. 

Example 3~15: Using a Makefile to Produce a Local Version of an Application 

# FILE NAME: Makefile 

# Makefile for the inventory application implicit client 
# 

# definitions for this make file 
# 

APPL=inv 

IDLCMD=midl 

NTRPCLIBS=rpcrt4 . lib rpcns4.1ib libcmt.lib kerne!32.1ib 

! inc lude <ntwin3 2 . mak> 

## NT c flags 

cflags = -c -WO -Gz -D_X86_=1 -DWTN32 -EMT /I. /I., /nologo 

## NT nmake inference rules 



Chapter j. How to Write Clients 77 

Example 3~15: Using a Makefile to Produce a Local Version of an Application (continued) 

$(cc) $(cdebug) $(cflags) $(cvarsmt) $< 
$ (cvtomf ) 



# 

# LOCAL BUILD of the client application to test locally 

# 

local : Iclient . exe 

lclient.exe: Iclient. obj Imanager.obj invntry.obj 

$(link) $(linkdebug) $(conflags) -out: Iclient. exe -map: Iclient .map \ 

Iclient. obj Imanager.obj invntry.obj \ 

$(NTRPCLIBS) 



# Local client sources 
invntry . obj : . . \ invntry . c 

$(cc) $(cdebug) $(cflags) $(cvarsmt) /DLOCAL /I. /I.. \ 

/ Foinvntry . obj . . \ invntry . c 
Iclient. obj: client. c $(APPL).h 

$(cc) $(cdebug) $(cflags) $(cvarsmt) /DLOCAL /I. /I.. \ 

/Folclient.obj client. c 
Imanager.obj : . . \manager.c $ (APPL) .h 

$(cc) $(cdebug) $(cflags) $(cvarsmt) /DLOCAL /I. /I.. \ 
/Folmanager . obj . . \manager . c 



In this Chapter: 

Kinds of Pointers 

Kinds of Arrays 

Memory Usage 




Pointers, Arrays, 
and Memory Usage 



In C, pointers and arrays have a close correlation due to the way applications 
access the information they contain. Pointers and arrays work essentially the same 
in distributed and local applications. But there are a few restrictions in distributed 
applications because the client and server have different address spaces. In most 
of this chapter we discuss pointers and arrays for clients. See also Chapter 5, How 
to Write a Server, for a discussion of memory allocation for pointers and arrays in 
remote procedures. 

To make your applications more efficient, MIDL offers several kinds of pointers 
and arrays to reduce network traffic and stub overhead. This chapter uses the 
inventory application to demonstrate the use of pointers and arrays in distributed 
applications. 



Kinds of Pointers 



A pointer is a variable containing the address of another data structure or variable. 
As in C, you declare a pointer in an interface definition by using an asterisk (*) 
followed by a variable. For example, the inventory application has the following 
procedure declaration: 

void whatis_part_price( /* get part price from inventory */ 

[in] part_num number, 

[out] part_price *price 
); 

In a distributed application, the client and server do not share the same address 
space. This means the data a pointer refers to in the client is not available in the 
remote procedure of the server. The opposite is also true. Therefore, pointer data 
is copied between the client and server address spaces during a remote procedure 
call. For the whatis_part_price procedure, data that the pointer argument refers to 
on the server is copied back to the client and placed in the memory referred to by 



79 



80 Microsoft RFC Programming Guide 

the price pointer. This copying of pointer data does not occur during a local pro 
cedure call. 

MIDL has three kinds of pointers: reference, unique, and full. We ll describe them 
here in order of increasing capability. Keep in mind, though, that more capabilities 
result in more stub overhead. 

A reference pointer is used to refer to existing data. It is the simplest kind of 
pointer. Consequently, it has a performance advantage over other kinds of point 
ers because stub overhead is minimal. For example, the whatis_part_price proce 
dure uses a reference pointer. This procedure passes by reference a pointer to an 
allocated part_price data structure. The remote procedure returns output data to 
the same memory location with the part price. Thus, for reference pointers, the 
data can change but not the address itself. The [ref ] attribute specifies a refer 
ence pointer in an interface definition. 

Sometimes you need a pointer that can do more, such as handling singly-linked 
lists in which the end of the list is marked with a null pointer. For this situation, a 
unique pointer might be used because it can be null. A unique pointer has many 
capabilities usually associated with pointers. Use unique pointers in interface defi 
nitions when a remote procedure call allocates new memory for the client. In this 
case, the client stub actually allocates the memory. Unique pointers cannot address 
data that is also addressed by other pointers in the remote procedure, so you 
should avoid using complex data structures with cycles (doubly-linked lists). The 
[unique] attribute specifies a unique pointer in the interface definition. 

A full pointer has all of the capabilities associated with unique pointers. In addi 
tion, it allows two pointers to refer to the same address, as in a double linked list. 
The [ptr] attribute specifies a full pointer in the interface definition. Full pointer 
capability incurs significant stub overhead, so use full pointers only when neces 
sary. 

A pointer attribute must be applied where the pointer is defined with an asterisk. 
For instance, if you define a typedef that resolves to a pointer, you cannot apply 
the pointer attribute where you use the typedef. 

The following sections discuss the use of pointers, and tell you when you need a 
reference or full pointer. Table 4-1 and Example 4-5 summarize what you need to 
know to declare and use pointers. 

Pointers as Output Parameters 

Due to the overhead of transmitting data, you have to declare MIDL parameters to 
be input, output, or both. In MIDL, as in C, input parameters are passed in by 
value, which means a copy of each input parameter is available in the procedure. 
Passing input parameters by value makes sense for a small amount of data. This 
technique offers simplicity since programmers don t have to deal with pointers or 
addresses. However, passing by value also means that any change to the variable 



Chapter 4: Pointers, Arrays, and Memory Usage 



in the procedure cannot reflect back to the original parameter when the call com 
pletes. 

To fill in data for an output parameter (or modify an input/output parameter), 
both C and MIDI must pass by reference a memory address using a pointer or 
array parameter. During a remote procedure call, the parameter refers to existing 
memory, which is passed by reference to the client stub. When the remote proce 
dure completes execution, data is sent back by the server stub to the client stub, 
which unmarshalls it into the memory referred to by the pointer. Therefore, the 
data is available to the client application when the client stub returns to the appli 
cation. 

Example 4-1 shows an output parameter in the whatis_part_price procedure dec 
laration from the inventory interface definition. Pointer parameters (*price) are 
reference pointers by default. 

Example 4-1: Defining an Output Parameter 

void whatis_part_price ( /* get part price from inventory */ 

[in] part_num number, 

[out] part_price *price /* reference pointer */ 

); 

The part_price structure must be allocated in the client prior to the remote pro 
cedure call, but values are assigned in the remote procedure and transmitted back. 
The whatis_part_price remote procedure call in the client looks like this: 

part_record part; /* structure for all data about a part */ 



case p : whatis_part_price (part. number, & (part. price) } ; 
printf ( "price: %10.2f\n", part. price. per_unit) ; 
break; 

In the server, whatis_part_price reads a part record from the database for the part 
number input. It then assigns the values from the part record to the price structure 
members. Finally, the procedure returns and the price information is marshalled 
and transmitted by the server stub. The whatis_part_price remote procedure looks 
like this: 

void whatis_part_price (number, price) 
part_num number; 
part_price *price; 
{ 

parc_record *part; /* a pointer to a part record */ 

. r ead_part_record ( number , &par t ) ; 
price->units = part->price. units; 
price->per_unit = part->price.per_unit; 
return; 



82 Microsoft RFC Programming Guide 

You can see from the preceding explanation that an output parameter must refer 
to existing storage on the client, and therefore that it is always a reference pointer. 
In fact, the MIDL compiler refuses to let you declare an output-only parameter with 
the unique or ptr attribute. 

Suppose we don t know how much memory should be allocated for output data, 
so we want a procedure to return data in a parameter as newly allocated memory. 
We cannot just allocate some memory and hope it s enough because if the data 
output is greater, data will overwrite into other memory. To solve this, we pass a 
pointer to a pointer. We describe how to do this later in the chapter. 

A parameter used as both input and output is passed by reference. Programs com 
monly modify data by passing a pointer to a data structure into a procedure, 
which passes back the same pointer but with modified data. Optional (NULL) 
parameters can be used as input/output parameters. This feature is described in 
the following section. 

Pointers as Input Parameters 

Suppose our inventory interface has the following procedure declaration: 

void store_parts ( 

[in] part_record *partl, 

[in] part_record *part2 
); 

Assume this procedure adds new parts to the database. The procedure takes as 
parameters two pointers to structures of type part_record, (already defined in the 
interface) to store all data about a part. 

The remote procedure call in a client can look like the following: 

part_record *partl, *part2; 

parti = (part_record *)malloc(sizeof (part_record) ) ; 

part2 = (part_record *)itialloc(sizeof (part_record) ) ; 

/* part structures are filled in */ 

partl->nuniber = 123; 

part2->number = 124; 



store_parts (parti , part2 ) ; 

In this simple case, the client stub marshalls and transmits the data the pointers 
refer to. (This procedure is not implemented in any applications in this book, so 
no server code is shown.) 

One reason reference pointers reduce overhead is that the stubs make certain 
assumptions about the use of the pointer. Since pointer parameters are reference 
pointers by default, one of these assumptions is that a pointer parameter points to 
valid data of the type specified. 



Chapter 4: Pointers, Arrays, and Memory Usage 83 

Suppose we want optional parameters in our procedure definition. In this case, 
the client passes a null pointer value for the parameter, so the remote procedure 
knows to ignore it. For the stubs to know the parameter is a null value, the param 
eter must be a unique pointer so the stubs do not attempt to copy any data for the 
parameter. 

Example 4-2 shows how to modify our store_parts procedure declaration so that 
both parameters are unique pointers. 

Example 4-2: Defining Optional Procedure Parameters 

void store_parts_l ( /* O */ 

[in, unique] part_record *partl, 
[in, unique] part_record *part2 



typedef [unique] part_record *part_record_ptr; 
void store_parts_2 ( /* */ 

[in] part_record_ptr parti, 

[in] part_record_ptr part2 

O To specify an optional parameter, use the unique attribute on an input (or 
input/output) parameter. 

As an alternative to method 1 for specifying an optional parameter, define a 
unique pointer data type and use the data type for the procedure parameter. 

The client can now supply a NULL pointer: 

store_part s_l ( part 1 , NULL ) ; 

If an input/output parameter is a unique pointer with a null value on input, it is 
also null on output because the client does not have an address to store a return 
value. 

Microsoft RFC allows two pointers to refer to the same data. This practice is known 
as pointer aliasing. 




To minimize overhead, stubs cannot manage more than one reference pointer 
referring to the same data in a single remote procedure call. For example, suppose 
our store_parts procedure does something useful if we pass in the same pointer 



84 Microsoft RFC Programming Guide 

for both arguments. The following type of remote procedure call causes unpre 
dictable behavior: 

store_parts (parti, parti); /* WRONG do not use ref pointer aliasing */ 

This call will not work as expected because the parameters (reference pointers) 
both point to the same address. Reference pointers and unique pointers do not 
allow two pointers to refer to the same data. 

If store_parts_l were used instead of store_parts, the call would work correctly, 
because the arguments were specifically defined in the interface definition as full 
pointers with the ptr attribute. 

Using Pointers to Pointers for New Output 

A pointer refers to a specific amount of memory. For a procedure parameter to 
output newly allocated memory, we use a pointer to refer to another pointer that 
refers to data (or to another pointer and so on). This is also known as multiple 
levels of indirection. 

If you use just one pointer for a procedure parameter, you would have to make 
two remote procedure calls to allocate new memory. The first remote procedure 
call obtains the size of the server s data structure. Then the client allocates memory 
for it. The second remote procedure call obtains data from the server and fills the 
previously allocated memory. In a distributed application, using two pointers 
allows the client and server stubs to allocate all the necessary memory in one 
remote procedure call. The client stub must generate a copy of the memory allo 
cated on the server. 

The whatare_subparts procedure in the inventory application contains a parameter 
with a pointer to a pointer: 

[out] part_list **subparts 

The procedure allocates memory for the left pointer, and the right pointer is a 
parameter passed by reference to return the address of the left pointer. To accom 
plish this, MIDI must use two kinds of pointers: 



The right pointer is a reference pointer and the left pointer is a unique pointer. 
The reference pointer by itself cannot have new memory automatically allocated 
because it will point to the same address throughout the remote call. However, for 
the unique pointer, the amount of memory allocated by the server is allocated 
automatically by the client stub when the call returns. 

When a pointer attribute is applied in an interface definition where there are 
pointers to pointers, it applies only to the right pointer and does not propagate to 
any other pointers. 



Chapter 4: Pointers, Arrays, and Memory Usage 85 

Example 4-3 demonstrates how to return data in a parameter by using two point 
ers. The procedure needs to output a data structure (in this case a structure with a 
conformant array). The final size of the data structure is unknown when you call 
the remote procedure. 

Example 4-3: Defining Pointers to Pointers for Memory Allocation 



pointer_default (unique) /* the pointer default is a unique pointer O */ 
] interface inventory 



void whatare_subparts ( /* get list of subpart numbers for a part */ 

[in] part_num number, 

[out] part_list **subparts /* a pointer to a pointer ) */ 

); 

O Parameters or type definitions with multiple pointers use a pointer default to 
specify the kind of pointer for all but the right one. To establish a pointer 
default, use the pointer_default attribute in the interface definition header. 
In this example, the unique argument establishes a unique pointer default. 

If memory is allocated during remote procedure execution, output parameters 
require multiple pointers. By default, the right pointer of a procedure parame 
ter is a reference pointer. The left pointer must be a unique pointer. This is 
accomplished through the pointer_default attribute. 

The part_list structure is allocated during the remote procedure call. On the 
server, the remote procedure allocates memory and assigns data. The server stub 
marshalls and transmits the data back to the client. The server stub then frees the 
memory allocated in the remote procedure. The client stub allocates memory and 
unmarshalls the transmitted data into the new memory. The remote procedure call 
in a client for whatare_subparts looks like: 

part_record part; . /* structure for all data about a part */ 
part_list *subparts; /* pointer to parts list data structure */ 



case s : whatare_subparts ( part. number, &subparts) ; 
for(i = 0; i < subpart s->size; i++) 

printf ( " %ld " , subpart s->numbers [ i ] ) ; 
printf ("\ntotal number of subpart s : %ld\n ", subparts->size) 



86 Microsoft RFC Programming Guide 

When you finish with the data, free the memory allocated by unique pointers: 

free ( subparts ) ; 
break; 

See Example 5-9 in Chapter 5 for the server implementation of the remote proce 
dure whatare_subparts. 

Pointers as Procedure Return Values 

As we have described previously, the client must allocate memory for reference 
pointer data before it is used in a remote procedure call. This simplifies the client 
stub by giving unmarshalling code a place to put data after the server sends it. 
Now consider the following remote procedure call in client application code: 

unsigned long *a; 
a = proc ( ) ; 

The address of the procedure assignment, a, is available only when the procedure 
returns, and not during its execution. Therefore, we cannot use the method just 
described for a reference pointer to allocate memory in the client prior to the call, 
and expect the stub to complete the assignment for us. Procedures that return 
pointer results always return full pointers, so that the stub allocates any necessary 
memory and unmarshalls data into it for us. Example 4-4 shows a procedure that 
returns a pointer. 

Example 4-4: Defining a Procedure that Returns a Pointer 

typedef [string, unique] char *paragraph; /* description of part O */ 



paragraph get_part_description( /* return a pointer to a string */ 

[in] part_num number 
); 

O A pointer attribute (unique) on a pointer data type (char *paragraph) speci 
fies the kind of pointer for that data type wherever it is used in the interface. 
(If a pointer data type does not have a pointer attribute, the pointer specified 
with the pointer_default attribute applies.) To specify a pointer to a string, 
apply the string attribute as well. 

@ Procedures that return a pointer result always return a full pointer. A proce 
dure result cannot be a reference pointer because new storage is always allo 
cated by the client stub, which copies data into it when the call returns. 

The call to get_part_description looks like: 

part_record part; /* structure for all data about a part */ 



Chapter 4: Pointers, Arrays, and Memory Usage 



87 



case d : part. description = get_part_description (part. number ); 
printf ( "description: \n%s\n" , part .description) ; 

When you finish with the data, free the memory allocated by unique pointers: 



if (part. description != NULL) 
free (part .description) ; 



/* free memory allocated */ 



On the server, the remote procedure allocates memory that the server stub copies 
and transmits back to the client. The server stub then frees the memory allocated. 
Example 5-8 shows how to allocate memory in the get_part_description remote 
procedure. 

Pointer Summary 

As reference pointers, unique pointers, and full pointers represent increases in 
capability, they also require increases in stub overhead needed to manage them. 
Therefore, you must differentiate among reference, unique, and full pointers in the 
interface definition. Table 4-1 summarizes and compares pointer types. Example 
4-5 shows how to recognize which kind of pointer applies in an interface defini 
tion. A visible ref or unique pointer attribute overrides a default. 



Table 4-1: A Summary of Reference and Unique Pointers 

Reference Pointer Unique Pointer 



Full Pointer 



Attribute name ref 


unique 


ptr 


Characteristics Provides indirection 


Multiple levels of 


Indirection and full 


where the value is 


indirection 


pointer capabilities 


always the address 






of valid data 












Stub overhead Minimum 


Moderate 


Maximum 


Value of NULL Cannot be NULL 


Can be NULL 


Can be NULL 


Address value Never changes 


May change when a 


May change when a 


when a call returns 


call returns 


call returns 


Storage . Storage exists prior 


Storage is allocated 


Storage is allocated 


to the call 


automatically if 


automatically if 




needed 


needed 


Input and out- Data is written into 


The storage location 


The storage location 


put parameter existing storage 


of data on output 


of data on output 


when the call re 


may be different 


may be different 


turns 


from the storage lo 


from the storage lo 




cation on input. If 


cation on input. If 




the input value is 


the input value is 




NULL, the output 


NULL, the output 




value is also NULL. 


value is also NULL. 



88 



Microsoft RFC Programming Guide 



Table 4-1: A Summary of Reference and Unique Pointers (continued) 
Reference Pointer Unique Pointer Full Pointer 


Output parame 
ter 


Parameter is a refer 
ence pointer by de 
fault 


Not allowed 


Not allowed 


Input parameter 


Data is read from 
existing storage 


Data is read from 
existing storage; if 
the value is NULL, 
no data is read 


Data is read from 
existing storage; if 
the value is NULL, 
no data is read 


Pointer aliasing 


Not allowed 


Not allowed 


Allowed 



Example 4-5: How to Determine Kinds of Pointers 



pointer_default (unique) ; 
] inventory interface 



/*O*/ 



typedef [string, unique] char *paragraph ;/**/ 



paragraph get_part_description ( 
[in] part_num number, 



/**/ 



void whatis_part_price( 

[in] part_num number, 
[out] part_price *price 



/* O */ 



void whatare_subparts ( 

[in] part_num number, 
[out] part_list **subparts 



/* */ 



typedef struct { 
[ref] part_num 



*number; 



/* */ 



Chapter 4: Pointers, Arrays, and Memory Usage 89 

Example 4-5: How to Determine Kinds of Pointers (continued) 

[ref] part_quantity *quantity; 
[ref] account_num *account; 
} part_order; 



void store_parts_l ( 

[in, unique] part_record *partl, 
[in, unique] part_record *part2 



O The MIDL compiler attempts to assign the appropriate kind of pointer to 
pointers without a full, unique, or ref attribute. The pointer_default 
interface header attribute specifies which kind of pointer applies when one 
cannot be automatically determined. You can give the pointer_default 
attribute an argument of ref, unique, or full. If a pointer attribute is not 
specified for the data type, the interface requires a pointer default to specify 
the kind of pointer for the following cases: 

Pointers in typedefs (see callout 2) 

Multiple pointers other than the right pointer (see callout 5) 

Pointers that are members of structures or cases of discriminated unions 
(see callout 6) 

A pointer type attribute specifies the kind of pointer used. In this example, all 
occurrences that use the paragraph data type are unique pointers. If none of 
the pointer attributes ref, unique or full is present in the typedef, the 
pointer_default attribute specifies the kind of pointer. 

A pointer return value of a procedure is always a unique pointer because new 
memory is allocated. The paragraph data structure is a pointer to a string. 

O A pointer parameter of a procedure is a reference pointer by default. Parame 
ter reference pointers must always point to valid storage (never null). (See 
also callout 7.) 

With multiple pointers, the pointer_default attribute specifies all pointers 
except the right-most pointer. In this example, the right pointer is a reference 
pointer because it is a parameter pointer. The left pointer is determined by 
the pointer default. In this procedure, the left pointer must be a unique 
pointer so the array of parts in the subparts structure is automatically allo 
cated by the client stub when the call returns. 

When a structure member or discriminated union case is a pointer, you must 
assign it a unique or ref attribute, either explicitly or through the attribute 
pointer_default. This interface definition specifies the structure members as 
reference pointers in order to override the unique pointer default. Unique or 



90 Microsoft RFC Programming Guide 

full pointers are unnecessary for these structure members; therefore, it is more 
efficient to use reference pointers to minimize the overhead associated with 
unique pointers. 

An input or input/output pointer parameter can be made an optional proce 
dure parameter by applying the unique attribute. An attribute of either 
unique or ptr is required if you pass a value of NULL in a call. 

Kinds of Arrays 

You can use the following kinds of arrays in RFC applications: 

Fixed arrays contain a specific number of elements defined in the interface 
definition. They are defined just like standard C declarations. 

Varying arrays have a fixed size but clients and servers select a portion to 
transmit during a remote procedure call. The interface definition specifies sub 
set bound variables used by the clients and servers to set the bounds. 

Conformant arrays have their size determined in the application code. The 
interface definition specifies an array size variable that the clients and servers 
use to control the amount of memory allocated and data transmitted. 

Selecting a Portion of a Varying Array 

For some clients or servers you need to use only a portion of an array in a remote 
procedure call. If this is the case, it is more efficient to transmit only the needed 
portion of the array. Procedures or structures that use varying arrays with data 
limit variables allow you to select the portion of an array that is processed by a 
remote procedure call. 

A varying array has a fixed size when the application is compiled, but the portion 
of the array that contains the relevant, transmissible data is determined at runtime. 
For example, given the varying array arr [100] , you can specify any index values 
in the range < L < U < 99, where L represents the lower data limit of the array 
and (/represents the upper data limit. 

An array is varying if you declare it in your interface definition with two extra 
attributes: first_is to indicate where transmission starts (Z), and either 
length_is or last_is to indicated where transmission stops ((/). Whether you 
use length_is or last_is depends on convenience. 

Suppose that the following procedure appears in an interface definition: 

const long SIZE = 100; 

void proc ( 

[in] long first, 
[in] long length, 



Chapter 4: Pointers, Arrays, and Memory Usage 91 

[in, first_is( first) , length_is (length) ] data_t arr[SIZE] 
); 

To select a portion of the array to transmit, assign values to the variables first 
and length. For input parameters, the client sets them prior to the remote proce 
dure call. Be sure the upper data limit value does not exceed the size of the array, 
for example: 

long first = 23; 
long length = 54; 
data_t arr[SIZE] ; 

proc ( first, length, arr); 

The transmitted array portion is represented by the indices |23| . . . [76| (23 + 54 - 
1). The entire array is available in the client and the server, but only the portion 
represented by the data limit variables is transmitted and meaningful for the given 
remote procedure call. If the data limit parameters are also output, the remote pro 
cedure can set them to control the portion of the array transmitted back to the 
client. 

A structure is an alternate way to define a varying array in an interface definition; 
for example: 

typedef struct varray_t { 

long first; 

long length; 

[first_is( first) , length_is ( length) ] data_t arr [SIZE] ; 
} varray_t; 

proc ([in] varray_t varray) ; 

Managing the Size of a Conformant Array 

Conformant arrays are defined in an interface definition with empty brackets or an 
asterisk (*) in place of the first dimension value. 

. . . cl[*] . . . 
. . . c2[] [10] . . . 

The conformant -array cl [ * ] has index values [o] ... \M\ in which the dimension 
variable, M, represents the upper bound of the array. The dimension variable is 
specified in the interface definition and used in the application code at runtime to 
establish the array s actual size. 

To specify an array size variable or a maximum upper bound variable, use one of 
the array size attributes, size_is or max_is, in an interface definition. These vari 
ables are used in the application to represent the size of the array. You can use 
either one, depending on which you find most convenient. Example 4-6 shows 
how a conformant array is defined in a structure. 



92 



Microsoft RFC Programming Guide 



Example 4-6: A Conformant Array in an Interface Definition 



typedef struct part_list{ 

long size; /" numoer or pares in array w "/ 

[size_is(size) ] part_num numbers [*]; /* conformant array of parts*/ 

} part_list; 



/* list of part numbers */ 
/* number of parts in array O */ 



typedef struct part_record { /* data for each part */ 

part_num number; 

part_name name; 

paragraph description; 

part_price price; 

part_guantity quantity; 

part_list subparts; /* Conformant array or struct must be last */ 
} part_record; 



void whatare_subparts ( 

[in] part_num number, 
[out] part_list **subparts 



/* get list of subparts numbers for a part */ 

/**/ 



O When an array member of a structure (numbers [*]) has an array attribute, the 
dimension variable (size) must also be a structure member. This assures that 
the dimension information is always available with the array when it is trans 
mitted. The dimension variable member must be, or must resolve to, an inte 
ger. 

The size_is attribute specifies a variable (size) that represents the number 
of elements the array dimension contains. In the application, the array indices 
are ... |size-l[ . For example, if size is equal to 8 in the application code, 
then the array indices are 



If a conformant array is a member of a structure, it must be last so that your 
application can allocate any amount of memory needed. A conformant struc 
ture (structure containing a conformant array member) must also be the last 
member of a structure containing it. 

O Use a conformant structure and multiple levels of indirection for remote pro 
cedures that allocate a conformant array. Chapter 5 implements this proce 
dure. 

To specify a variable that represents the highest index value for the first dimension 
of the array rather than the array size, use the max_is attribute instead of the 
size_is attribute. For example, the conformant structure defined in Example 4-6 
can also be defined as follows: 



Chapter 4: Pointers, Arrays, and Memory Usage 



typedef struct part_list{ 

long max; 

[max_is (max) ] part_num numbers [*] ; 
} part_list; 

The variable max defines the maximum index value of the first dimension of the 
array. In the application, the array indices are \Q\ . . . |max| . For example, if max is 
equal to 7 in the application code, then the array indices are 



To avoid making mistakes in application development, be consistent in the inter 
face definitions you write. Use either the size_is attribute or the max_is attribute 
for all your conformant arrays. 

Conformant arrays as procedure parameters 

When you call a remote procedure that contains a conformant array, you must 
pass the number of elements that are contained by the array. When a client calls 
the whatare_subparts remote procedure of Example 4-3, the dimension informa 
tion is available in the part_list structure. However, if an array is passed as a 
parameter, the dimension information must also be an in parameter of the proce 
dure. 

For example, instead of obtaining an array of all the subparts for a part (as the 
ivhatare_subparts procedure does) you may want only the first five subparts. This 
procedure is defined as follows: 

void get_n_subparts ( /* get n subpart numbers for a part */ 

[in] part_num number, 

[in] long n, 

[out,size_is (n) ] part_num subparts [] 
); 

In the client, the input includes the part number, a 5 representing the number of 
subparts desired, and a previously allocated array, large enough for the five sub- 
part numbers. The output is the array with the first five subpart numbers. (The 
get_n_subparts procedure is not defined in the inventory interface definition.) 

Dynamic memory allocation for conformant arrays 

Suppose the following procedures appear in interface definitions: 

procl([in] long size, [in, size_is (size) ] data_t arr[]); 
proc2([in] long max, [in, max_is(max)] data_t arr[]); 

You have to allocate memory for each array needed in the application. To allocate 
dynamic memory for conformant arrays, use a scheme such as the following: 

unsigned long s,m; 

data_t *s_arr, *m_arr; /* pointers to some data structures */ 

/* some application specific constants */ 
s = SIZE; 
m = MAX; 



94 Microsoft RFC Programming Guide 

I* allocation of the arrays */ 

s_arr = (data_t *)malloc( (s) * sizeof (data_t) ) ; 
m_arr = (data_t *)malloc( (m+1) * sizeof (data_t) ) ; 

/* the remote procedure calls */ 
proc 1 ( s , s_ar r ) ; 
proc2 (m, m_arr) ; 

In this example, SIZE is defined in the client to represent an array size and MAX is 
defined to represent the maximum index value of an array. Notice an array that 
has the max_is attribute in its interface definition must have an extra array ele 
ment allocated because arrays begin with an index value of 0. 

Memory allocation for conformant structures 

Structures containing a conformant array require memory allocation in the client 
before they are input to a remote procedure call, because a statically allocated 
conformant structure has storage for only one array element. For example, the fol 
lowing is the part_list structure of the inventory interface: 

typedef struct part_list{ 

long size; 

[size_is (size) ] part_num numbers [*] 
} part_list; 

The structure in the header file generated by the MIDI compiler has an array size 
of only one, as follows: 

typedef struct part_list { 

unsigned long size; 

part_num numbers [ 1 ] ; 
} part_list; 

The application is responsible for allocating memory for as much of the array as it 
needs. Use a scheme such as the following to allocate more memory for a confor 
mant structure: 

part_list *c; /* a pointer to the conformant structure */ 

long s; 

s = 33; /* the application specific array size */ 

c = (part_list * )malloc( sizeof (part_list) + (sizeof (part_num) * (s-1) )); 

Notice that since the declared structure s size contains an array of one element 
representing the conformant array, the new memory allocated needs one array ele 
ment less than the requested array size. 



Memory Usage 



Distributed applications usually involve more complicated memory management 
than single-system applications because the address spaces are on separate 
machines. Fortunately, for many programming situations, Microsoft RPC s default 



Chapter 4: Pointers, Arrays, and Memory Usage 95 

memory usage method can automate most of the memory management details, 
freeing programmers to concentrate on the application itself. In the default 
method, memory on clients and servers is allocated automatically by the stub code 
for each part of the data structure being stored. 

However, while this automation is certainly convenient, it can sometimes result in 
large stub code and slower performance, especially when the data structures being 
managed are complex. Consequently, Microsoft RFC offers alternative memory 
usage methods which can help optimize performance, decrease stub size, or let 
you tailor your application to specific programming circumstances. 

Before we look at specific methods, let s look at the kind of data structures that 
are passed between clients and servers. Sizeable amounts of data are usually 
passed between clients and servers as pointers. Simple pointer data can usually be 
handled by the stub code using the default memory management scheme. But 
more complex data structures such as linked lists might benefit from the use of 
alternative memory management methods. Linked lists can be made up of many 
nodes connected with pointers. The size of a linked list is often variable and mem 
bers need to be inserted or deleted in the middle easily. 

A two-dimensional linked list could represent a sparse array which your applica 
tion sends to a compute server to be multiplied. Tree structures are a natural form 
for parsed language data. For example, you might call a "parse server" with a file 
name and it could return a syntax tree of the data broken down according to 
grammar rules. Arithmetic expressions are often represented internally in tree 
form. Graphs of nodes are used in resource allocation problems, usually represent 
ing networks of computers, of cities, and so on. 

In any case, linked lists consist of multiple nodes which must be allocated storage 
space in both clients and servers. By default, the client and server stub code which 
marshalls and unmarshalls data uses a crude but effective algorithm to manage the 
pointers. It makes separate calls to midl_user_allocate and midl_user_free to allo 
cate and deallocate each individual node in the data structure. While this approach 
can add stub overhead to the application, it relieves you from having to concern 
yourself with memory management details. 

In addition to the default method, there are three other memory usage methods 
which you can use by including ACF attributes or by making slight changes to the 
IDL file. The methods together, are: 

node-by-node allocation and deallocation (the default) 

single buffer allocation 

client application allocated buffers 

persistent storage on the server 

Of the four methods, the first two rely solely on the stubs to allocate and free 
memory while the last two involve the application. In previous chapters we 



96 



Microsoft RFC Programming Guide 



explained that you must include user-written versions of midl_user_allocate and 
midl_user_free in both the client and server parts of your application. The reason 
for this is that the client and server stubs or, in some cases, your application code, 
calls these procedures to allocate and deallocate memory used by application 
parameters. 

Table 4-2 shows whether the stub code or the application is responsible for mem 
ory management in each method. 



Table 4-2: What Allocates Memory 

Client 
Stub Code Application 

Node by node alloca 
tion and deallocation 

user allocate 



Server 



Stub Code 



Application 



m idl_ user^free 

Single buffer alloca 
tion 

m idl_ user_allocate 
m idl_ user^free 

Client application- 
allocated buffers 

m idl_ user_allocate 
m idl_ user_Jree 

Persistent storage on 
the server 

midl_user_allocate 
l_ user_Jree 



The following sections examine the reasoning behind each memory usage 
method. The sections also describe how to use ACF attributes to select a method 
for use with a given situation. All of the alternative (non-default) memory usage 
methods use attributes that are extensions of DCE IDL. The use of these attributes 
requires the /ext MIDL compiler switch at compile time. 

Node-By-Node Allocation and Deallocation 

When you are passing simple pointers back and forth between a client and a 
server, you needn t worry about choosing a particular memory usage method. The 
stub code, which marshalls and unmarshalls parameters, will allocate and deallo 
cate memory for you on both the client and the server. 

On the other hand, separate stub calls to midl_user_allocate for each node in a 
complex linked list can add unnecessary stub overhead to the application. If you 



Chapter 4: Pointers, Arrays, and Memory Usage 97 

are worried about the overhead, perhaps you could use this method to get your 
application up and running and then choose another method if you think memory 
usage is a bottleneck. 

Using Contiguous Server Memory 

When memory on the server is contiguous, as it ordinarily is with Microsoft Win 
dows NT, you might increase performance by directing the stub to allocate a sin 
gle linear buffer for the entire tree or graph. 

In this case, the client stub determines the size of the buffer needed by chasing all 
of the pointers in the structure. This approach relieves the server stubs from mak 
ing separate calls to midl_user_allocate for each node in the data structure. 
Because data can be accessed sequentially, memory performance might also be 
improved by using this technique. 

To use this technique, apply the ACF attribute allocate (all_nodes) to the 
pointer type in a typedef in the ACF file. 

/* ACF fragment */ 

typedef [allocate (all_nodes )] point er_name; 

Allocating Buffers with the Client Application 

When you know how big a data structure is, you can specify the buffer size in the 
client application and pass it to the server as a parameter to the remote procedure. 
This technique can help minimize the stub size on clients and servers and improve 
the performance of the affected remote procedure call because the client stub 
doesn t have to chase pointers. The server stub allocates the buffer space with one 
call to midl_user_allocate , using the size parameter taken from the remote proce 
dure call. The runtime library will raise an exception if insufficient memory is allo 
cated, however. After the call completes, the server stub frees the memory with 
one call to midl_user_Jree . 

The client side can benefit from this technique, too. For instance, say your applica 
tion has a multiplication interface that multiplies matrixes as in multiplyjnatrix 
(matrix *ml *m2 ) . -Now let s say that the client makes many calls to this same 
interface. In this case, it s probably more efficient for the client application to allo 
cate and control memory directly, reusing the memory that is allocated only once, 
rather than have the client stubs allocate and free memory with each call. 

Even when you know the buffer size, you might not want to take the time to use 
this technique. But if memory allocation causes a bottleneck in your application, 
the technique may help. 

This method requires two steps. First, add a size parameter to the procedure decla 
ration in the IDL file, as illustrated in the following IDL file fragment in which we 
include the parameter cBytes. 



Microsoft RFC Programming Guide 



I* IDL file function declaration (fragment) */ 

void GetEmployeeRecord ( 

[in, string] char EnployeeName [NAMESIZE] , 

[in] short cBytes, 

[out, ref] P_RECORD_TYPE pRecord /* record for named employee */ 
); 

Second, in the ACF file, apply the ACF byte_count attribute to the parameter that 
will store the size of the buffer. 

/* ACF file (fragment */ 

GetEmployeeRecord ( [byte_count (cEytes) ] pRecord ) ; 

Now the server stub will make a single call to midl_user_allocate using the cBytes 
size parameter to allocate memory for this buffer. 

Persistent Storage on the Server 

Persistent state, or "context," offers a way to manage data on the server so that 
you can reuse it from call to call, and clean it up properly after you re done with 
it. One example of persistent state might be a dictionary server or a symbol table 
server. You pass the server a tree which it saves away, and then you make queries 
against it later. This technique can save time because your application does not 
need to copy the same data into a buffer each time it s needed. 

To use this method, apply the allocate(dont_free) attribute to the ACF typedef 
declaration in the ACF file, as in the following usage example. 

/* ACF fragment */ 

typedef [allocate (all_nodes, dont_free) ] pointer_name; 

Using this method, the server stub does not call midl_user_/ree when the remote 
procedure call completes. Instead, the server application must call midl_user_Jree 
when its procedures are finished using the data structure. To make the parameters 
available for use by other remote procedure calls on the server, you must copy the 
pointers to global variables. 

In Chapter 7, Context Handles, we ll see a different way of managing server con 
text through the use of context handle types. While context handles require more 
programming than the simpler persistent data technique mentioned here, they 
offer more automatic functions which you may want to use. For instance, context 
handles track and free memory resources automatically and they can associate 
server contexts with specific clients. 



In this Chapter: 

Some Background on 
Call Processing 

Initializing the 
Server 

Writing Remote 
Procedures 

Compiling and 

Linking Servers HOW tO W^tC d 




RPC servers are more complicated than clients at least at this introductory stage 
because the servers have a more complicated role: they have to be continuously 
active and be prepared to handle multiple calls in any order. This chapter uses the 
inventory example as the basis for showing the various issues required by servers. 

Before reading this chapter, it s a good idea to read Chapter 1, Overview of an RFC 
Application, for an overview of a distributed application, and Chapter 2, Using a 
Microsoft RPC Interface, for features of interface definitions. You should also read 
Chapter 3, How to Write Clients, to understand how clients use servers. 

You write the following two distinct portions of code for all servers: 

Server initialization includes most of the RFC-specific details including RPC 
runtime routines. This code is executed when the server begins, before it pro 
cesses any remote procedure calls. 

The manager portion, or remote procedure implementations, include special 
techniques for memory management. 

Some Background on Call Processing 

Chapter 1 describes how a typical distributed application works: 

Figure 1-9 shows the initialization steps to prepare a server before it processes 
remote procedure calls. 

Figure 1-10 shows how a client finds a server using the automatic binding 
method. 

Figure 1-11 shows the basic steps during a remote procedure call after the 
client finds the server. 



99 



100 



Microsoft RFC Programming Guide 



To understand server initialization, it is useful at this point to explain how the RFC 
runtime library handles an incoming call. Figure 5-1 shows how the server system 
and RFC runtime library handle a client request. 



Server 
Host 



Server 

RFC 

Runtime 

Library 




Request 
Queue 




O Call is placed in 
request queue 



Call from client 



Figure 5- 1 . How the server runtime library handles a call 

A call request for the server comes in over the network. The request is placed 
in a request queue for the endpoint. (The server initialization can select more 
than one protocol sequence on which to listen for calls, and each protocol 
sequence can have more than one endpoint associated with it.) Request 
queues temporarily store all requests, thus allowing multiple requests on an 
endpoint. If a request queue fills, however, the next request is rejected. 

The RFC runtime library dequeues requests one at a time from all request 
queues and places them in a single call queue. The server can process remote 
procedures concurrently, using threads. If a thread is available, a call is imme 
diately assigned to it. (Server initialization can select the number of threads 
for processing remote procedure calls.) In this figure, only one thread is exe 
cuting. If all threads are in use, the call remains in the call queue until a 
thread is available. If the call queue is full, the next request is rejected. 

) After a call is assigned to a thread, the interface specification of the client call 
is compared with the interface specifications of the server. An interface speci 
fication is an opaque data structure containing information (including the 
UUID and version number) that identifies the interface. Opaque simply means 



Chapter 5: How to Write a Server 101 

the details are hidden from you. If the server supports the client s interface, 
processing goes to the stub code. If the server does not support the client s 
interface, the call is rejected. 

When the call finally gets to the stub, it unmarshalls the input data. Unmarshalling 
involves memory allocation (if needed), copying the data from the RFC runtime 
library, and converting data to the correct representation for the server system. 

Initializing the Server 

The server initialization code includes a sequence of runtime calls that prepare the 
server to receive remote procedure calls. The initialization code typically includes 
the following steps: 

1 . Register the interface with the RFC runtime library. 

2. Create server binding information by selecting one or more protocol 
sequences for the RFC runtime library to use in your network environment. 

3. Advertise the server location so the clients have a way to find it. A client uses 
binding information to establish a relationship with a server. Advertising the 
server usually includes storing binding information in a name service 
database. Occasionally an application stores server binding information in an 
application-specific database, or displays it, or prints it. 

4. Manage endpoints in a local endpoint map. 

5. Listen for remote procedure calls. 

During server execution, no remote procedure calls are processed until the initial 
ization code completes execution. RFC runtime routines are used for server initial 
ization. (Table B-2 in Appendix B, RFC Runtime Routines Quick Reference, lists all 
the RFC runtime routines for servers.) 

Example 5-1 shows the necessary header files and data structures for server initial 
ization of the inventory application. 

Example 5-1: Server Header Files and Data Structures 

I* FILE NAME: server. c */ 

ftinclude <stdio.h> 

#include <stdlib.h> 

ftinclude <ctype.h> 

#include "inv.h" /* header created by the MIDL compiler O */ 

#include "status. h" /* contains the CHECK_STATUS macro */ 

#define STRINGLEN 50 

main (argc, argv) 
int argc; 
char *argv [ ] ; 
{ 

error_status_t status; /* error status (nbase.h) */ 

/* RFC vectors @ */ 



102 Microsoft RFC Programming Guide 

Example 5-1: Server Header Files and Data Structures (continued) 

rpc_binding_vector_t *binding_vector; /* binding handle list (rpcdce.h) */ 
rpc_protseq_vector_t *protseq_vector; /*protocol sequence list (rpcdce.h) */ 

char entry_name[STRINGLEN] ; /* name service entry name */ 

char annotation [ STRINGLEN] ; /* annotation for endpoint map */ 

char hostname [ STRINGLEN] ; /* used to store the computer name */ 

EWORD hostname_size=STRINGLEN; /* required by GetComputerName */ 



/* For the rest of the server initialization, register interfaces, */ 
/* create server binding information, advertise the server, */ 

/* manage endpoints, and listen for remote procedure calls. */ 

O Always include the C language header file (created by the MIDL compiler) 
from all interfaces the server uses. This file contains the definitions of data 
types and structures that are needed by the RFC runtime routines. 

An unsigned32 variable is needed to report errors that may occur when an 
RFC runtime routine is called. 

Some RFC runtime routines use a data structure called a vector. A vector in 
RFC applications contains a list (array) of other data structures and a count of 
elements in the list. Vectors are necessary because the number of elements on 
the list is often unknown until runtime. The rpc_binding_vector_t is a list 
of binding handles in which each handle refers to some binding information. 
The list in rpc_protseq_vector_t contains protocol sequence information 
representing the communication protocols available to a server. RFC runtime 
routines create vectors, use vectors as input, and free the memory of vectors. 

Many header files such as rpc.h and rpcndr.h are included in the interface header 
inv.h. The rpc.h file in turn has included within it header files such as rpcdce.h, 
rpcnsi.h, and rpcnterr.h. Many of these header files are associated with RFC- 
specific interface definitions. These interface definitions contain data structure defi 
nitions you may need to refer to in order to access structure members and make 
runtime calls. 

Object UUIDs are scattered throughout the RFC runtime routines as parameters for 
developing certain kinds of applications. You do not need to use object UUIDs to 
develop many applications so they are not covered in this book. 

Registering Interfaces 

All servers must register their interfaces so that their information is available to the 
RFC runtime library. This information is used when a call from a client comes in, 
so the client is sure the server supports the interface, and the call can be correctly 
dispatched to the stub. 

Before a client makes a call, it checks its interface against the one advertised in the 
server s binding information. But that does not guarantee that the server supports 



Chapter 5: How to Write a Server 103 

the client s interface. For example, it is possible for a complex server to temporar 
ily suspend support for a specific interface. Therefore, when a remote procedure 
call arrives, a comparison is made between the client s and server s interface speci 
fications. If the server supports the client s interface, the RFC runtime library can 
dispatch the call to the stub. 

Use an interface handle to refer to the interface specification in application code. 
An interface handle is a pointer defined in the C language header file and gener 
ated by midl. For example, the server interface handle for the inventory applica 
tion is inv_Vl_0_s_ifspec. The interface handle name contains the following: 

The interface name given in the interface definition header (inv). 

The version numbers in the version attribute (vl_0). If the interface definition 
has no version declared, version 0.0 is assumed. 

The letter s or c depending on whether the handle is for the server or client 
portion of the application. 

The word if spec. 

The default style of interface names generated by the midl version 2.0 compiler is 
compatible with names generated by the OSF DCE IDL compiler. Note that the midl 
version 1.0 compiler generates another form of interface handle name such as 
inv_ClientIfHandle and inv_Server If Handle. To generate older names that 
are compatible with midl version 1.0 interface names, you must use the /oldnames 
option with a midl version 2.0 compiler. 

Example 5-2 is a portion of C code that registers one interface. 

Example 5-2: Registering an Interface with the Runtime Library 

I* The header files and data structures precede registering interfaces. */ 



/************************** REGISTER INTERFACE ***************************/ 

status = 

RpcServerRegisterlf ( /* O */ 

inv_Vl_0_s_if spec , /* interface specification (inv.h) */ 

NULL, 

NULL 
); 
CHECK_STATUS( status, "Can t register interface:", ABORT); /* */ 



/* For the rest of the server initialization, create server binding */ 
/* information, advertise the server, manage endpoints, and listen for */ 
/* remote procedure calls. */ 



104 Microsoft RFC Programming Guide 

O The RpcServerRegisterlf routine is a required call to register each interface the 
server supports. The interface handle, inv_Vl_0_s_ifspec, refers to the inter 
face specification. 

The CHECK_STATUS macro is defined in the status. h file. It is an application- 
specific macro used in this book to process status values returned from RFC 
runtime calls (see Example 3-12). 

Multiple interfaces may be registered from a single server by calling the RpcSeruer- 
Registerlf routine with a different interface handle. 

The second and third arguments to the RpcServerRegisterlf call are used in com 
plex applications to register more than one implementation for the set of remote 
procedures. When only one implementation exists, these arguments are set to 
NULL. Also, in the event of a symbol name conflict between the remote procedure 
names of an interface and other symbols in your server (such as procedure 
names), you can use these arguments to assign different names to the server 
code s remote procedures. 

Creating Server Binding Information 

Server binding information is created when you select protocol sequences during 
server initialization. RFC uses protocol sequences (described in Chapter 3, How to 
Write Clients) to identify the combinations of communications protocols that RFC 
supports. Most servers offer all available protocol sequences so that you do not 
limit the opportunities for clients to communicate with the server. 

Recall that besides a protocol sequence, binding information includes a host net 
work address. A server process runs on only one host at a time, so this binding 
information is obtained from the system and not controlled in your server code. 

When a protocol sequence is selected, an endpoint is also obtained. You have sev 
eral choices when obtaining endpoints. 

Using dynamic endpoints 

Chapter 3 describes the difference between dynamic and well-known endpoints. 
Most servers use dynamic endpoints for their flexibility and to avoid the problem 
of two servers using the same endpoints. Dynamic endpoints are selected for you 
by the RFC runtime library and vary from one invocation of the server to the next. 
When the server stops running, dynamic endpoints are released and may be 
reused by the server system. 

Example 5-3 is a portion of the inventory server initialization showing the selection 
of one or all protocol sequences and dynamic endpoints. For this example, invoke 
the server with a protocol sequence argument to select a specific protocol 
sequence. If you invoke this server without an argument, the server uses all avail 
able protocols. 



Chapter 5: How to Write a Server 105 

Example 5~3- Creating Server Binding Information 

I* Registering interfaces precedes creating server binding information. */ 



/****************** CREATING SERVER BINDING INFORMATION ******************/ 
if(argc > 1) { 
status = 

RpcServerUseProtseq( /* use a protocol sequence O */ 

(unsigned char *)argv[l], /* the input protocol sequence */ 
RPC_C_PROTSEC_MAX_REQS_DEFAULT, /* (rpcdce.h) */ 

NULL /* security descriptor (not reqd) */ 

); 

CHEOK_STATUS( status, "Can t use this protocol sequence:", ABORT); 
} 
else { 

puts ("You can invoke the server with a protocol sequence argument."); 
status = 

RpcServerUseAllProtseqs ( /* use all protocol sequences */ 

RPC_C_PROTSEO_MAX_REQS_DEFAULT, /* (rpcdce.h) */ 

NULL /* security descriptor (not reqd) */ 

); 
CHECK_STATUS( status, "Can t register protocol sequences:", ABORT); 



status = 

RpcServerlnqBindings ( /* get binding information for server*/ 

&binding_vector 
); 
CHECK_STATUS ( status, "Can t get binding information:", ABORT); 



/* For the rest of the server initialization, advertise the server, */ 
/* manage endpoints, and listen for remote procedure calls. */ 

O The RpcServerUseProtseq routine is called with the chosen protocol sequence 
string. This call selects one protocol sequence on which the server listens for 
remote procedure calls. For this example, when the server is invoked, argc is 
the number. of arguments on the command line, and argv[l] is the protocol 
sequence string argument. The constant RPCjC_PROTSEQjyiAX_C^LLLS_DEFAULT 
sets the request queue size for the number of calls an endpoint can receive at 
any given moment. 

The RpcServerUseAllProtseqs routine is called to select all available protocol 
sequences on which the RFC runtime library listens for remote procedure 
calls. 

The RpcServerlnqBindings routine is a required call to obtain the set of bind 
ing handles referring to all of this server s binding information. 



1 06 Microsoft RFC Programming Guide 

Dynamic endpoints must be registered with the server system s local endpoint 
map using the RpcEpRegister routine, so that clients can look them up when they 
try to find a server. 

Using well-known endpoints 

An endpoint is well-known if it is specifically selected and assigned to a single 
server every time it runs. Well-known endpoints are more restrictive than dynamic 
endpoints because, in order to prevent your servers from using the same end- 
points as someone else, you need to register well-known endpoints with the 
authority responsible for a given transport protocol. For example, the ARPANET 
Network Information Center controls the use of well-known endpoint values for 
the Internet Protocols. 

Well-known endpoints are often employed for widely-used applications. One 
server that needs well-known endpoints is the RFC service. This service runs on 
each system hosting RFC servers, maintaining the database that maps servers to 
endpoints. When a client has a partially bound handle, and it needs to obtain an 
endpoint for its application s server, the client RFC runtime library contacts the 
server system s RFC service. In short, the RFC service is required for finding 
dynamic endpoints. For clients to contact it, the RFC service itself must have a 
well-known endpoint. 

Although you do not need to register well-known endpoints in the server system s 
endpoint map, you are encouraged to, so that clients are unrestricted in finding 
your servers. Use the RpcEpRegister routine to register endpoints in the endpoint 
map. 

Table 5-1 shows the RFC runtime routines that create server binding information 
with well-known endpoints. 

Table 5-1: Creating Binding Information with Well-known Endpoints 
RFC Runtime Routine Description 



RpcServerUseProtseqEp Uses a specified protocol sequence and well-known 

endpoint, supplied in application code, to establish 
server binding information. Even though the endpoint 
is not dynamically generated, clients do not have an 
obvious way to get it. So the server must register the 
endpoint in the server system s endpoint map. 



RpcServerUseProtseqlf 



Uses a specified protocol sequence, but well-known 
endpoints are specified in the interface definition 
with the endpoint attribute. Both clients and servers 
know the endpoints through the interface definition. 



Chapter 5: How to Write a Server 107 

Table 5-1: Creating Binding Information with Well-known Endpoints (continued) 
RFC Runtime Routine Description 



RpcSeruerUseAllProtseqsIf Uses all supported protocol sequences, but well- 
known endpoints are specified in the interface defini 
tion with the endpoint attribute. Both clients and 
servers know the endpoints through the interface def 
inition. 



Advertising the Server 

Advertising the server means that you make the binding information available for 
clients to find this server. You can advertise the server by one of the following 
methods: 

Export to a name service database. 

Store binding information in an application-specific database. 

Print or display binding information for clients. 

The method you use depends on the application, but the most common way is 
through a name service database. Binding information and the interface specifica 
tion are first exported to a server entry in the database. The information is associ 
ated with a recognizable name appropriate for the application. This information 
can now be retrieved by a client using this name. When the client imports binding 
information, the RFC runtime library compares the interface specifications of the 
client and the name service entries, to be sure the client and server are compati 
ble. 

Conventions for naming RFC server entries rely on associating a host computer 
name with the server entry name, thereby creating a unique server entry name. 
Unique server entry names allow multiple instances of a server to coexist in one 
NT domain. Although it s possible for multiple servers to share use of a single 
server entry, problems arise if the true owner of the entry removes the entry from 
the name service; binding information for all other servers is removed as well. 

Using this convention means that clients that use server entry names to find 
servers will need to know which computer a server is running on. Automatic 
clients usually seek servers based on the interface UUID so they are freed from 
having to know the server s computer name. When NT domains do not contain 
multiple instances of servers, you don t need to use the convention. 

If you plan to store your entry names in DCE CDS, you can also export a group 
entry name that is not associated with a computer name. The convention for nam 
ing RFC group entries includes the interface name. The server entry name is added 
as a member of the group. When the client imports binding information using the 
group name, the group members are searched until a compatible server entry is 
found. Microsoft RFC includes the API functions that control group and profile 



108 Microsoft RFC Programming Guide 

operations for use with DCE CDS. Note, however, that the Microsoft Locator version 
1.0 does not fully support group or profile operations. 

Example 5-4 is a portion of the inventory initialization code that uses the name 
service database to advertise the server. 

Example 5-4: Advertising the Server to Clients 

I* Registering interfaces and creating server binding information */ 
/* precede advertising the server. */ 



/*************************** ADVERTISE SERVER 



strcpy (entry_name, " / . : /inventory_" ) ; 

GetComputerNamet&hostname, &hostname_size) ; 

strcat (entry_name, hostname); 

status = 

RpcNsBindingExport ( /* export to a name service database O */ 

RPC_C_NS_SYNTAX_DEFAULT, /* syntax of entry name (rpcdce.h) */ 
(unsigned char *)entry_ name, /* name of entry in name service */ 
inv_Vl_0_s_ifspec / /* interface specification (inv.h) */ 
binding_vector, /* binding information */ 

NULL /* no object UUIDs exported */ 

); 

CHECK_STATUS( status, "Can t export to name service database:", RESUME); 



/* For the rest of the server initialization, manage endpoints and */ 
/* listen for remote procedure calls. */ 

O The RpcNsBindingExport routine exports the server binding information to a 
name service database. The constant RPC_C_NS_SYNTAX_DEFAULT establishes 
the syntax the RFC runtime library uses to interpret an entry name. (Microsoft 
RFC currently has only one syntax.) The entry name is the recognizable name 
used in the database for this binding information. 

The interface handle (inv_Vl_0_s_ifspec) is needed so interface information 
is associated with the binding information in the name service database. The 
binding vector is the list of binding handles that represents the binding infor 
mation exported. (The NULL value represents an object UUID vector. For this 
application, no object UUIDs are used.) 

The RpcNsBindingExport routine exports well-known endpoints to the name ser 
vice database along with other binding information, but, because of their tempo 
rary nature, dynamic endpoints are not exported. Performance of the name service 
will degrade if it becomes filled with obsolete endpoints generated when servers 
restart. Also, clients will fail more often trying to bind to servers of nonexistent 
endpoints. Since dynamic endpoints are not in a name service database, clients 
need to find them from another source. The next section discusses how to manage 
endpoints. 



Chapter 5: How to Write a Server 109 

Managing Server Endpoints 

When the server uses dynamic endpoints, clients need a way to find them, 
because neither the name service database nor the interface specification store 
dynamic endpoints. The endpoint map is a database on each RFC server system 
that associates endpoints with other server binding information. As a general rule, 
have your server store all endpoints (dynamic and well-known) in the endpoint 
map. If all endpoints are placed in the endpoint map, system administrators have 
an easier time monitoring and managing all RFC servers on a host system. 

When a client uses a partially bound binding handle for a remote procedure call, 
the RFC runtime library obtains an endpoint from the server system s endpoint 
map. (However, if a well-known endpoint is available in the interface specifica 
tion, the server s endpoint map is not used.) To find a valid endpoint, the client s 
interface specification and binding information (protocol sequence, host, and 
object UUID) are compared to the information in the endpoint map. When an end- 
point of an appropriate server is finally obtained, the resulting fully bound binding 
handle is used to complete the connection at that endpoint. Example 5-5 shows 
how a server registers its endpoints in the endpoint map. 

Example 5-5: Managing Endpoints in an Endpoint Map 

/* Registering interfaces, creating server binding information, and */ 
/* advertising the server precede managing endpoints. */ 



/*************************** MANAGE ENDPOINTS ****************************/ 

strcpy (annotation, "Inventory interface"); 

status = 

RpcEpRegister ( /* add endpoints to local endpoint map O */ 

inv_Vl_0_s_ifspec, /* interface specification (inv.h) */ 
binding_vector, /* vector of server binding handles */ 

NULL, /* no object UUIDs to register */ 

(unsigned char *) annotation /* annotation supplied (not required) */ 

); 

CHECK_STATUS( status, "Can t add endpoints to local endpoint map:", RESUME); 

status = 

RpcBindingVectorFree ( /* free server binding handles*/ 

&binding_vector 
); 
CHECK_STATUS( status, "Can t free server binding handles:", RESUME); 

open_inventory ( ) ; /* application specific procedure */ 



110 Microsoft RFC Programming Guide 

Example 5- 5: Managing Endpoints in an Endpoint Map (continued) 

I* For the rest of the server initialization, listen for remote */ 
/* procedure calls. */ 

O The RpcEpRegister routine registers the server endpoints in the local endpoint 
map. Use the same interface handle, binding vector, and object UUID vector 
as you used in the RpcNsBindingExport routine (see Example 5-4). An annota 
tion argument is not needed because Microsoft RFC provides no way to 
retrieve this information from the endpoint map. 

The RpcBindingVectorFree routine is a required call that frees the memory of 
the binding vector and all binding handles in it. Each call to RpcServerlnq- 
Bindings (see Example 5-3) requires a corresponding call to RpcBinding 
VectorFree. Make this call prior to listening for remote procedure calls, so the 
memory is available when remote procedure calls are processed. 

The RpcEpRegister call is required if dynamic endpoints are established with the 
RpcServerUseProtseq or RpcServerUseAllProtseqs runtime routines, because each 
time the server is started, new endpoints are created (see Example 5-3). If well- 
known endpoints are established with the RpcServerUseProtseqEp runtime routine, 
you should use the RpcEpRegister routine, because even though the endpoint may 
always be the same, a client needs to find the value. If well-known endpoints are 
established with the RpcServerUseProtseqlf or RpcServerUseAllProtseqsIf call, they 
need not be registered, because the client has access to the endpoint values 
through the interface specification. 

When a server stops running, endpoints registered in the endpoint map become 
outdated. The RFC service maintains the endpoint map by removing outdated end- 
points. However, an unpredictable amount of time exists in which a client can 
obtain an outdated endpoint. If a remote procedure call uses an outdated end- 
point, it will not find the server and the call will fail. To prevent clients from 
receiving outdated endpoints, use the RpcEpUnregister routine before a server 
stops executing. 

The only way to actively manage endpoints in the endpoint map is by using Rpc 
EpRegister and other RFC runtime routines in the server initialization code (see 
Example 5-5). 

Listening for Remote Procedure Calls 

The final requirement for server initialization code is to listen for remote proce 
dure calls. 

Many of the RFC runtime routines used in this book have an error status variable, 
used to determine whether the routine executed successfully. However, when the 
server is ready to process remote procedure calls, the RpcServerListen runtime rou 
tine is called. The RpcServerListen runtime routine does not return unless the 



Chapter 5: How to Write a Server 111 

server is requested to stop listening by one of its own remote procedures using 
the RpcMgmtStopServerListening routine. 

Any errors occurring during stub code or remote procedure execution are reported 
as exceptions, and, unless your code is written to handle exceptions, it will 
abruptly exit. You can use a set of RFC macros to help process some system 
exceptions that occur outside the application code. The macros RpcTryExcept, 
RpcExcept, and RpcEndExcept delineate code sections in which exceptions are 
controlled. If an exception occurs during the RpcTryExcept section, code in the 
RpcExcept section is executed to handle any necessary error recovery or cleanup 
such as removing outdated endpoints from the endpoint map. 

These macros are not likely to be invoked when exceptions occur within the 
server application code itself; exceptions within a server usually cause the server 
to abort before the exceptions are reported back to the application. 

The RpcExcept section contains clean-up code that does such things as remove 
outdated endpoints from the endpoint map. The RpcTryExcept and RpcExcept 
sections end with the RpcEndExcept macro. 

Example 5-6 is a portion of C code that shows how the inventory server listens for 
remote procedure calls and handles exceptions. 

Example 5-6: Listening for Remote Procedure Calls 

I* Registering interfaces, creating server binding information, */ 

/* managing endpoints, and advertising the server precede listening */ 

/* for remote procedure calls. */ 

/***************** LISTEN FOR REMOTE PROCEDURE CALLS *****************/ 
RpcTryExcept /* thread exception handling macro O */ 

{ 

status = 

RpcServerListen ( /* */ 

1, /* process one remote procedure call at a time */ 

RPC_C_LISTEN_MAX_CALLS_DEFAULT , 
NULL 
); 

CHECK_STATUS( status, "rpc listen failed:", RESUME); 

} 

RpcExcept ( RpcExcept ionCodeO ) /* error recovery and cleanup */ 
{ 

close_inventory ( ) ; /* application specific procedure */ 

status = 

RpcServerlnqBindings ( /* get binding information */ 

&binding_vector 
); 
CHECK_STATUS( status, "Can t get binding information:", RESUME); 

status = 

RpcEpUnregister ( /* remove endpoints from local endpoint map O */ 
inv_Vl_0_s_ifspec, /* interface specification (inventory. h) */ 
binding_vector, /* vector of server binding handles */ 

NULL /* no object UUIDs */ 



112 Microsoft RFC Programming Guide 

Example 5-6: Listening for Remote Procedure Calls (continued) 

); 

CHECK_STATUS( status, "Can t remove endpoints from endpoint map:", RESUME); 

status = 

RpcBindingVectorFree ( /* free server binding handles */ 

&binding_vector 
); 
CHECK_STATUS ( status , "Can t free server binding handles:", RESUME); 

puts ( " \nServer quit ! " ) ; 
} 

RpcEndExcept ; 
} /* END SERVER INITIALIZATION */ 

O The RpcTryExcept macro begins a section of code in which you expect 
exceptions to occur. For this example, the RpcTryExcept section contains 
only the RpcServerListen routine. If an exception occurs during the remote 
procedure execution, the code section beginning with the RpcExcept macro 
is executed to handle application-specific cleanup. 

@ The RpcServerListen routine is a required call that causes the runtime to listen 
for remote procedure calls. The first argument sets the number of threads the 
RFC runtime library uses to process remote procedure calls. In this example, 
the RFC runtime library can process one remote procedure call at a time. If 
your remote procedures are not thread safe, set this value to 1. 

The RpcServerlnqBindings routine obtains a set of binding handles referring 
to all of the server s binding information. 

O The RpcEpUnregister routine removes the server endpoints from the local end- 
point map. If the server registered endpoints with a call to RpcEpRegister, this 
call is recommended before the process is removed (see Example 5-5). 

The RpcBindingVectorFree routine is called to free the memory of a binding 
vector and all binding handles in it. Each call to RpcServerlnqBindings 
requires a corresponding call to RpcBindingVectorFree. 

The server initialization code for the inventory application is now complete. All of 
the server initialization code is shown in Example D-5. Table B-2 lists all the run 
time routines that servers can use. 

Writing Remote Procedures 

When writing your remote procedures, consider the issues of memory manage 
ment, threads, and client binding handles. 

Remote procedures require special memory management techniques. Suppose a 
procedure allocates memory for data that it returns to the calling procedure. In a 
local application, the calling procedure can free allocated memory because the 
procedure and calling procedure are in the same address space. However, the 



Chapter 5: How to Write a Server 113 

client (calling procedure) is not in the same address space as the server (remote 
procedure), so the client cannot free memory on the server. Repeated calls to a 
remote procedure that allocates memory, without some way to free the memory, 
will obviously waste the server s resources. 

You must manage memory for remote procedures by calling programmer-supplied 
wrapper routines for malloc and free in remote procedures. These routines enable 
the server stub to free memory allocated in remote procedures, after the remote 
procedure completes execution. 

Recall that the RpcServerListen routine in server initialization determines the num 
ber of threads a server uses to process remote procedure calls. If the server listens 
on more than one thread, the remote procedures need to be thread safe. For 
example, the remote procedures should not use server global data unless locks are 
used to control thread access. In the inventory application, when reading from or 
writing to the inventory application database, a lock may be needed so data is not 
changed by one thread while another thread is reading it. The topic of multi 
threaded application development is beyond the scope of this book. 

So far, we have used server binding handles and server binding information to 
allow clients to find servers. When a server receives a call from a client, the client 
RFC runtime library supplies information about the client side of the binding to the 
server RFC runtime library. Client binding information is used in server code to 
inquire about the client. This client binding information includes: 

The RFC protocol sequence used by the client for the call. 

The network address of the client. 

The object UUID requested by the client. This can be simply a nil UUID. 

To access client binding information in remote procedures use a client binding 
handle. If the client binding handle is available, it is the first parameter of the 
remote procedure. If you require client binding information, the procedure decla 
rations in the interface definition must have a binding handle as the first parame 
ter. No further details of client binding information are described in this book. 

Managing Memory in Remote Procedures 

In typical applications, you use the C library routines, malloc and free, or your 
own allocation scheme, to allocate and free memory that pointers must refer to. In 
RFC servers, when implementing a remote procedure that returns a pointer to 
newly allocated memory to the client, use programmer-supplied wrapper routines 
to malloc and free to manage memory in the remote procedures. The routines, 
which are named midl_user_allocate and midl_user_jree, are also called by the 
stub code to allocate and free memory. 



114 _ Microsoft RFC Programming Guide 

Example 5-7 shows how you can write the wrapper routines for malloc and free. 
Example 5- 7: Programmer-Supplied Wrapper Routines for malloc and free 

/*** midl_user_al locate / midl_user_free ***/ 

void * _RPC_API 
midl_user_al locate 



size_t size; 
{ 

unsigned char * ptr; 

ptr = malloc ( size ) ; 

return ( (void *)ptr ); 
} 

void _RPC_API 
midl_user_free 
( 

ob j ect 
) 

void * object; 
{ 

free (object) ; 
} 

Use the midl_user_allocate routine instead of the C library routine malloc, so 
bookkeeping is maintained for memory management. This also ensures that mem 
ory on the server is automatically freed by the server stub after the remote proce 
dure has completed execution. Memory allocation will not accumulate on the 
server and get out of control. 

For reference pointers, memory on the client side must already exist, so no mem 
ory management is required for remote procedures whose output parameters are 
reference pointers. After you make the remote procedure call, first the server stub 
automatically allocates necessary memory and copies the data for the reference 
pointer into the new memory. Then it calls the implementation of the remote pro 
cedure. Finally, the remote procedure completes, output data is transmitted back 
to the client stub and the server stub frees the memory it allocated. 

On both the client and server, more complex memory management occurs for 
unique pointers than for reference pointers. If a remote procedure allocates mem 
ory for an output parameter, the server stub copies and marshalls the data, then 
the stub frees the memory that was allocated in the remote procedure. When the 
client receives the data, the client stub allocates memory and copies the data into 
the new memory. It is the client application s responsibility to free the memory 
allocated by the client stub. 

Example 5-8 shows how to use the midl_user_allocate routine to allocate memory 
for unique pointers. The procedure get_part_description of the inventory 



Chapter 5: How to Write a Server 775 

application returns a string of characters representing the description of a part in 
the inventory. The call in the client is as follows: 

part_record part; /* structure for all data about a part */ 



part. description = get_part_descript ion (part. number ); 

Example 5-8: Memory Management in Remote Procedures 

paragraph get_part_description (number) 
part_num number; 

part_record *part; /* a pointer to a part record */ 

paragraph description; 

int size; 

char *strcpy ( ) ; 

if( read_part_record( number, &part) ) { 

/* Allocated data that is returned to the client must be allocated */ 
/* with the midl_user_allocate routine. */ 

size = strlen((char *)part->description) + 1; /* O */ 

description = (paragraph) midl_user_allocate ( (unsigned) size) ; /* */ 
strcpy((char *) description, (char *)part->description) ; 

else 

description = NULL; 
return (description) ; 

O An additional character is allocated for the null terminator of a string. 

The remote procedure calls the midl_user_allocate stub support routine to 
allocate memory in the remote procedure. 

When the procedure completes, the server stub automatically frees the memory 
allocated by mid l_user_a I locate calls. When the remote procedure call returns, the 
client stub automatically allocates memory for the returned string. When the client 
application code is finished with the data, it frees the memory allocated by the 
client stub as follows: 

if (part. description != NULL) 
free (part .description) ; 

For more complex memory management, there is a programmer-supplied counter 
part to the C library routine free called midl_user_Jree. 

The only time you don t use the midl_user_allocate and midl_user_free routines 
for memory management is when you use context handles. Memory allocated for 
context on the server must not use these routines because subsequent calls by the 
client must have access to the same context as previous calls. See Chapter 7 for 
more information on context handles. 



116 Microsoft RFC Programming Guide 

Allocating Memory for Conformant Arrays 

The whatare_subparts procedure of the inventory application allocates memory 
for a conformant array in a structure, and returns a copy of the conformant 
structure to the client. The whatare_subparts procedure is declared in the interface 
definition as follows: 

typedef struct part_list{ /* list of part numbers */ 

long size; /* number of parts in array */ 

[size_is(size) ] part_num numbers [*]; /* conformant array of parts */ 

} part_list; 



void whatare_subparts ( /* get list of subpart numbers for a part */ 

[in] part_num number, 

[out] part_list **subparts /* the structure containing the array */ 
); 

Output pointer parameters are reference pointers, which must have memory allo 
cated in the client prior to the call. Therefore, you need a unique pointer in order 
for new memory to be automatically allocated by the client stub for the ** sub- 
parts structure when the whatarejsubparts procedure returns. A pointer to a 
pointer is required so that the reference pointer points to a full pointer, which in 
turn points to the structure. 

Example 5-9 shows how to allocate memory in the remote procedure for a confor 
mant structure. The call in the client is as follows: 

part_record part; /* structure for all data about a part */ 

part_list *subparts; /* pointer to parts list data structure */ 



whatare_subparts (part. number, &subparts) ; 

Example 5~9: Conformant Array Allocation in a Remote Procedure 

void whatare_subparts (number, subpart_ptr) 
part_num number; 
part_list **subpart_ptr; 
{ 

part_record *part; /* pointer to a part record */ 

int i; 

int size; 

read_part_record( number, &part) ; 

/* Allocated data that is output to the client must be allocated with */ 
/* the midl_user_allocate stub support routine. Allocate for a part_list */ 
/* struct plus the array of subpart numbers. Remember the part_list */ 
/* struct already has an array with one element, hence the -1. */ 

size = sizeof (part_list) 

+ (sizeof (part_num) * (part->subparts.size-l) ) ; /* O */ 



Chapter 5: How to Write a Server 117 

Example 5-9: Conformant Array Allocation in a Remote Procedure (continued) 

*subpart_ptr = (part_list *)midl_user_allocate( (unsigned) size) ; /* */ 

/* fill in the values */ 

(*subpart_ptr) ->size = part->subparts.size; 

for(i =0; i < (*sutpart_ptr) ->size; i++) 

( *subpart_ptr ) ->numbers [ i ] = part->subparts . numbers [ i ] ; 
return; 
} 

O The allocated memory includes the size of the conformant structure plus 
enough memory for all the elements of the conformant array. The conformant 
structure generated by the MIDL compiler already has an array of one element, 
so the new memory allocated for the array elements is one less than the num 
ber in the array. 

Use the RFC stub support routine midl_user_allocate to allocate memory so 
bookkeeping is maintained for memory management, and so the server stub 
automatically frees memory on the server after the remote procedure com 
pletes execution. 

When the data for the conformant structure is returned to the client, the client stub 
allocates memory and copies the data into the new memory. The client application 
code uses the data and frees the memory allocated, as follows: 

for(i =0; i < subparts->size; i++) 

printf ( " %ld " , subparts->numbers [ i ] ) ; 

printf ("\nTotal number of subparts:%ld\n" , subparts->size) ; 
free(subparts) ; /* free memory allocated for conformant structure */ 

Compiling and Linking Servers 

Figure 5-2 shows the files and libraries required to produce an executable server. 
When complex data types are used, the MIDL compiler produces the server stub 
auxiliary file (appl^y.c) when the interface is compiled. The auxiliary file contains 
data marshalling procedures that can be used by other interfaces. No stub auxiliary 
files are produced for the inventory application. Example 5-10 shows the portion 
of a makefile that: 

Compiles the C language stubs and server code along with the header file 
producing server object files. 

Links the server object files to produce the executable server file. 



118 



Microsoft RFC Programming Guide 



Write server application files 
containing initialization code 
and the remote procedures. 

Include the header files 
produced by interface 
compilation. 



Generate client application 
and stub object files. 



Use the server stub and 
auxiliary files produced 
by compilation. 



Create the executable server 
file by linking the server 
application, stub, and 
auxiliary object files with the 
Microsoft RFC library. 



Text 
Editor 




Linker 



server 



Figure 5-2. Producing a server 

Example 5-10: Using a Makefile to Compile and Link a Server 

# FILE NAME: Makefile 

# Makefile for the inventory application 
# 

# definitions for this make file 
# 

APPL=inv 

NTRPCLIBS=rpcrt4 . lib rpcns4.1ib libont.lib kerne!32.1ib 

! include <ntwin32.mak> 

## NT c flags 

cflags = -c -WO -Gz -D_X86_=1 -CWIN32 -EMT /nologo 



Chapter 5: How to Write a Server 119 

Example 5~10: Using a Makefile to Compile and Link a Server (continued) 

## NT nmake inference rules 

$(cc) $(cdebug) $(cflags) $(cvarsmt) $< 
$ (cvtomf ) 



# 

# SERVER BUILD 
# 

server : server . exe 

server.exe: server. obj manager. obj invntry.obj $(APPL)_s.obj $(APPL)_x.obj 
$(link) $(linkdebug) $(conflags) -out : server . exe -map: server. map \ 

server . obj manager . obj invntry . obj $ ( APPL ) _s . obj $ ( APPL ) _x . obj \ 

$(NTRPCLIBS) 



# client and server sources 
client. obj: client. c $(APPL).h 
manager . obj : manager. c $(APPL).h 
server. obj: server. c $(APPL).h 
invntry.obj: invntry. c $(APPL).h 



In this Chapter: 

Naming 

DefaultEntry 

Server Entries 

Some Rules for Using 
the Microsoft Locator 





Using a Name Service 



We have seen in earlier chapters that clients query a name service to find a host 
where a server is running. We have set up our environment in a simplistic, if not 
inconvenient, manner so that we could avoid discussing details about the name 
service. For instance, in Chapter 1, Overview of an RFC Application, our arithmetic 
server used a simple server entry name. While this simple name is easy to create 
and use, it makes it difficult for an NT domain to accommodate other identical 
servers because they ll all be exporting their binding information to the same entry 
name in the name service. 

In a production environment, you don t want to restrict the number of servers you 
can have in a domain. That would defeat the purpose of the name service, which 
is to allow servers to be moved, added, and removed without affecting end-users. 

In this chapter, we discuss how to use a name service to provide multiple servers 
in your domain, which increases reliability and availability. You accomplish this by 
giving a server different names when it runs on different hosts. This is necessary 
because each server should be uniquely identified in the name service. Towards 
the end, we discuss some rules and caveats for using the Microsoft Locator. 

In DCE, the Cell Directory Service uses group entries and profile entries as a way 
to organize servers and control a client s search for server entries. The Microsoft 
Locator Version 1.0 does not support the use of CDS group entries or profile 
entries. However, Microsoft RFC includes group and profile routines in its runtime 
library for compatibility with DCE, for situations when you are running on a net 
work where other machines have DCE and you want to store binding information 
in CDS. 



121 



122 Microsoft RFC Programming Guide 



Naming 



Microsoft RFC supplies the Locator as the name service used by Microsoft RFC 
applications to locate servers. Servers store their binding information in the Loca 
tor s RFC name service database where it can be retrieved by clients. Clients then 
use the binding information to connect to servers. 

Because so many servers can exist in a Locator s domain, the collection of names 
is hierarchically organized. In DCE, this hierarchy really corresponds to the way 
that the name service stores the entries in its distributed database. But with the 
Microsoft Locator, the names are simply strings. The hierarchy is merely an appear 
ance, just for the convenience of the users for instance, so that related servers 
can have similar names. But it is still useful. 

Here are examples of entry names in the Locator: 

/. . . /manufacturing/ services /graphics/ servers /gif_server 
/ . : /services /graphics/ servers /gif_server 

Names like those in the example can help organize servers logically so clients can 
find them by using consistent naming patterns. 

The above example shows two ways to name a server. The first example includes 
the name of the domain, manufacturing, as part of the name. The second exam 
ple avoids using the / . . . /manufacturing prefix by beginning the name with 
/ . : . The domain name prefix is implicit because a Locator maintains entry names 
only from its own domain in this case, the manufacturing domain. The second 
example allows server portability across domains that use similar naming conven 
tions. 

When a server starts, it can export its name to the Locator database along with its 
protocol sequence and host address. Unlike DCE, Microsoft RFC does not provide 
independent tools for administrators to manage the entries. Consequently, your 
applications must do any needed entry management. 



DefaultEntry 



Recall that if you use automatic binding, the client stub finds a server for you. By 
default, a client searches the Locator for a server offering an interface with a 
matching interface UUID. You can override this behavior by setting the Default- 
Entry Windows NT registry value to a valid server entry name. 

You can set the DefaultEntry on Windows NT client using the regedt32 program. 
In the HKEY_LOCAL_MACHINE on Local Machine window, you should select 
SOFTWARE/Microsoft/I^>c/NameService. 

If the DefaultEntry value exists in the right portion of the window, double click 
on it to invoke a dialog box for typing in the server entry name. Type in the name 
and then click on OK. 



Chapter 6: Using a Name Service 



123 



If the Def aultEntry value does not exist, you can add it by pulling down the Edit 
menu and clicking on Add Value .... In the Value Name field, type Def aultEntry. 
Then click on OK. In the resulting String dialog box, type in the server entry name 
and then click on OK. 

You can set the Def aultEntry on Microsoft DOS and Windows 3.1 clients by 
using a text editor to add a line like the following to the C:\RPCREG.DAT configu 
ration file. 

\Root\Software \Microsoft\Rpc \NameService\Def aultEntry=/ . : /arithmetic_RIGEL. 

Server Entries 

A name service server entry stores binding information for an RFC server. Figure 
6-1 depicts server entries in the name service database. 



Server entry 

Interface identifier 
Binding information 



Server entry 

Interface identifier 
Binding information 



Figure 6-1. Server entries in the name service database 

A server entry contains the following information: 

An interface identifier consists of an interface UUID and a version number. 
During the search for binding information, RFC name service routines use this 
identifier to determine if a compatible interface is found. 

Binding information is the information a client needs to find a server. It 
includes one or more sets of protocol sequence and host address combina 
tions. Well-known endpoints can also be part of the binding information, but 
dynamic endpoints cannot. 



124 Microsoft RFC Programming Guide 

Some applications use optional object UUIDs to identify application-specific 
objects or resources. 

A reasonable naming scheme for server entries combines the host system name 
and a meaningful definition of what the server offers. For example, the arithmetic 
interface on a host system named RIGEL can have the following name service 
entry: 

/ . : /arithmetic_RIGEL 

In this way, using a simple convention that all servers can follow, you are assured 
that each server at your site has a unique name as long as you have only one 
server per host. Normally, a host should only provide one server for an interface. 
You can increase the number of clients a server handles by increasing the number 
of threads a server can spawn. In the unusual case in which your system has mul 
tiple servers offering the same interface, you need to distinguish each server with 
separate name service entries and unique entry names. For example, one server 
might be / . : /arithmeticl_RIGEL, and another / . : /arithmetic2_RIGEL. 

If you structure your entry names to included embedded host names, using the 
host name again in the right-most part of the name is redundant. In this case, the 
arithmetic application might have the following entry name: 

/ . : /product_developnent/test_servers/host_RIGEL/arithmetic 

When your client uses the name service to find a server, it does an import or 
lookup for binding information, starting at an entry name known to be in the 
database. Entry names must be supplied to you in one of two ways: by the name 
service administrator who knows the name service database organization, or by 
the server administrator. You use RFC name service routines to search the name 
service database. These routines compare the client s interface identifier with inter 
face identifiers in the database. When there is a match and the entry contains com 
patible binding information, the compatible binding information is returned. 

Figure 6-2 shows how the arithmetic application uses a server entry in the name 
service database. The arithmetic server uses the RpcNsBindingExport runtime rou 
tine to export binding information to the / . : /arithmetic_RIGEL server entry. 
The arithmetic server s use of RpcNsBindingExport is shown in Example 1-4 in 
Chapter 1. 

The arithmetic client uses the automatic binding method, so the client stub finds 
the server without using the server entry name. Instead, the automatic client 
requests a binding for an interface with a matching interface UUID. When client 
application code assists the search, as when using implicit or explicit binding 
methods, you can set a programmer-supplied environment variable such as 
ARITHMETIC_SERVER_ENTRY, to something like / . : /arithmetic_RIGEL on the 
client system SIRIUS, so the client stub has a name to search for in the name ser 
vice. In this example, the name service simply searches for the server entry name 



Chapter 6: Using a Name Service 



125 



I . : /arithmetic_RIGEL. The server entry s binding information is returned, and 
the remote procedure call is completed. 



System SIRIUS 




Import 



System RIGEL 




Arithmetic 
Server 



O Export 



Sys 


tern QUASAR 


Nai 


ne Service Database 






A:/arithmetic_RIGEL 



















Figure 6-2. A simple use of a name service database 

Creating a Server Entry and Exporting 
Binding Information 

Microsoft RFC offers flexible ways for servers to construct server entry names. A 
name can be hard-coded in the server itself, but this method makes it difficult to 
change a server name because the server must be recompiled. To make your 
server more portable, you can specify a server name outside the program by set 
ting an environment variable used by the server. For instance, you can use a batch 
file to set a server-specific environment variable and then start the server. 

@REM FILE NAME: arith.bat 

ECHO OFF 

set ARITHMETIC_SERVER_ENTRY=/ . : /arithmetic_rigel 

server 



The server constructs the entry name using the WIN32 API getenv routine to read in 
the environment variable. The server then uses the NSI routine RpcNsBinding- 



126 Microsoft RFC Programming Guide 

Export to export binding information to the name service entry. If an entry does 
not already exist, the Locator creates one for you. 

entry_name = (unsigned char *)getenv("ARITHMETIC_SERVER_ENTRY") ; 

status = 

RpcNsBindingExport ( /* export entry to name service database */ 

RPC_C_NS_SYNTAX_DEFAULT, /* syntax of the entry name (rpcdce.h) */ 

entry_name, /* entry name for name service */ 

arith_ServerIf Handle, /* interface specification (arith.h) */ 

binding_vector, /* the set of server binding handles */ 
NULL 

); 

CHECK_STATUS( status, "Can t export to name service database", ABORT); 

Alternatively your server can use the WIN32 API getcomputername routine to read 
the computer name and append it to a string that is associated with the ARITH- 
METIC_SERVER_ENTRY environment variable. This method can make servers even 
more portable because you don t have to modify the .BAT file if you move the 
server to a different host. 

EWDRD hostname_size=STRINGLEN; /* required by GetComputerName */ 



strcpy (entry_name, "ARITHMETIC_SERVER_ENTRY" ) ; 

GetComputerName ( khostname , &hostname_size) ; 

strcat (entry_name, hostname); 

status = 

RpcNsBindingExport ( /* export to a name service database */ 

RPC_C_NS_SYNTAX_DEFAULT, /* syntax of entry name (rpcdce.h) */ 
(unsigned char *)entry_name, /* name of entry in name service */ 
inv_ServerIf Handle, /* interface specification (inv.h) */ 
binding_vector, /* binding information */ 

NULL /* no object UUIDs exported */ 

); 

CHECK_STATUS( status, "Can t export to name service database:", RESUME); 

If you expect the server to be removed from service for a long period of time or 
even permanently, you should remove the server binding information from the 
name service using the RpcNsBindingUnexport runtime routine. 

Some Rules for Using the Microsoft Locator 

When your Windows NT domain is large and contains several Advanced Servers, 
the Locator does not always work smoothly. Changes to the database can some 
times result in inconsistencies. 

A Windows NT domain is a group of users and their systems sharing common 
security and administration. A domain consists of one domain controller which 
maintains the master copy of the domain s user and group database. The controller 
also stores the master copy of the Microsoft Locator. 



Chapter 6: Using a Name Service 727 

Domains should also contain one or more Windows NT Advanced Servers which 
maintain copies of the master databases stored on the domain controller. The Win 
dows NT Advanced Servers in the domain query the domain controller every five 
minutes asking whether changes have been made. The controller sends just the 
changes to the requesting server, minimizing network traffic. If the domain con 
troller becomes unavailable for some reason, for example it crashes, a Windows 
NT Advanced Server in the domain is promoted to be the new domain controller. 
If the new controller s RFC name service database is not up-to-date, missing entries 
must be re-exported by their servers to the new controller. Consequently, out-of- 
date data tends to stay out of date. 

Domain controllers also maintain group entry information while Windows NT 
Advanced Servers do not. When a server is promoted to be the new domain con 
troller, group entries that existed before the promotion are lost. Consequently, 
Microsoft encourages users to rely on server entries rather than group entries. 

The domain controller and Windows NT Advanced Servers maintain the RFC name 
service database in transient memory rather than in a file. This model cannot guar 
antee the integrity of the database structure. If the domain controller crashes, all 
unpropagated server entries and all group entries must be reconstructed. 




In this Chapter: 

The Remote _flle 
Application 

Declaring Context in 
an Interface 
Definition 

Using a Context 
Handle in a Client 

Managing Context in 
a Server 




Some applications require that a server maintain information between remote pro 
cedure calls. This is called maintaining context (or maintaining state). Global data 
is one way a local application can maintain information between procedure calls. 
In a distributed application, however, the client and server are in different address 
spaces, so the only data common to each are passed as parameters. Even if a set 
of remote procedures use server global data, there is nothing to prevent more than 
one client from making calls that modify the data. A context handle is the mecha 
nism that maintains information on a particular server for a particular client. An 
active context handle refers to valid (non-null) context, and includes binding infor 
mation because a specific server maintains information for a particular client. 

The Remote _file Application 

The rfile application is a simple file transfer example that copies text from the 
client to the server. A client uses a context handle to refer to server context. The 
server context is the file handle used by remote procedures to open, write, and 
close the file. In this application, the filename on the server may be the same or 
different from the filename on the client, but the server does not overwrite an 
existing file on the server system. 

If you do not select any filenames, this application uses standard input (stdiri) of 
the client and standard output (stdouf) of the server to transfer a message from the 
client to the server. The complete rfile application is shown in Appendix E, The 
Rfile Application. 



129 



Microsoft RFC Programming Guide 



Declaring Context in an Interface Definition 

A file handle in a local application is analogous to a context handle in a dis 
tributed application. The information a file handle refers to is maintained by the C 
library and the operating system, not your application. You call some library rou 
tines to open or close the file, and other routines to read from or write to the file. 

A context handle is maintained by the stubs and RFC runtime library, not by your 
application code. What you have to write is a remote procedure that returns an 
active context handle, and one that frees the context when you are finished with 
it. Other remote procedures can access or manipulate the active context. 

Example 7-1 shows how to define context handles in the rfile interface defini 
tion. 

Example 7-1: Defining Context Handles 

I* FILE NAME: rfile. idl */ 
[ 

uuid(A61E4024-A53F-101A-BLAF-08002B2E5B76), 
version (1.0) , 
pointer_default (unique) 
] 

interface rfile /* file manipulation on a remote system */ 

{ 

typedef [context_handle] void *filehandle; /* O */ 

typedef byte bufferf]; 

filehandle remote_open( /* open for write ) */ 

[in] handle_t binding_h, /* explicit primitive binding handle */ 

[in, string] char name[], /* if name is null, use stdout in server */ 

[in, string] char mode[] /* values can be "r", "w", or "a" */ 

); 

long remote_send( 

[in] filehandle fh, /* */ 

[in, max_is(max)] buffer buf, 

[in] long max 
); 

void remote_close ( 

[in, out] filehandle *fh /* O */ 



To define a context handle data type, apply the context_handle attribute to 
a void * type (or a type that resolves to void *) in a type definition. If the 
client-server communication breaks down or the client fails, a context handle 
data type allows the server to automatically clean up the user-defined context 
with a call to a context rundown procedure. If a context handle is applied in 
a type definition, then the server application developer must write a context 
rundown procedure. 



Chapter 7: Context Handles 737 

@ At least one remote procedure initializes the context handle and returns it to 
the client for later use. A procedure returning a context handle result always 
returns a new active context handle. Also, if a parameter is an out-only con 
text handle, the procedure creates a new active context handle. 

A procedure with a context handle parameter that is input only must use an 
active context handle. 

When the client application is finished with the server context, the context 
must be freed. 

If the context handle is null upon return from a procedure, the remote procedure 
on the server has freed the context and the client stub has freed the context han 
dle. A remote procedure that frees a context handle requires the parameter to have 
the in directional attribute so the server can free the context, and the out direc 
tional attribute so the client stub can also free the client s copy of the context han 
dle. 

Using a Context Handle in a Client 

The client uses a context handle to refer to the server context through the remote 
procedure calls. In the client, the context handle refers to an opaque structure. 
This means that the data is hidden and cannot be manipulated by the client appli 
cation code. The context handle can be tested for null, but not assigned any val 
ues by the client application. The server code accomplishes all context 
modification, but the status of the context is communicated to the client through 
the context handle. The client stub manipulates the context handle in the client on 
behalf of the server. Example 7-2 shows a typical sequence of remote procedure 
calls when using context handles. 

Example 7-2: Using a Context Handle in a Client 

/* FILE NAME: client. c */ 

#include <stdio.h> 

#include <stdlib.h> 

#include <string.h> 

#include "rfile.h" 

#define MAX 200 /* maximum line length for a file */ 

main(argc, argv) 

int argc; 

char *argv [ ] ; 

{ 

FILE *local_fh; /* file handle for client file input */ 

char host [100]; /* name or network address of remote host */ 
char remote_name[100] ; /* name of remote file */ 

rpc_binding_handle_t binding_h; /* binding handle */ 

filehandle remote_fh; /* context handle */ 

buffer *buf_ptr; /* buffer pointer for data sent */ 

int size; /* size of data buffer */ 

get_args(argc, argv, &local_fh, host, (char *)remote_name) ; 



Microsoft RFC Programming Guide 



Example 7-2: Using a Context Handle in a Client (continued) 

#ifndef LOCAL 

if (do_string_binding(host, &binding_h) < 0) { /* O */ 

f print f (stderr, "Cannot get binding\n" ) ; 

exit(l); 
} 
ttendif 

remote_fh = remote_open(binding_h, remote_name, (char *)"w"); /* */ 
if (remote_fh == NULL) { 

fprintf (stderr, "Cannot open remote file\n"); 

exit(l); 



/* The buffer data type is a conformant array of bytes; */ 
/* memory must be allocated for a conformant array. */ 
buf_ptr = (buffer *)nialloc( (MAX+1) * sizeof (buf f er) ) ; 

while ( fgets((char *)buf_ptr, MAX, local_fh) != NULL) { 

size = (int) strlen( (char *)buf_ptr) ; /* data sent will not include \0 */ 
if( remote_send(remote_fh, (*buf_ptr) , size) < 1) { /* */ 

fprintf (stderr, "Cannot write to remote file\n"); 
exit(l) ; 



remote_close(&remote_fh) ; /* O */ 

} 

O Before a context handle becomes valid, a client must establish a binding with 
the server that will maintain the context. For the explicit or implicit binding 
methods, your application has to perform this step. For the automatic binding 
method, binding occurs in the client stub during the first remote procedure 
call. Then, to find the server after the context handle is established, subse 
quent calls use it instead of a binding handle. The do_string_binding proce 
dure is an application-specific procedure that creates a binding handle from a 
host input and a generated protocol sequence. It is shown in Chapter 3, How 
to Write Clients. 

The symbol LOCAL is used in applications in this book, to distinguish compil 
ing this client to test in a local environment, from compiling to run in a dis 
tributed environment. 

To establish an active context handle, a procedure must either return the con 
text handle as the procedure result or have only the out directional attribute 
on a context handle parameter. The context handle cannot be used by any 
other procedure until it is active. For the remote_open procedure, an explicit 
binding handle is the first parameter. 

Procedures using only an active context handle can be employed in any way 
the application requires. Note that for a procedure to use the context handle, 
a context handle parameter must have at least the in attribute. The 
remote_send procedure sends a buffer of text data to the server, where the 
remote procedure writes the data to the file referred to by the context handle. 



Chapter 7: Context Handles 



133 



O When you have finished with the context, free the context handle to release 
resources. 

Binding Handles and Context Handles 

A procedure can use a binding handle and one or more context handles. How 
ever, make sure all handles in the parameter list refer to the same server because a 
remote procedure call cannot directly refer to more than one server at a time. 

Table 7-1 shows how to determine whether a binding handle or a context handle 
directs the remote procedure call to the server. 



Table 7-1: Binding Handles and Context Handles in a Call 

Other 
Procedure Format Parameters 



proc( . . . ) 



proc( [in] bh . . . ) 



proc( . . . [in]ch . . . 



proc( . . . [in,out]ch 



No binding or con 
text handles 

May include context 
handles 

May include other 
context handles but 
no binding handles 



May include other 
input/output or out 
put-only context 
handles but no 
binding handles or 
input-only context 
handles 



Handle that 
Directs Call 

The interface-wide auto 
matic or implicit binding 
handle directs the call. 
The explicit binding 
handle, bh, directs the 
call. 

The first context handle 
that is an input-only pa 
rameter directs the call. 
If it is null, the call will 
fail. 

The first non-null con 
text handle that is an in 
put/output parameter di 
rects the call. If all are 
null, the call will fail. 



Managing Context in a Server 

When more than one remote procedure call from a particular client needs context 
on a server, the server stub and server application maintain the context. This sec 
tion describes how to implement the procedures that manipulate context in a 
server. 

A server context handle refers to context in the server code. It communicates the 
status of the context back to the client. From the perspective of the server 



134 Microsoft RFC Programming Guide 

developer, a server context handle is an untyped pointer that can be tested for 
null, assigned null, or assigned any value. 

Once the server context handle is active (non-null), the server maintains the con 
text for the particular client until one of the following occurs: 

The client performs a remote procedure call that frees the context. 

The client terminates while context is being maintained. 

Communication breaks between the client and server. 

If the client terminates or the client-server communication breaks while the server 
maintains context, the server s RFC runtime library may invoke a context rundown 
procedure to clean up user data. 

Writing Procedures That Use a Context Handle 

Example 7-3 shows how to implement a procedure that obtains an active context 
handle, one that uses the active context handle, and one that frees the context 
handle. 

Example 7~3: Procedures That Use Context Handles 

I* FILE NAME: manager. c */ 
ttinclude <stdio.h> 
ttinclude <string.h> 
# include <io.h> 
#include <errno.h> 
ttinclude "rfile.h" 

filehandle remote_open(binding_h, name, mode) /* O */ 

rpc_binding_handle_t binding_h; 

char name [ ] ; 

char mode [ ] ; 

{ 

FILE *FILEh; 

if (strlen( (char *)name) == 0) /* no file name given */ 

if (strcmpt (char *)mode, "r") == 0) 

FILEh = NULL; /* cannot read nonexistent file */ 

else FILEh = stdout; /* use server stdout */ 

else if (access ( (char *)name, 0) == 0) /* file exists */ 

if (strcmpt (char *)mode, "w" ) == 0) 

FILEh = NULL; /* do not overwrite existing file */ 

else FILEh = fopen((char *)name, (char *)mode) ; /* open read/append */ 

else /* file does not exist */ 

if (strcmpt (char *)mode, "r") == 0) 

FILEh = NULL; /* cannot read nonexistent file */ 

else FILEh = fopen((char *)name, (char *)mode) ; /* open write/append */ 

return ( (filehandle) FILEh ); /* cast FILE handle to context handle */ 



Chapter 7: Context Handles 135 

Example 7-3: Procedures That Use Context Handles (continued) 

long int remote_send(fh, buf, max) /* */ 

filehandle fh; 

buffer buf; 

long int max; 

{ 

/* write data to the file (context) , which is cast as a FILE pointer */ 

return( fwrite(buf, max, 1, fh) ) ; 



void remote_close(fh) /*)*/ 

filehandle *fh; /* the client stub needs the changed value upon return */ 

{ 

if( (FILE *) (*fh) != stdout ) 
f closet (FILE *) (*fh) ) ; 

(*fh) = NULL; /* assign NULL to the context handle to free it */ 

return; 
} 

O Initialize data as required by later calls, and assign the application context to 
the server context handle. In this example, a file handle is obtained and 
assigned to the context handle when the procedure returns. Outside of the 
server process this file handle is meaningless, but when the client makes sub 
sequent calls, the server uses this file handle to write data or close the file. 

Use the server context handle parameter defined with the in directional 
attribute. This procedure must have an active context handle as input. For this 
example, the buffer (buf) of max number of items is written to the file. Cast 
the server context handle to the context s data type (FILE *). 

) Free the context by using a procedure whose context handle parameter is 
defined with the in and out directional attributes. This procedure must have 
an active context handle as input. To free the context, assign null to the server 
context handle and use the C library procedure free or a corresponding 
method to clean up your application. In this example, before freeing the file 
handle, the context is tested to be sure it does not refer to stdout. The server 
context handle is cast to the context s data type. 

When this procedure returns to the client, the client stub automatically frees 
the context handle on the client side if the server context handle is set to 
NULL. 

If memory must be allocated for the context, use the C library procedure malloc or 
another method. Do not use the stub support procedure midl_user_allocate 
because you do not want the allocated memory to be automatically freed by the 
server stub after the procedure completes. 



Microsoft RFC Programming Guide 



Writing a Context Rundown Procedure 

A context rundown procedure allows orderly cleanup of the server context. The 
server RFC runtime library automatically calls it when a context is maintained for a 
client, and either of the following occurs: 

The client terminates without requesting that the server free the context. 

Communication breaks between the client and server. 

In our example, the interface definition defines the following type as a context 
handle: 

typedef [context_handle] void *filehandle; 

Example 7-4 shows the context rundown procedure to implement in the server 
code. The procedure name is created by appending _rundown to the type name 
(filehandle). The procedure does not return a value and the only parameter is the 
context handle. In this example, when the context rundown procedure executes, it 
closes the file that represents the context. 

Example 7-4: A Context Rundown Procedure 

I* FILE NAME: crndwn.c */ 
#include <stdio.h> 
#include "rfile.h" 

void filehandle_rundown(remote_fh) 

filehandle remote_fh; /* the context handle is passed in */ 

{ 

fprintf (stderr, "Server executing context rundown\n" ) ; 

if( (FILE *)remote_fh != stdout ) 

f close ( (FILE *)remote_fh ) ; /* file is closed if client is gone */ 

remote_fh = NULL; /* must set context handle to NULL */ 

return; 
} 

The context handle must be defined as a type in the interface definition in order 
for the server runtime to automatically call the context rundown procedure. And if 
you define the context handle as a type, then you must implement a context run 
down procedure in the server. 




MIDI and ACF Attributes 
Quick Reference 



All MIDI attributes are shown in Tables A-l through A-8, and all ACF attributes are 
shown in Table A-9, but not all are demonstrated in this book. 



Table A-l: MIDI Interface Header Attributes 
Attribute Description 



uuid ( uuid_string) 



version (major. minor) 
pointer_default (kind) 



endpoint (string) 



local 



A universal unique identifier is generated by the 
uuidgen utility and assigned to the interface to distin 
guish it from other interfaces. This attribute is re 
quired unless the local attribute is used. 
A particular version of a remote interface is identified 
when more than one version exists. 
The default treatment for pointers is specified. Kinds 
of pointers include reference (ref) and unique 
(unique). 

An endpoint is a number representing the transport- 
layer address of a server process. This attribute spec 
ifies a well-known endpoint on which servers will lis 
ten for remote procedure calls. Well-known end- 
points are usually established by the authority re 
sponsible for a particular transport protocol. 
The MIDI compiler can be used as a C language 
header file generator. When this attribute is used, all 
other interface header attributes are ignored and no 
stub files are generated by the MIDL compiler. 



137 



138 



Microsoft RFC Programming Guide 



Table A-2: MIDI Array Attributes 
Attribute Description 



string 



An array is specified to have the properties of a string. 



size_is(size) 



max_is (max) 



first_is( first) 



last_is(Iast) 



length_is (length) 



Conformant Array Attributes 
A variable is defined in the interface definition and used 
at runtime to establish the array size. 

A variable is defined in the interface definition and used 
at runtime to establish the maximum index value. 

Varying Array Attributes 

A variable is defined in the interface definition and used 
at runtime to establish the lowest index value of transmit 
ted data. The value is not necessarily the lowest bound 
of the array. 

A variable is defined in the interface definition and used 
at runtime to establish the highest index value of trans 
mitted data. The value is not necessarily the highest 
bound of the array. 

A variable is defined in the interface definition and used 
at runtime to establish the number of elements transmit 
ted for a portion of the array. 



Table A- 3: MIDL Pointer Type Attributes 
Attribute Description 

unique A pointer is specified as a unique pointer with the unique attribute. 
Unique pointers provide basic indirection and they can be null. 
Unique pointers cannot contain cycles or loops. 

ref A pointer is specified as a reference pointer with the ref attribute. 

This attribute gives basic indirection without the implementation over 
head associated with unique pointers. 

string A pointer is specified as pointing to a string. 



Appendix A: MIDI and ACF Attributes Quick Reference 



139 



Table A- 4: MIDI Data Type Attributes 
Attribute Description 



pointer type attributes 



context_handle 



handle 



transmit_as ( type) 



A data type with a visible pointer operator may be speci 
fied with a pointer type attribute (See Table A-3). 
A state is maintained on a particular server between re 
mote procedure calls from a specific client by maintaining 
a context handle as a data type. The context handle iden 
tifies the state. 

A defined data type is specified as a customized handle 
so that the client-server binding information is associated 
with it. 

A data type that is manipulated by clients and servers 
may be specified so that it is converted to a different data 
type for transmission over the network. 



Table A-5: MIDI Structure Member Attributes 

Description 



Attribute 

array attributes 



pointer type attributes 



ignore 



A structure member can have array attributes if it has ar 
ray dimensions or a visible pointer operator. A structure 
member that has a visible pointer operator and the 
size_is or max_is attribute defines a pointer to a con 
formant array, not an array structure member (see Table 
A-2). 

A structure member can have a pointer type attribute if it 
has a visible pointer operator (see Table A-3). 
Do not transfer the data in this structure member (a 
pointer) during a remote procedure call. This can save 
the overhead of copying and transmitting data to which 
the pointer refers. 



Table A-6: MIDI Union Case Attributes 
Attribute i Description 



pointer type attributes 



A union case can have a pointer type attribute if it has a 
visible pointer operator. See Table A-3. 



140 



Microsoft RFC Programming Guide 



Table A- 7: MIDI Procedure Parameter Attributes 



Attribute 



Description 



in 

out 

array attributes 

pointer type attributes 
context_handle 



The parameter is input when the remote procedure is 
called. 

The parameter is output when the remote procedure re 
turns. 

A parameter with array dimensions can have array at 
tributes. A conformant array is a procedure parameter 
with a visible pointer operator and the size_is or 
max_is attribute (see Table A-2). 

A parameter with a visible pointer operator can have a 
pointer type attribute. See Table A-3. 

A parameter that is a void * type can have the context 
handle attribute. 



Table A-8: MIDI Procedure Attributes 
Attribute Description 



string 

ptr 

unique 
context handle 



Procedure Result Attributes 



A procedure result is specified to have the properties of a 
string with the string attribute. 

A procedure that returns a pointer result always returns a full 
pointer. It may be specified with the ptr attribute but this is 
not necessary. Full pointers provide basic indirection and they 
can be null. They can also contain cycles or loops. 
Unique pointers provide basic indirection and they can be 
null. Unique pointers cannot contain cycles or loops. Unique 
pointers can be specified with the unique attribute. 
A procedure returns a context handle result in order to indi 
cate a state on a particular server, which is then referred to in 
successive remote procedure calls from a specific client. 



Table A -9: ACF Attributes 
Attribute 



Description 



Binding Methods 



auto_handle 

iirplicit_handle ( type name) 
explicit_handle ( type name) 



The automatic binding method is selected. 
The implicit binding method is selected. 
The explicit binding method is selected. 



Appendix A: MIDI and ACF Attributes Quick Reference 141 

Table A-9: ACF Attributes (continued) 



Exceptions as Parameters 



corrm_status Names a parameter or the procedure result to 

which a status code is written if a communica 
tion error is reported by the client runtime to 
the client stub. The client remote procedure 
call must include the error_status_t data 
type in its argument list. If an error is report 
ed and this attribute and error_status_t da 
ta type are not used, the client stub raises an 
exception. 

fault_status Names a parameter or the procedure result to 

which a status code is written if an error is re 
ported by the server runtime to the server 
stub, an exception occurs in the server stub, 
or an exception occurs in the remote proce 
dure. If an error is reported and this attribute 
is not used, the client stub raises an excep 
tion. 

Excluding Unused Procedures 
code All or selected procedures from the interface 

have the associated client stub code generated 

by the MIDI compiler, 
nocode All or selected procedures from the interface 

do not have the associated client stub code 

generated by the MIDL compiler. 




RFC Runtime Routines 
Quick Reference 



The following tables organize the RFC runtime routines. Table B-l shows all the 
routines that client applications can use, and Table B-2 shows all the routines that 
server applications can use. The following abbreviations are used in RFC runtime 
routine names: 



Auth 


authentication, authorization 


Elt 


element 


Ep 


endpoint 


Exp 


expiration 


Id 


identifier 


If 


interface 


Inq 


inquire 


Mbr 


member 


Mgmt 


management 


Ns 


name service 


Protseq 


protocol sequence 


Rpc 


remote procedure call 


Stats 


statistics 



Numbers next to the calls have the following meaning: 
Function is limited to using Windows NT Security. 
Function is supported on Microsoft Windows NT systems only. 
Function acts on only the local process with Microsoft RPC Version 1.0. 

4 

Function provided for compatibility with DCE CDS. Not supported by the 
Microsoft Locator Version 1.0. 



143 



144 



Microsoft RFC Programming Guide 



Table B-l Client RFC Runtime Routines 



Manage Binding Handles 


Manage VUIDs 


RpcBindingCopy 
RpcBindingFree 
RpcBindingReset 
RpcEpResolveBinding 
RpcBindinglnqObject 
RpcBindingSetObject 
RpcBindinglnqAuthlnfo 1 
RpcBindingSetAuthlnfo 
RpcBindingVectorFree 
RpcStringBindingCompose 
RpcBindingFromStringBinding 
RpcBindingToStringBinding 
RpcSsDestroyClientContext 
RpcStringBindingParse 


UuidCreate 
UuidFromString 
UuidToString 
UuidCompare 
UuidEqual 
UuidHash 
UuidlsNil 


General Utility 


RpcStringFree 


Manage Name Service Entries 


RpcNsMgmtEntryCreate 4 
RpcNsEntryObjectlnqBegin 
RpcNsEntryObjectlnqNext 
RpcNsEntryObjectlnqDone 
RpcNsEntryExpandName 
RpcNsMgmtEntrylnqlflds 
RpcNsMgmtBindingUnexport 
RpcNsMgmtEntryDelete 


Find Servers from a Name Service 


RpcNsBindinglmportBegin 
RpcNsBindinglmportNext 
RpcNsBindinglmportDone 
RpcNsBindinglnqEntryName 
RpcNsBindingLookupBegin 
RpcNsBindingLookupNext 
RpcNsBindingSelect 
RpcNsBindingLookupDone 


Manage Name Service Groups 


RpcNsGroupMbrAdd 4 
RpcNsGroupMbrlnqBegin 4 
RpcNsGroupMbrlnqNext 4 
RpcNsGroupMbrlnqDone 4 
RpcNsGroupMbrRemove 4 
RpcNsGroupDelete 4 


Manage Name Service Expirations 


RpcNsMgmtlnqExpAge 
RpcNsMgmtSetExpAge 
RpcNsMgmtHandleSetExpAge 


Manage Endpoints 


RpcEpUnregister 



Appendix B: RFC Runtime Routines Quick Reference 



145 



Table B-l Client RFC Runtime Routines (continued) 



Manage Name Service Profiles 


Handle Exceptions 


RpcNsProfileEltAdd* 
RpcNsProfileEltlnqBegin 4 
RpcNsProfileEltlnqNext 4 
RpcNsProfileEltlnqDone 4 
RpcNsProfileEltRemove 4 
RpcNsProfileDelete 4 


RpcAbnormalTermination 
RpcEndExcept 
RpcEndFinally 
RpcExcept 
RpcFinally 
RpcExceptionCode 
RpcRaiseException 
RpcTryExcept 
RpcTryFinally 


Manage the Client 


RpcMgmtEnableldleCleanup 
RpcMgmtlnqComTimeout 
RpcMgmtSetComTimeout 
RpcMgmtSetCancelTimeout 
RpcWinSetYieldlnfo 
YieldFunctionName 


Manage Memory 


RpcSmAllocate 
RpcSmClientFree 
RpcSmDestroyClientContext 
RpcSmDisableAllocate 
RpcSmEnableAllocate 
RpcSmFree 
RpcSmGetThreadHandle 
RpcSmSetClientAllocFree 
RpcSmSetThreadHandle 
RpcSmSwapClientAllocFree 
RpcSsAllocate 
RpcSsDestroyClientContext 
RpcSsDisableAllocate 
RpcSsEnableAllocate 
RpcSsFree 
RpcSsGetThreadHandle 
RpcSsSetClientAllocFree 
RpcSsSetThreadHandle 
RpcSsSwapClientAllocFree 


Manage Local or Remote 
Applications 


RpcMgmtlsServerListening^ 
RpcMgmtStopServerListening3 
RpcMgmtInqStats3 


Inquire of Protocol Sequences 


RpcNetworklsProtseq Valid 


Manage Interface Information 


Rpclflnqld 
RpcIfRegisterAuthlnfo 
RpcIfldVectorFree 



146 



Microsoft RFC Programming Guide 



Table B-2 Server RFC Runtime Routines 



Manage Binding Handles 


Manage UUIDs 


RpcServerlnqBindings 
RpcBindingToStringBinding 
RpcStringBindingParse 
RpcStringBindingCompose 
RpcBindinglnqAuthClient 1 
RpcBindinglnqObject 
RpcBindingServerFromClient 
RpcBindingVectorFree 


UuidCreate 
UuidFromString 
UuidToString 
UuidCompare 
UuidEqual 
UuidHash 
UuidlsNil 


Manage Name Service Entries 


Manage Interfaces 


RpcNsMgmtEntryCreate 
RpcNsEntryObjectlnqBegin 
RpcNsEntryObjectlnqNext 
RpcNsEntryObjectlnqDone 
RpcNsEntryExpandName 4 
RpcNsMgmtEntrylnqlflds 
RpcNsMgmtBindingUnexport 
RpcNsMgmtEntryDelete 


RpcServerRegisterlf 
RpcServerlnqlf 
RpcServerUnregisterlf 
Rpclflnqld 
RpcIfldVectorFree 


Manage Name Service Expirations 


RpcNsMgmtlnqExpAge 
RpcNsMgmtSetExpAge 
RpcNsMgmtHandleSetExpAge 


Manage Name Service Groups 


RpcNsGroupMbrAdd 4 
RpcNsGroupMbrlnqBegin 1 
RpcNsGroupMbrlnqNext 4 
RpcNsGroupMbrlnqDone 4 
RpcNsGroupMbrRemove 4 
RpcNsGroupDelete 4 


Create Binding Information 


RpcImpersonateClient 2 
RpcRevertToSelf 2 
RpcServerUseProtseq 
RpcServerUseAllProtseqs 
RpcServerUseProtseqEp 
RpcServerUseProtseqlf 
RpcServerUseAllProtseqsIf 
RpcNetworklnqProtseqs 
RpcProtseqVectorFree 


Manage Endpoints 


RpcEpRegister 
RpcEpRegisterNoReplace 
RpcEpResolveBinding 
RpcEpUnregister 



Appendix B: RFC Runtime Routines Quick Reference 



147 



Table B-2 Server RFC Runtime Routines (continued) 



Manage Name Service Profiles 


Manage the Server 


RpcNsProfileEltAdd 1 
RpcNsProfileEltlnqBegin 4 
RpcNsProfileEltlnqNext 4 
RpcNsProfileEltlnqDone 4 
RpcNsProfileEltRemove 4 
RpcNsProfileDelete 4 


RpcMgmtSetServerStackSize 
RpcMgmtWaitServerListen 


Handle Exceptions 


RpcAbnormalTermination 
RpcEndExcept 
RpcEndFinally 
RpcExcept 
RpcFinally 
RpcExceptionCode 
RpcRaiseException 
RpcTryExcept 
RpcTryFinally 


Listen for RPCs 


RpcServerListen 


General Utility 


RpcStringFree 


Manage Local or Remote 
Applications 


Manage Memory 


RpcMgmtLsServerListening 3 
RpcMgmtStopServerListening 3 
RpcMgmtlnqStats 3 
RpcMgmtStatsVectorFree 


RpcSmAllocate 
RpcSmClientFree 
RpcSmDisableAllocate 
RpcSmEnableAllocate 
RpcSmFree 
RpcSmGetThreadHandle 
RpcSmSetThreadHandle 
RpcSsAllocate 
RpcSsDisableAllocate 
RpcSsEnableAllocate 
RpcSsFree 
RpcSsGetThreadHandle 
RpcSsSetThreadHandle 


Manage Object Types 


RpcObjectSetType 
RpcObjectSetlnqFn 
RpcObjectlnqType 


Manage Authentication 


RpcServerRegisterAuthlnfo 1 
RpcBindinglnqAuthClient 1 


Export Servers to a Name Service 


RpcNsBindingExport 
RpcNsBindingUnexport 



In this Appendix: 

How to Build and 
Run the Application 

Application Files 




The Arithmetic Application 



The arithmetic application makes a remote procedure call to a procedure named 
sum_arrays, which adds together the values for the same array index in two long 
integer arrays, and returns the sums in another long integer array. 

The application demonstrates the basics of a distributed application with a remote 
procedure call and includes these features: 

Denning a simple array in an interface definition 

Using the automatic binding method 

Exporting a server to the name service 

Checking the error status of RFC runtime calls 

How to Build and Run the Application 

To build the server of the distributed application, type the following: 

C:\SERVER> nmake server 

To run the server of the distributed application, type the following: 

C:\SERVER> arith 

To build the client of the distributed application, type the following: 

C:\CLIENTT> nmake client 

To run the client of the distributed application, type the following: 

C:\CLIENT> client 



149 



150 Microsoft RFC Programming Guide 



Application Files 



Makefile contains descriptions of how the application is compiled. Use the compi 
lation make all to create all the executable files for the application. See Example 
C-l. 

arith.bat is a batch file that sets the environment and executes the server. See 
Example C-2. 

arith.idl contains the description of the constants, data types, and procedures for 
the interface. See Example C-3. 

client. c initializes two arrays, calls the remote procedure sum_arrays, and displays 
the results of the returned array. See Example C-4. 

manager. c is the remote procedure implementation. See Example C-5. 

sewer. c initializes the server with a series of Microsoft RFC runtime calls. See Exam 
ple C-6. 

status. h defines the CHECK_STATUS macro, which interprets error status codes that 
may return from Microsoft RFC runtime calls. See Example C-7. 

Exa mple C- 1 : The Makefile for the A rith metic Application 

# FILE NAME: Makefile 

# Makefile for the arithmetic application 
# 

# definitions for this make file 
# 

APPL=arith 

IDLCMD=midl 

NTRPCLIBS=rpcrt4 . lib rpcns4.1ib libcmt.lib kerne!32.1ib 

# Include Windows NT macros 
! include <ntwin32 .mak> 

# NT c flags 

cflags = -c -WO -Gz -D_X86_=1 -DWIN32 -DMT /nologo 

# NT nmake inference rules 

$(cc) $(cdebug) $ (cflags) $(cvarsmt) $< 
$(cvtomf ) 

# 

# COMPLETE BUILD of the application 
# 

#all: local interface client server 

all: lclient.exe interface client.exe server.exe 

# 

# INTERFACE BUILD 
# 

interface : $ ( APPL ) . h $ ( APPL ) _c . ob j $ ( APPL ) _s . ob j 



Appendix C: The Arithmetic Application 151 

Example C- 1: The Makefile for the Arithmetic Application (continued) 

# 

# LOCAL BUILD of the client application to test locally 
# 

local : Iclient . exe 
lclient.exe: Iclient. obj Imanager.obj 

$(link) $(linkdebug) $(conflags) -out: Iclient. exe -map: Iclient .map \ 

Iclient. obj Imanager.obj \ 

$(NTRPCLIBS) 

# 

# CLIENT BUILD 
# 

client : client . exe 

client.exe: client. obj $ (APPL)_c.obj 

$(link) $ (linkdebug) $(conflags) -out: client. exe -map: client .map \ 

client. obj $(APPL)_c.obj \ 

$(NTRPCLIBS) 

# 

# SERVER BUILD 
# 

server : server . exe 

server.exe: server. obj manager. obj $ (APPL)_s.obj 

$(link) $ (linkdebug) $(conflags) -out : server . exe -map: server. map \ 

server . obj manager .obj $ ( APPL ) _s . obj \ 

${NrRPCLIBS) 

# client and server sources 
client. obj: client. c $(APPL).h 
manager. obj: manager. c $(APPL).h 
server . obj : server . c $ (APPL) . h 

# Local client sources 
Iclient. obj: client. c $(APPL).h 

$(cc) $(cdebug) $(cflags) $(cvarsmt) /DLOCAL /Folclient.obj client. c 
Imanager . obj : manager . c $ (APPL ) . h 

$(cc) $(cdebug) $(cflags) $(cvarsmt) /DLOCAL /Folmanager . obj manager. c 

# client stubs 

$( APPL )_c. obj: $(APPL)_c.c 
$( APPL )_x. obj: $(APPL)_x.c 

# compile the server stub 

$ (APPL) _s. obj : $(APPL)_s.c 

# generate stubs, auxiliary and header file from the IDL file 
$(APPL).h $(APPL)_c.c $(APPL)_x.c : $(APPL).idl 

$ (IDLCMD) $ (APPL) . idl 

# clean up for fresh build 
clean: 

del $(APPL)_?.c 

del *.obj 

del $(APPL) .h 

del *.map 



152 _ Microsoft RFC Programming Guide 

Example C-1-. The Makefile for the Arithmetic Application (continued) 

del *.pdb 

clobber: clean 

if exist client.exe del client.exe 
if exist lclient.exe del lclient.exe 
if exist server.exe del server.exe 

Example C-2: The Server Batch File for the Arithmetic Application 

ECHO OFF 

@KEM FILE NAME: arith.bat 

set ARITHMETIC_SERVER_ENTRY=/ . : /arithmetic_serverhost 

server 

Example C~3: The MIDI File of the Arithmetic Application 

/* FILE NAME: arith.idl */ 

/* This Interface Definition Language file represents a basic arithmetic */ 

/* procedure that a remote procedure call application can use. */ 

[ 

uuid(6AF85260-A3A4-10LA-BLAE-08002B2E5B76) , /* Universal Unique ID */ 

pointer_default (ref ) /* default pointer type is reference */ 

] 

interface arith /* interface name is arith */ 

{ 

const unsigned short ARRAY_SIZE = 10; /* an unsigned integer constant */ 
typedef long long_array [ARRAY_SIZE] ; /* an array type of long integers */ 

void sum_arrays ( /* The sum_arrays procedure does not return a value */ 

[in] long_array a, /* 1st parameter is passed in */ 

[in] long_array b, /* 2nd parameter is passed in */ 

[out] long_array c /* 3rd parameter is passed out */ 



Example C-4: The Client File of the Arithmetic Application 

I* FILE NAME: client. c */ 

/* This is the client module of the arithmetic example. */ 

#include <stdio.h> 

# include <stdlib.h> 

ttinclude "arith. h" /* header file created by IDL compiler 

long_array a ={100,200,345,23,67,65,0,0,0,0}; 
long_array b ={4,0,2,3,1,7,5,9,6,8}; 

main () 
{ 

long_array result; 

int i; 

sum_arrays(a, b, result); /* A Remote Procedure Call 

puts ("sums: ") ; 

for(i =0; i < ARRAY_SIZE; i++) 
printf ( "%ld\n" , result [i] ) ; 



Appendix C: The Arithmetic Application 153 

Example C-4: The Client File of the Arithmetic Application (continued) 
/it************************************************************************/ 
/*** MIDL_user_allocate / MIDL_user_free ***/ 

void * _RPC_API 
MIDL_user_allocate 

( 
size 

) 

size_t size; 
{ 

unsigned char * ptr; 
ptr = malloc ( size ) ; 
return ( (void *)ptr ) ; 



void __RPC_API 
MIDL_user_free 
( 

object 
) 

void * object; 
{ 

free (object) ; 
} 

Example C-5. Remote Procedure of the Arithmetic Application 

I* FILE NAME: manager. c */ 

/* An implementation of the procedure defined in the arithmetic interface. */ 

# include <stdio.h> 

#include "arith.h" /* header file produced by IDL compiler */ 

void sum_arrays(a, b, c) /* implementation of the sum_arrays procedure */ 
long_array a; 
long_array b; 
long_array c; 
{ 

int i; 

for(i = 0; i -< ARRAY_SIZE; i++) 

c[i] = a[i] + b[i] ; /* array elements are each added together */ 

} 

Example C-6: Server Initialization of the Arithmetic Application 

/* FILE NAME: server. c */ 

#include <stdio.h> 

#include "arith.h" /* header created by the idl compiler */ 

ttinclude "status. h" /* header with the CHECK_STATUS macro */ 

main () 

{ 

unsigned long status; /* error status */ 

rpc_binding_vector_t *binding_vector; /* set of binding handles */ 



154 Microsoft RFC Programming Guide 

Example C-6. Server Initialization of the Arithmetic Application (continued) 

unsigned char *entry_name; /* entry name for name service */ 

status = /* error status */ 

RpcServerRegisterlf ( /* register interface with the RFC runtime */ 

arith_vO_0_s_ifspec, /* interface specification (arith.h) */ 

NULL, 

NULL 
); 
CHECK_STATUS( status, "Can t register interface", ABORT); 

status = 

RpcServerUseAllProtseqs ( /* create binding information */ 

RPC_C_PROTSEQ_MAX_REQS_DEFAULT, /* queue size for calls */ 

NULL /* no security descriptor is used */ 

); 

CHECK_STATUS ( status, "Can t create binding information", ABORT); 

status = 

RpcServerlnqBindings ( /* obtain this server s binding information */ 

&binding_vector 
); 
CHECK_STATUS( status, "Can t get binding information", ABORT); 

entry_name - (unsigned char *)getenv("ARITHMETIC_SERVER_ENTRY") ; 

status = 

RpcNsBindingExport ( /* export entry to name service database */ 

RPC_C_NS_SYNTAX_DEFAULT, /* syntax of the entry name */ 

entry_name, /* entry name for name service */ 

arith_vO_0_s_ifspec, /* interface specification (arith.h)*/ 

binding_vector, /* the set of server binding handles */ 
NULL 

); 

CHECK_STATUS( status, "Can t export to name service database", ABORT); 

status = 

RpcEpRegister ( /* register endpoints in local endpoint map */ 

arith_vO_0_s_ifspec, /* interface specification (arith.h) */ 

binding_vector, /* the set of server binding handles */ 

NULL, 

NULL 
); 
CHECK_STATUS( status, "Can t add address to the endpoint map", ABORT); 

status = 

RpcBindingVectorFree ( /* free set of server binding handles */ 

&binding_vector 
); 
CHECK_STATUS( status, "Can t free binding handles and vector", ABORT); 

puts ( "Listening for remote procedure calls ..."); 

status = 

RpcServerListen ( /* listen for remote calls */ 

1, /* minimum number of threads */ 

RPC_C_LISTEN_MAX_CALLS_DEFAULT, /*concurrent calls to server */ 
NULL /* continue listening until explicitly stopped */ 



Appendix C: The Arithmetic Application 155 

Example C-6: Server Initialization of the Arithmetic Application (continued) 

CHECK_STATUS( status, "rpc listen failed", ABORT); 

/*** MIDL_user_al locate / MIDL_user_free ***/ 

void * RPC API 
MIDL_user_al locate 

size 
size_t size; 

unsigned char * ptr; 
ptr = malloc ( size ) ; 
return ( (void *)ptr ) ; 

} 

void RPC API 
MIDL_user_free 

ob j ect 
void * object; 

free (object); 

Example C- 7: The Check Error Status Macro 

/* FILE NAME: status. h */ 
ttinclude <stdio.h> 
#include <stdlib.h> 

#define RESUME 
#def ine ABORT 1 
#define ERROR_TEXT_SIZE 1025 

#define CHECK_STATUS ( input_status , comment, action) \ 
{ \ 

if (input_status ! = RPC_S_OK) { \ 

error_stat = FormatMessage ( FORMAT_MESSAGE_FROM_SYSTEM \ 

,NULL \ 

, input_status \ 

,0 \ 

, error_string \ 

, ERROR_TEXT_SIZE \ 

,NULL); \ 

fprintf (stderr, "%s %s\n", comment, error_string) ; \ 
if (action == ABORT) \ 

exit(l); \ 
} \ 



156 Microsoft RFC Programming Guide 

Example C- 7: The Check Error Status Macro (continued) 



static int error_stat; 

static unsigned char error_string[ERROR_TEXT_SIZE] ; 



In this Appendix: 

How to Run the 
Application 

Application Files 




The Inventory Application 



The inventory application allows a user to inquire about, and order from, a simple 
inventory. Data structures are defined for the following items: 

Part number (to identify a part) 

Part name 

Part description 

Part price 

Quantity of part 

Part list 

Account number (to identify a user) 

Procedures are also defined in the interface definition to do the following: 

Confirm if a part is available 

Obtain a part name 

Obtain a part description 

Obtain a part price 

Obtain the quantity of parts available 

Obtain a list of subpart numbers 

Order a part 

The application demonstrates many features of Microsoft RFC application develop 
ment including: 

Using strings, pointers, structures, a union, and a conformant array. 



157 



158 Microsoft RFC Programming Guide 

Allocating new memory in a remote procedure for data returned to the client 
using stub support routines. The get_part_description and whatare_subparts 
remote procedures demonstrate server allocation of a string and a conformant 
structure. 

Managing protocol sequences, interpreting binding information, selecting 
binding information, and using exception handler macros. 

Variations on a client using ACFs and the automatic, implicit, and explicit 
binding methods. 

Finding a server by importing from a name service database. 

How to Run the Application 

To run the local test of the client, type the following: 

C:\> nmake local 
C:\> lclient.exe 

To run the server of the distributed application, type the following: 

C:\SERVER> nmake server 
C:\SERVER> server.exe 

To run the client that uses the automatic binding method, type the following: 

C:\CLIENT> nmake client 
C:\CLIENT> client.exe 

To run a nondistributed local test of the implicit client, type the following in the 
implicit subdirectory: 

C:\> nmake local 
C:\> lclient.exe 

To run the implicit client of the distributed application using the automatic server, 
type the following in the implicit subdirectory: 

C:\CLIENT> nmake client 
C:\CLIENT> client.exe 

To run the explicit server of the distributed application, type the following in the 
explicit subdirectory: 

C:\SERVER> nmake server 
C:\SERVER> server.exe 

To run the explicit client of the distributed application using the explicit server, 
type the following in the explicit subdirectory: 

C:\CLIENT> nmake client 
C:\CLIENT> client.exe 



Appendix D: The Inventory Application 159 



Application Files 



Makefile contains descriptions of how the application is compiled. Some files 
depend on the header file status. h from the arithmetic application for the 
CHECK_STATUS macro. See Example D-l. 

inv.idl contains the description of the constants, data types, and procedures for the 
interface. See Example D-2. 

manager. c is the implementation of all the remote procedures defined in this inter 
face. See Example D-3. 

invntry.c is the implementation of the inventory database. For simplicity, only 
three inventory items are included. The part numbers for these are printed when 
the inventory is opened. See Example D-4. 

server. c initializes the server with a series of runtime calls prior to servicing remote 
procedure calls. In addition to the required calls, this server also selects a specific 
protocol sequence, uses exception handling macros, and does some basic cleanup 
when the server quits. See Example D-5. 

client. c displays the instructions for the user and processes user input in a loop 
until exit is selected. Each remote procedure is exercised depending on the input 
from the user. See Example D-6. 

implicit\Makefile contains descriptions of how the implicit client is compiled. 
Some files depend on the header file status. h from the arithmetic application for 
the CHECK_STATUS macro. See Example D-7. 

implici t\ inv_i.acf customizes how you use an interface. In this application it is 
used to select the implicit binding method. See Example D-8. 

implicit\client.c imports a binding handle from the name service database. See 
Example D-9. 

implicit\getbind.c contains the do_import_binding procedure, which shows how 
to import a binding handle from the name service database. See Example D-10. 

implicit\intbind.c- contains the do_interpret_binding procedure, which shows how 
to obtain the binding information to which a binding handle refers. See Example 
D-ll. 

The server for the implicit client is the same as the one for the automatic client. 

explicit\Makefile contains descriptions of how the explicit client is compiled. The 
compilation depends on some files from the implicit client development. See 
Example D-12. 

explicit\inv.idl contains the description of the constants, data types, and proce 
dures for the interface. All procedure declarations include a binding handle as the 
first parameter. See Example D-l 3. 



160 Microsoft RFC Programming Guide 

explicit\manager.c is the implementation of all the remote procedures denned in 
this interface. All procedure implementations include a binding handle as the first 
parameter. See Example D-14. 

explicit\client.c imports a binding handle from the name service database. All pro 
cedures have a binding handle as the first parameter. See Example D-15. 

The server s main program for the explicit client is the same as the one for the 
automatic and implicit clients. 

Example D-l. The Makefile for the Inventory Application 

# FILE NAME: Makefile 

# Makefile for the inventory application 
# 

# definitions for this make file 
# 

APPL=inv 

NTRPCLIBS=rpcrt4.1ib rpcns4.1ib libcmt.lib kerne!32.1ib 

! include <ntwin32.mak> 

## NT c flags 

cflags = -c -WO -Gz -D_X86_=1 -DWIN32 -DMT /nologo 

## NT nmake inference rules 

$(cc) $(cdebug) $ (cflags) $(cvarsmt) $< 
$(cvtomf ) 

# 

# COMPLETE BUILD of the application 
# 

all : local interface client server 

# 

# INTERFACE BUILD 
# 

interface: $ (APPL) .h $ (APPL)_c.obj $ (APPL)_s.obj 

# 

# LOCAL BUILD of the client application to test locally 
# 

local: lclient.exe 

lclient.exe: Iclient.obj litianager.obj invntry.obj 

$(link) $(linkdebug) $(conflags) -out: lclient.exe -map:lclient.map \ 

Iclient.obj Imanager.obj invntry.objX 

$(NTRPCLIBS) 

# 

# CLIENT BUILD 
# 

client: client.exe 

client.exe: client. obj $(APPL)_c.obj 

$(link) $(linkdebug) $(conflags) -out: client.exe -map: client .map \ 

client. obj $ (APPL) _c. obj \ 

$(NTRPCLIBS) 



Appendix D: The Inventory Application 161 

Example D-l: The Makefile for the Inventory Application (continued) 

# SERVER BUILD 
# 

server : server . exe 

server.exe: server. obj manager. obj invntry.obj $ (APPL)_s.obj 

$(link) $(linkdebug) $(conflags) -out : server . exe -map: server. map \ 

server . obj manager . obj invntry . obj $ ( APPL ) _s . obj \ 

$(NTRPCLIBS) 

# client and server sources 
client. obj: client. c $(APPL).h 
manager. obj: manager. c $(APPL).h 
server . obj : server . c $ ( APPL ) . h 
invntry . obj : invntry . c $ (APPL) . h 

# Local client sources 
Iclient.obj: client. c $(APPL).h 

$(cc) $(cdebug) $(cflags) $(cvarsmt) /DLOCALX 

/Folclient.obj client. c 
Imanager . obj : manager . c $ (APPL ) . h 

$(cc) $(cdebug) $(cflags) $(cvarsmt) /DLOCAL \ 

/Folmanager . obj manager. c 

# client stubs 

$( APPL )_C. Obj: $(APPL)_C.C 
$( APPL )_x. obj: $(APPL)_x.c 
$ (APPL) _S. obj : $(APPL)_S.C 

# generate stubs, auxiliary and header file from the IDL file 
$(APPL).h $(APPL)_c.c $(APPL)_x.c : $(APPL).idl 

midl $(APPL) .idl 

# clean up for fresh build 
clean: 

del $(APPL)_?.c 

del *.obj 

del $(APPL) .h 

del *.map 

del *.pdb 

clobber: clean 

if exist client.exe del client.exe 

if exist lclierit.exe del lclient.exe 

if exist server.exe del server.exe 

Example D-2. The MIDL File of the Inventory Application 

/* FILE NAME: inv.idl */ 

[ /* brackets enclose attributes */ 

uuid(A6lE3FCO-A53F-10lA-BlAF-08002B2E5B76) , /* universal unique identifier */ 

version(l.O) , /* version of this interface */ 

pointer_default (unique) /* pointer default */ 

] interface inv /* interface name */ 

{ 

const long MAX_STRING =30; /* constant for string size */ 

typedef long part_num; /* inventory part number */ 



162 Microsoft RFC Programming Guide 

Example D-2. The MIDI File of the Inventory Application (continued) 

typedef [string] char part_naine[MAX_STRING+l] ; /* name of part */ 

typedef [string, unique] char *paragraph; /* description of part */ 

typedef enum { 

ITEM, GRAM, KILOGRAM 
} part_units; /* units of measurement */ 

typedef struct part_price { /* price of part */ 

part_units units; 

double per_unit; 

} part_price; 

typedef union switch (part_units units) total { /* quantity of part */ 

case ITEM: long int number; 

case GRAM: 

case KILOGRAM: double weight; 
} part_quantity; 

typedef struct part_list{ /* list of part numbers */ 

long size; /* number of parts in array */ 

[size_is(size) ] part_num numbers [*]; /* conformant array of parts */ 

} part_list; 

typedef struct part_record { /* data for each part */ 

part_num number; 

part_name name ; 

paragraph description; 

part_price price; 

part_quantity quantity; 

part_list subparts; 
} part_record; 

typedef long account_num; /* user account number */ 

********************* Procedure Declarations *************************/ 

boolean is_part_available( /* return true if in inventory */ 

[in] part_num number /* input part number */ 

); 

void whatis_part_name( /* get part name from inventory */ 

[in] part_num number, /* input part number */ 

[in, out] part_name name /* output part name */ 
); 

paragraph get_part_description ( /* return a pointer to a string */ 

[in] part_num number 
); 

void whatis_part_price ( /* get part price from inventory */ 

[in] part_num number, 

[out] part_price *price 
); 

void whatis_part_quantity( /* get part quantity from inventory */ 
[in] part_num number, 
[out] part_quantity *quantity 



Appendix D: The Inventory Application __ 163 

Example D-2. The MIDI File of the Inventory Application (continued) 



void whatare_subparts ( /* get list of subpart numbers */ 

[in] part_num number, 
[out] part_list **subparts /* structure containing the array */ 



/* Order part from inventory with part number, quantity desired, and 
/* account number. If inventory does not have enough, output lesser 



/* Order part from inventory with part number, quantity desired, and */ 

. , */ 

/* quantity ordered. Return values: l=ordered OK, */ 

/* -l=invalid part, -2=invalid quantity, -3=invalid account. */ 

long order_part ( /* order part from inventory, return OK or error code */ 
[in] part_num number, 

[in, out] part_quantity *quantity, /* quantity ordered */ 

[in] account_num account 
); 
} /* end of interface definition */ 

Example D-3- Remote Procedures of the Inventory Application 

I* FILE NAME: manager. c */ 

/** Implementation of the remote procedures for the inventory application. **/ 

#include <stdio.h> 

# include <stdlib.h> 

#include "inv.h" 

boolean is_part_available (number) 

part_num number; 

{ 

part_record *part; /* a pointer to a part record */ 

int found; 

found = read_part_record( number, &part) ; 
if (found) 

return (TRUE) ; 
else 

return (FALSE) ; 



void what is_part_name ( number, name) 
part_num number; 
part_name name; 
{ 

part_record *part; /* a pointer to a part record */ 

read_part_record( number, &part) ; 

strncpy ( (char *)name, (char *)part->name, MAX_STRING) ; 

return; 



paragraph get_part_descript ion ( number ) 

part_num number; 

{ 

part_record *part; /* a pointer to a part record */ 



164 Microsoft RPC Programming Guide 

Example D-3: Remote Procedures of the Inventory Application (continued) 

paragraph description; 
int size; 

if( read_part_record( number, &part) ) { 

/* Allocated data that is returned to the client must be allocated */ 

/* with the MIDL_user_allocate stub support routine. */ 

size = strlen((char *) part -xJescript ion) + 1; 

description = (paragraph) MIDL_user_allocate( (unsigned) size) ; 

strcpy((char *) description, (char *)part->description) ; 
} 
else 

description = NULL; 
return (description) ; 



void whatis_part_price (number, price) 
part_num number; 
part_price *price; 
{ 

part_record *part; /* a pointer to a part record */ 

read_part_record ( number , &part ) ; 
price->units = part->price. units; 
price->per_unit = part->price.per_unit; 
return; 



void what is_part_quantity (number, quantity) 
part_num number; 
part_quantity *quantity; 
{ 

part_record *part; /* a pointer to a part record */ 

read_part_record( number, &part) ; 
quantity->units = part -xjuantity. units; 
switch (quantity->units) { 

case ITEM: quantity->total. number = part -xguantity. total. number; 
break; 

case KILOGRAM: 

case GRAM: quantity- >total . weight = part -xjuantity. total. weight; 

break; 
} 
return; 



void whatare_subparts ( number, subpart_ptr) 
part_num number; 
part_list **subpart_ptr; 
{ 

part_record *part; /* pointer to a part record */ 

int i; 
int size; 

read__part_record ( number , &part ) ; 



Appendix D: The Inventory Application _ 165 

Example D- 3: Remote Procedures of the Inventory Application (continued) 

I* Allocated data that is output to the client must be allocated with */ 

/* the MIDL_user_al locate stub support routine. Allocate for a */ 

/* part_list struct plus the array of subpart numbers. Remember the */ 

/* part_list struct already has an array with one element, hence the -1. */ 
size = sizeof (part_list) + (sizeof (part_num) * (part->subparts.size-l) ) ; 
*subpart_ptr = (part_list *)MIDL_user_allocate( (unsigned) size) ; 

/* fill in the values */ 

(*subpart_ptr) ->size = part->subparts.size; 

for(i =0; i < (*subpart_ptr) ->size; i++) 

(*subpart_ptr) ->numbers[i] = part ->subparts. numbers [i ] ; 
return; 



long int orderjpart (number, quantity, account) 

part_num number; 

part_quantity *quantity; 

account_num account ; 

{ 

part_record *part; /* pointer to a part record */ 

long error =1; /* assume no error to start */ 

/* Test for valid input */ 

if ( !read_part_record( number, &part) ) /* invalid part number input */ 

error = -1; 
else if (quantity->units == ITEM) /* invalid quantity input */ 

error = (quantity->total. number <= 0) ? -2 : error; 
else if (quantity->units == GRAM I I quantity->units == KILOGRAM) 

error = (quantity->total. weight <= 0.0) ? -2 : error; 
/* else if () invalid account, not implemented */ 
/* error = -3; */ 

if (error < 0) 

return (error) ; 

/* convert input quantity & units if units are not correct for part */ 
if (quantity- >units != part->quantity. units) { 

if (part-xjuantity. units == ITEM) /* convert weight to items */ 

quantity->total. number = (long int) quantity- >total. weight; 
else if (quantity->units == ITEM) /* convert items to weight */ 

quantity- >total .weight = (long float) quantity- >total. number; 
else if (quantity->units == GRAM && part-xjuantity. units == KILOGRAM) 

quantity- >total . weight /= 1000.0; /* convert grams to kilograms */ 
else if (quantity->units == KILOGRAM && part -xjuantity. units == GRAM) 

quantity->total. weight *= 1000.0; /* convert kilograms to grams */ 
quantity->units = part-xjuantity. units; 



/* check if enough in inventory for this order */ 
switch (part-xjuantity. units) { 
case ITEM: 

if (part-xjuantity. total. number > quantity->total. number) 
/* reduce quantity in inventory by amount ordered */ 
part -xjuantity. total. number -= quantity- >total . number; 
else { 



166 Microsoft RPC Programming Guide 

Example D- 3: Remote Procedures of the Inventory Application (continued) 

/* order all available and reduce quantity in inventory to */ 

quantity- >total. number = part-xjuantity. total, number ; 

part-xjuantity. total. number = 0; 
} 

break; 

case KILOGRAM: 
case GRAM: 

if (part-xjuantity. total. weight > quantity- >total . weight) 

/* reduce quantity in inventory by amount ordered */ 

part-xjuantity. total, weight -= quantity- >total. weight; 
else { 

/* order all available and reduce quantity in inventory to 0.0 */ 

quantity->total .weight = part-xjuantity . total .weight ; 

part-xjuantity. total. weight = 0.0; 
} 
break; 



write_part_record(part) ; /* update inventory */ 
return (1); /* order ok */ 

Example D-4: The Inventory Implementation 

/* FILE NAME: invntry.c */ 

/* A sample implementation of an inventory. */ 

* For simplicity, a few inventory items are maintained in the inventory. */ 

* The valid numbers are printed when the open_inventory ( ) procedure is */ 
/* called so the user knows what numbers to test. */ 
#include <stdio.h> 

#include <stdlib.h> 

ttinclude "inv.h" 

#define MAX_PARTS 10 /* maximum number of parts in this inventory */ 

#define MAX_SUBPARTS 5 /* maximum number of subparts for a part */ 

static part_record *rec[MAX_PARTS] ; /* array of pointers for this inventory */ 
static inventory_is_open =0; /* flag is reset to non-zero when open */ 

* Data for empty record or unknown part number */ 
static part_record no_part = {0, "UNKNOWN"} ; 
static part_num no_subparts [MAX_SUBPARTS] ; 



void open_inventory ( ) /***** setup inventory *******************************/ 

int i , j ; 
unsigned size; 

/* Allocate memory for the inventory array. Each part gets the size of */ 
/* a part_record plus enough memory for a subpart list. Since the */ 
/* subpart list is already defined in the part_record as an array of 1, */ 

* the new array memory only needs to be MAX_SUBPARTS-1 in size. */ 
for(i =0; i < MAX_PARTS; i++) { 

size = sizeof (part_record) + (sizeof (part_num) * (MAX_SUBPARTS-1) ) ; 

rec[i] = (part_record *)malloc(size) ; 



Appendix D: The Inventory Application 167 

Example D-4. The Inventory Implementation (continued) 

} 

/* assign some data to the inventory array (part of an exercise machine) */ 

rec [ ] ->number = 102 ; 

stmcpy((char *)rec[0] ->name / "electronics display module" , MAX_STRIN3) ; 

rec[0]->description = (paragraph) malloc( 1000 ); 

strcpy((char *)rec[0] ->description, 

"The electronics display module is a liquid crystal display containing\n\ 
a timer, counter, metronome, and calorie counter."); 
rec [ ] ->price . units = ITEM; 
rec[0]->price.per_unit = 7.00; 
rec [0]->quantity. units = rec [0] ->price. units; 
rec [ 0] -xjuantity. total. number = 432; 

rec [0]->subparts. size = 4; /* cannot be greater than MAX_SUBPARTS */ 
for(i =0; i < rec [0] ->subparts. size; i++) /* values used are not relevant */ 
rec[0]->subparts.numbers[i] = rec[0]->number + 1 + i; 

rec[l] ->number = 203; 

strncpy ( (char *)rec[l] ->name, "base assembly", MAX_STRHSJG) ; 
rec [1] -description = (paragraph) malloc( 1000 ); 
strcpy((char *)rec[l] -xiescription, 

"The base assembly rests on the floor to stabilize the machine. \n\ 
The arm and bench assemblies are attached to it."); 
rec[l] ->price. units = ITEM; 
rec[l]->price.per_unit = 85.00; 
recfl] -xjuantity. units = recfl] ->price. units; 
rec [1] -xjuantity. total. number = 1078; 

rec [l]->subparts. size = 5; /* cannot be greater than MAX_SUBPARTS */ 
forfi =0; i < rec [1] ->subparts. size; i++) /* values used are not relevant */ 
rectl] ->subparts.numbers[i] = rec [1] ->number + 17 + i; 

rec[2]->number = 444; 

strncpy ( (char *)rec[2] ->name, "ballast", MAX_STRIN3) ; 
rec [2 ] -xiescription = (paragraph) malloc ( 1000 ) ; 
strcpy ( (char * ) rec [2 ] -xJescription, 

"The ballast is used to counterbalance the force exerted by the user."); 
rec[2]->price.units = KILOGRAM; 
rec[2]->price.per_unit = 1.59; 
rec [2] -xjuantity. units = rec[2]->price.units; 
rec [2] -xjuantity. total. weight = 13456.2; 

rec[2]->subparts.size =0; /* cannot be greater than MAX_SUBPARTS */ 
for(i =0; i < MAX_^UBPARTS ; i++) /* zero out subpart array */ 

rec [2 ]->subparts. numbers [i] = no_subparts[i] ; 

/* fill in rest of inventory as "empty" data */ 
for(i =3; i < MAX_PARTS; i++) { 

rec [ i ] = &no_part ; 

for(j = 0; j < MAX_SUBPARTS; j++) 

rec[i]->subparts. numbers [j] = no_subparts[j] ; 
} 

puts ("Part numbers in inventory:"); 
for(i = 0; i < MAX_PARTS; i++) 

if (rec[i]->number > 0) 

printf ( "%ld\n" , rec [i] ->number) ; 
inventory_is_open = 1; 



1 68 



Microsoft RFC Programming Guide 



Example D-4: The Inventory Implementation (continued) 



return; 



void close_inventory ( ) /**** close inventory 



/ 



/* Undo whatever is done in open_inventory . Free memory and so forth. */ 

/* (not implemented) */ 

return; 



int read_part_record ( number, part_ptr) /** get record for this part number **/ 
part_num number; 
part_record **part_ptr; 



int i; 

if (inventory_is_open == 0) 

open_inventory ( ) ; 
*part_ptr = &no_part; 
for(i =0; i < MAX_PARTS; i++) 
if (rec[i] ->number == number) { 
*part_ptr = rec[i]; 
break; 



/* initialize assuming no part */ 
/* search the inventory */ 
/* found the part */ 



if( (*part_ptr) ->number > 0) 

return ( 1 ) ; 
else 

return ( ) ; 



/* not a valid part 



int write_part_record(part) 

part_record *part; 

{ 

int i; 



update inventory for this part number ***** 



if (inventory_is_open == 0) 

open_inventory ( ) ; 
for(i =0; i < MAX_PARTS; 

if (rec[i]->number == part->number) { 

rec[i] = part; /* overwrite inventory with new data */ 
return (1) ; 
} 
return (0) ; 



/* dump the part data to the screen. 
static dump_part_record( index) 
int index; 
{ 

printf ( "number input : %ld part number : %ld\n" , number, rec [index] ->number) 

printf ( "part name: %s\n" , rec [index] ->name) ; 

printf ( "description : %s\n" , rec [ index] -Rescript ion) ; 

printf ("price :%f per %s\n", rec [ index] ->price.per_unit, 



Appendix D: The Inventory Application 169 

Example D-4: The Inventory Implementation (continued) 

(rect index] ->price. units == ITEM) ? "item" : "gram"); 
printf ( "quantity: " ) ; 
switchfrec [index] ->quantity. units) { 

case ITEM: printf ("%ld items\n", rec[index] ->quantity. total. number) ; break; 
case GRAM: printf ("%f grams\n", rec [ index] -xjuantity. total. weight ) ; break; 
case KILOGRAM: printf ("%f kilos\n", rec [ index] -xjuantity. total. weight ) ; 

break; 
} 

print f ( " subparts : " ) ; 
for(i =0; i < rec [index] ->subparts.size; i++) 

printf ( "%ld " , rec [index] ->subparts .numbers [i] ) ; 
printf ("\n" ) ; 
}*/ 

Example D-5. Server Initialization of the Inventory Application 

/* FILE NAME: server. c */ 

tinclude <stdio.h> 

#include <stdlib.h> 

#include <ctype.h> 

#include "inv.h" /* header created by the IDL corrpiler */ 

#include "status. h" /* contains the CHECK_STATUS macro */ 

ttdefine STRINGLEN 50 

main (argc, argv) 

int argc; 

char *argv [ ] ; 

{ 

error_status_t status; /* error status */ 

/* RFC vectors */ 

rpc_binding_vector_t *binding_vector; /* binding handle list */ 

RPC_PROTSEO_VECTOR *protseq_vector; /*protocol sequence list */ 

char entry_name [ STRINGLEN ]; /* name service entry name */ 
char group_name [ STRINGLEN ]; /* name service group name */ 
char annotation [ STRINGLEN] ; /* annotation for endpoint map */ 
char hostname [ STRINGLEN] ; /* used to store the computer name */ 

DWDRD hostname_size=STRINGLEN; /* required by GetComputerName */ 
/************************** REGISTER INTERFACE ***************************/ 
status = 
RpcServerRegisterlf ( 

inv_vl_0_s_ifspec, /* interface specification (inv.h) */ 

NULL, 

NULL 
); 
CHECK_STATUS( status, "Can t register interface:", ABORT); 

/****************** CREATING SERVER BINDING INFORMATION ******************/ 
if (argc > 1) { 
status = 

RpcServerUseProtseq( /* use a protocol sequence */ 

(unsigned char *)argv[l], /* the input protocol sequence */ 

RPC_C_PROTSEO_MAX_REQS_DEFAULT, /* the default number of requests*/ 

NULL /* security descriptor (not reqd)*/ 



Microsoft RFC Programming Guide 



Example D- 5: Server Initialization of the Inventory Application (continued) 

CHECK_STATUS( status, "Can t use this protocol sequence:", ABORT); 
} 
else { 

puts ("You can invoke the server with a protocol sequence argument."); 

status = 

RpcServerUseAllProtseqs ( /* use all protocol sequences 

RPC_C_PROTSEQ_MAX_REQS_DEFAULT, /* the default number of requests */ 
NULL /* security descriptor (not reqd) */ 

); 

CHECK_STATUS ( status, "Can t register protocol sequences:", ABORT); 

} 

status = 

RpcServerlnqBindings ( /* get binding information for server */ 

&binding_vector 

); 

CHECK_STATUS( status, "Can t get binding information:", ABORT); 

/*************************** ADVERTISE SERVER ****************************/ 



strcpy ( entry_name , " / . : / inventory_" ) ; 

GetComputerName(&hostname, &hostname_size) ; 

strcat (entry_name, hostname); 

status = 

RpcNsBindingExport ( /* export to a name service database */ 

RPC_C_NS_SYNTAX_DEFAULT, /* syntax of entry name */ 

(unsigned char *)entry_name, /* name of entry in name service */ 
inv_vl_0_s_ifspec, /* interface specification (inv.h) */ 
binding_vector, /* binding information */ 

NULL /* no object UUIDs exported */ 

); 

CHECK_STATUS( status, "Can t export to name service database:", RESUME); 



ENDPOINTS w***"******* * * **** *** *** ^ 

strcpy (annotation, "Inventory interface"); 

status = 

RpcEpRegister ( /* add endpoints to local endpoint map */ 

inv_vl_0_s_ifspec, /* interface specification (inv.h) */ 
binding_vector, /* vector of server binding handles */ 

NULL, /* no object UUIDs to register */ 

(unsigned char *) annotation /* annotation supplied (not required) */ 

); 

CHECK_STATUS( status, "Can t add endpoints to local endpoint map:", RESUME); 

status = 

RpcBindingVectorFree ( /* free server binding handles */ 

&binding_vector 
); 
CHECK_STATUS( status, "Can t free server binding handles:", RESUME); 

open_inventory ( ) ; /* application specific procedure */ 

/******************* LISTEN FOR REMOTE PROCEDURE CALLS *******************/ 
RpcTryExcept /* thread exception handling macro */ 



Appendix D: The Inventory Application _ 171 

Example D- 5: Server Initialization of the Inventory Application (continued) 

status = 
RpcServerListen ( 

1, /* process one remote procedure call at a time */ 

RPC_C_LISTEN_MAX_CALLS_DEFAULT , 

NULL 
); 

CHECK_STATUS ( status, "rpc listen failed:", RESUME); 
} 

RpcExcept (RpcExceptionCodeO ) /* error recovery and cleanup */ 

{ 

close_inventory ( ) ; /* application specific procedure */ 

status = 

RpcServerlnqBindings ( /* get binding information */ 

&binding_vector 
); 
CHECK_STATUS( status, "Can t get binding information:", RESUME); 

status = 

RpcEpUnregister ( /* remove endpoints from local endpoint map */ 

inv_vl_0_s_ifspec, /* interface specification (inv.h) */ 

binding_vector, /* vector of server binding handles */ 

NULL /* no object UUIDs */ 

); 

CHECK_STATUS( status, "Can t remove endpoints from endpoint map:", RESUME); 

status = 

RpcBindingVectorFree ( /* free server binding handles */ 

&binding_vector 
); 
CHECK_STATUS( status, "Can t free server binding handles:", RESUME); 

puts ( " \nServer quit ! " ) ; 
} 

RpcEndExcept ; 
} /* END SERVER INITIALIZATION */ 

/*** MIDL_user_al locate / MIDL_user_free ***/ 

void * __RPC_API 
MIDL_user_al locate " 



size_t size; 
{ 

unsigned char * ptr; 
ptr = malloc ( size ) ; 
return ( (void * ) ptr 



void _RPC_API 
MIDL_user_free 



172 Microsoft RFC Programming Guide 

Example D- 5: Server Initialization of the Inventory Application (continued) 

( 

ob j ect 
) 

void * object; 
{ 

free (object) ; 
} 

Example D-6: The Automatic Client File of the Inventory Application 

/* FILE NAME: client. c */ 

/******************** client of the inventory application *******************/ 

#include <stdio.h> 

#include <stdlib.h> 

#include "inv.h" /* header file created by the IDL compiler */ 

char instructions [] = "Type character followed by appropriate argument (s) .\n\ 

Is part available? a [part_number] \n\ 

What is part name? n [part_number] \n\ 

Get part description. d [part_number] \n\ 

What is part price? p [part_number] \n\ 

What is part quantity? q [part_number] \n\ 
What are subparts of this part? s [part_number] \n\ 

Order part. o part_number quantity\n\ 

REDISPLAY r\n\ 

EXIT e\n" ; 

main() 

{ 

part_record part; /* structure for all data about a part */ 

part_list *subparts; /* pointer to parts list data structure */ 
account_num account =1234; /* a user account number */ 

int i, num_args, done = 0; 

long result; 

char input [100] , selection [20 ], quantity [20] ; 

puts ( instructions ) ; 

part. number = 0; 

strcpy (quantity , " " ) ; 

while Udone) { /* user makes selections and each is processed */ 

printf ( " Selection : " ) ; f flush ( stdout ) ; gets ( input ) ; 

num_args = sscanf (input, "%s%ld%s", selection, & (part. number ), quantity); 

switch ( tolower (selection [0] )) { 
case a : if ( is_part_available (part. number )) 
puts ( "available : Yes " ) ; 

else 

puts ( " avai lable : No " ) ; 

break; 
case n : what is_part_name( part. number, part. name) ; 

printf ("name: %s\n", part. name); 

break; 
case d : part . description = get_part_description (part. number ); 

printf ( "description: \n%s\n" , part . description) ; 



Appendix D: The Inventory Application 



173 



Example D-6: The Automatic Client File of the Inventory Application (continued) 

if (part. description != NULL) 

f ree( part. descript ion ); /* free memory allocated */ 
break; 

case p : whatis_part_price (part. number, & (part. price) ) ; 
printf ("price :%10.2f\n", part. price. per_unit) ; 
break; 

case q : whatis_part_quantity (part. number, &( part. quant i ty )); 
if (part, quantity, units == ITEM) 

printf ("total items :%ld\n", part. quantity. total. number ); 
else if (part. quantity. units == GRAM) 

printf ("total grams:%10.2f\n" , part. quantity. total. weight ); 
else if (part. quantity. units == KILOGRAM) 

printf ("total kilos :%10.2f\n", part. quantity. total. weight ) ; 
break; 

case s : whatare_subparts (part. number, &subparts) ; 
for(i =0; i < subparts->size; i++) 

printf ( " %ld " , subparts->numbers [ i ] ) ; 

printf ("\ntotal number of subparts:%ld\n" , subparts->size) ; 
free(subparts) ; /* free memory for conformant struct */ 
break; 
case o : if(num_args < 3) { 

puts ("Not enough arguments"); 
break; 



/* Assume KILOGRAM units and assign quantity input */ 

part. quantity. units = KILOGRAM; 

part. quantity. total. weight = atof (quantity) ; 

result = order_part (part. number, & (part. quant i ty ), account); 

if (result > 0) { 

if (part. quantity. units == ITEM) 

printf ("order :%ld items\n", part. quantity. total. number ); 
else if (part. quantity. units == GRAM) 

printf ( "order : %10 . 2f grams\n" , part . quantity . total .weight ) , 
else if (part. quantity. units == KILOGRAM) 

printf ("order :%10.2f kilosYn", part. quantity. total. weight) , 

else { /* error cases */ 

if (result == -1) puts ( "Invalid part number"); 
else if (result == -2) puts ("Invalid quantity" ); 
else if (result == -3) puts ("Invalid account number"); 

break; 

case r : /* redisplay selection or bad input displays instructions */ 
default : puts ( instructions ) ; break ; 
case e : done = 1; break; 
} /*end case */ 
} /* end while */ 
} /* end mainO */ 



/**** 
/*** 
/***< 



MIDL_user_allocate / MIDL_user_free 



****/ 
*** / 

****/ 



U4 Microsoft RFC Programming Guide 

Example D-6: The Automatic Client File of the Inventory Application (continued) 

void * _RPC_API 
MIDL_user_al locate 



size_t size; 
{ 

unsigned char * ptr; 
ptr = malloc ( size ) ; 
return ( (void *)ptr ); 



void __RPC_API 
MIDL_user_free 
( 

ob j ect 
) 

void * object; 
{ 

free (object) ; 
} 

Example D- 7: The Makefile for the Implicit Client 

# FILE NAME: Makefile 

# Makefile for the inventory application implicit client 
# 

# definitions for this make file 
# 

APPL=inv 

IDLCMD=midl 

NTRPCLIBS=rpcrt4 . lib rpcns4.1ib libcmt.lib kerne!32.1ib 

! include <ntwin32.mak> 

## NT c flags 

cflags = -c -WO -Gz -D_X86_=1 -DWIN32 -DMT /I. /I., /nologo 

## NT nmake inference rules 

$(cc) $(cdebug) $ (cflags) $(cvarsmt) $< 
$(cvtotnf) 

# 

# COMPLETE BUILD of the application 
# 

all: lclient.exe interface client.exe 

# 

# INTERFACE BUILD 
# 

interface : $ ( APPL ) . h $ ( APPL ) _c . ob j 

# 

# LOCAL BUILD of the client application to test locally 



Appendix D: The Inventory Application 775 

Example D- 7: The Makefile for the Implicit Client (continued) 

# 

local: lclient.exe 

lclient.exe: Iclient.obj Imanager. obj invntry.obj 

$(link) $(linkdebug) $(conflags) -out: lclient.exe -map:lclient.map \ 

Iclient.obj Imanager.obj invntry.obj \ 

$(NTRPCLIBS) 

# 

# CLIENT BUILD 
# 

client : client . exe 

client.exe: client. obj getbind.obj intbind.obj $ (APPL)_c.obj 

$(link) $(linkdebug) $(conflags) -out : client. exe -map: client. map \ 

client. obj getbind.obj intbind.obj $ (APPL)_c.obj \ 

$(NTRPCLIBS) 

# client and server sources 
client. obj: client. c $(APPL).h 
getbind . obj : getbind . c 

intbind . obj : intbind . c 

# Local client sources 
invntry . obj : . . \ invntry . c 

$(cc) $(cdebug) $(cflags) $(cvarsmt) /DLOCAL /I. /I.. \ 

/Foinvntry . obj . . \ invntry . c 
Iclient.obj: client. c $(APPL).h 

$(cc) $(cdebug) $(cflags) $(cvarsmt) /DLOCAL /I. /I.. \ 

/Folclient.obj client. c 
Imanager . obj : . . \manager . c $ ( APPL) . h 

$(cc) $(cdebug) $(cflags) $(cvarsmt) /DLOCAL /I. /I.. \ 
/Fo Imanager . obj . . \manager . c 

# client stubs 

$( APPL )_c. obj: $(APPL)_c.c 
$( APPL )_x. obj: $(APPL)_x.c 

# generate stubs, auxiliary and header file from the IDL file 
$(APPL).h $(APPL)_i.acf $(APPL)_c.c $(APPL)_x.c : . . \$ (APPL) . idl 

$(IDLCMD) ..\$ (APPL) .idl /acf $ (APPL)_i.acf 

# clean up for fresh build 
clean: 

del $(APPL)_?.c 
del *.obj 
del $(APPL) .h 
del *.map 
del *.pdb 

clobber : clean 

if exist client.exe del client.exe 
if exist lclient.exe del lclient.exe 
if exist server.exe del server.exe 



176 



Microsoft RFC Programming Guide 



Example D-8: An ACF File for Implicit Binding 

I* FILE NAME: inventory .acf (implicit version)*/ 

/* This Attribute Configuration File is used in conjunction with the */ 

/* associated .idl file ( inventory . idl ) when the IDL compiler is invoked. */ 

implicit_handle(handle_t global_binding_h) /* implicit binding method */ 

] 

interface inv /* The interface name must match the .idl file. */ 



Example D-9: The Implicit Client of the Inventory Application 

I* FILE NAME: client. c */ 

/******* Client of the inventory application with implicit method ***********/ 

#include <stdio.h> 

#include <stdlib.h> 

#include "inv.h" /* header file created by the IDL compiler */ 

# include " . . \status .h" 

char instructions [] = "Type character followed by appropriate argument ( s ). \n\ 



Is part available? 

What is part name? 

Get part description. 

What is part price? 

What is part quantity? 

What are subparts of this part? 

Order part. 

REDISPLAY 

EXIT 



[part_number] \n\ 
[part_number] \n\ 
[part_number] \n\ 
[part_number] \n\ 
[part_number] \n\ 
[part_number] \n\ 



o part_number quantity\n\ 

r\n\ 

e\n" ; 



main() 



part_record part; 
part_list *subparts; 
account_num account = 1234; 
unsigned long status; 



/* structure for all data about a part */ 

/* pointer to parts list data structure */ 

/* a user account number */ 

/* error status */ 



int i, num_args, done = 0; 

long result; 

char input [100] , selection [20 ], quantity [20] ; 

puts (instructions) ; 
part. number = 0; 
strcpy (quantity, " " ) ; 



#ifndef LOCAL 

do_import_binding ( 
#endif 



/* find server in name service database */ 
&global_binding_h) ; 



status = RpcBindingReset (global_binding_h) ; 

CHECK_STATUS( status, "Can t reset binding handle", ABORT); 

while Udone) { /* user makes selections and each is processed */ 

printf ( " Selection : " ) ; f flush ( stdout ) ; gets ( input ) ; 
num_args = sscanf (input, "%s%ld%s", selection, & (part. number ), quantity), 

switch (tolower (selection [0] )) { 



Appendix D: The Inventory Application 



177 



Example D-9: The Implicit Client of the Inventory Application (continued) 

case a : if ( is_part_available (part. number )) 

puts ( " available : Yes " ) ; 
else 

puts ( " avai lable : No " ) ; 
break; 

case n : what is_part_name( part. number, part. name); 
printf ("name: %s\n", part. name); 
break; 

case d : part. description = ge t_part_descript ion (part .number) ; 
printf ( "description: \n%s\n" , part .description) ; 
if (part. description != NULL) 

f ree (part. description) ; /* free memory allocated */ 
break; 

case p : whatis_part_price (part. number, & (part. price) ) ; 
printf ("price :%10.2f\n", part. price. per_unit) ,- 
break; 

case q : what is_part_quantity( part, number, & (part, quantity) ); 
if (part, quantity, units == ITEM) 

printf ("total items:%ld\n", part. quantity. total. number ); 
else if (part. quantity. units == GRAM) 

printf ("total grams:%10.2f \n" , part. quantity. total. weight ); 
else if (part. quantity. units == KILOGRAM) 

printf ("total kilos : %10. 2f \n" , part. quantity. total. weight ) ; 
break; 

case s : whatare_subparts (part. number, &subparts) ; 
for(i = 0; i < subparts->size; i++) 

printf ( " %ld " , subparts->numbers [ i ] ) ; 

printf ("\ntotal number of subparts:%ld\n" , subparts->size) ; 
free(subparts) ; /* free memory for conformant struct */ 
break; 
case o : if(num_args < 3) { 

puts ("Not enough arguments"); 
break; 

/* Assume KILOGRAM units and assign quantity input */ 
part, quantity, units = KILOGRAM; 
part. quantity. total. weight = atof (quantity) ; 
result = order_part (part. number, & (part. quant i ty ), account); 
if (result > 0) { 
If (part. quantity. units == ITEM) 

printf ( "order : %ld items\n" , part . quantity . total . number) ; 
else if (part. quantity. units -= GRAM) 

printf ("order :%10.2f grams \n ", part. quantity .total. weight ); 
else if (part. quantity. units == KILOGRAM) 

printf ("order :%10.2f kilos\n", part. quantity. total. weight ); 

else { /* error cases */ 

if (result == -1) puts ("Invalid part number"),- 

else if (result == -2) puts ("Invalid quantity"); 

else if (result == -3) puts ("Invalid account number"); 

break; 
case r : /* redisplay selection or bad input displays instructions */ 



Microsoft RFC Programming Guide 



Example D-9: The Implicit Client of the Inventory Application (continued) 

default: puts ( instructions ); break; 
case e : done = 1; break; 
} /*end case */ 
} /* end while */ 
} /* end main() */ 

^ ************************************************************************* / 
/*** MIDL_user_al locate / MIDL_user_free 

/*************************************************************************/ 



void * __RPC_API 
MIDL user_al locate 



size_t size; 
{ 

unsigned char * ptr; 
ptr = malloc ( size ) ; 
return ( (void *)ptr ); 



void __RPC_API 
MIDL_user_free 
( 

ob j ect 
) 

void * object; 
{ 

free (object) ; 



Example D-10. The do_import_binding Procedure 

/* FILE NAME: getbind.c */ 

/* Get binding from name service database. */ 

#include <stdio.h> 

# include "inv.h" 

#include " . . \status .h" 

void do_import_binding(entry_name, binding_h) 

char entry_name [ ] ; /* entry name to begin search */ 

rpc_binding_handle_t *binding_h; /* a binding handle */ 

{ 

unsigned long status; /* error status */ 

RPC_NS_HANDLE import_context ; /* required to iirport */ 

char protseq[20]; /* protocol sequence */ 

status = 

RpcNsBindinglmportBegin ( /* set context to import binding handles */ 

RPC_C_NS_SYNTAX_DEFAULT, /* use default syntax */ 

(unsigned char *)entry_name, /* begin search with this name */ 

inv_vl_0_c_ifspec, /* interface specification (inv.h) */ 

NULL, /* no optional object UUID required */ 



Appendix D: The Inventory Application 775? 

Example D- 10: The do_import_binding Procedure (continued) 

&import_context /* import context obtained */ 

); 
CHECK_STATUS ( status, "Can t begin import:", RESUME); 

while (1) { 
status = 
RpcNsBindinglmportNext ( /* import a binding handle */ 

import_context , /* context from rpc_ns_binding_import_begin */ 

binding_h /* a binding handle is obtained */ 

); 
if (status != RPC_S_OK) { 

CHECK_STATUS ( status , "Can t import a binding handle:", RESUME); 

break; 
} 

/** application specific selection criteria (by protocol sequence) * */ 

do_interpret_binding ( *binding_h ,protseq) ; 

if (strcmp(protseq, "ncacn_ip_tcp") == 0) /*select connection protocol*/ 

break; 
else { 

status = 

RpcBindingFree ( /* free binding information not selected */ 
binding_h 

); 

CHECK_STATUS( status, "Can t free binding information:", RESUME); 
} 
} /*end while */ 

status = 

RpcNsBindinglnportDone ( /* done with import context */ 

&import_context /* obtained from rpc_ns_binding_import_begin */ 
); 

return; 
} 

Example D-ll. The do_interpret_binding Procedure 

/* FILE NAME: intbind.c */ 

/* Interpret binding information and return the protocol sequence. */ 

#include <stdio.h> 

# include <rpc.h> 

#include " . . \status .h" . 

void do_interpret_binding( binding, protocol_seq) 

rpc_binding_handle_t binding; /* binding handle to interpret */ 

cnar *protocol_seq; /* protocol sequence to obtain */ 

{ 

unsigned long status; /* error status */ 

unsigned char *string_binding; /* string of binding information */ 

unsigned char *protseq; /* binding component of interest */ 

status = 

RpcBindingToStringBinding ( /* convert binding information to string */ 

binding, /* the binding handle to convert */ 

&string_binding /* the string of binding data */ 



Microsoft RFC Programming Guide 



Example D- 11: The do_interpret_binding Procedure (continued) 

); 

CHECK_STATUS( status, "Can t get string binding :", RESUME); 

status = 

RpcStringBindingParse ( /* get components of string binding */ 

string_binding, /* the string of binding data */ 

NULL, /* an object UUID string is not obtained */ 

&protseq, /* a protocol sequence string IS obtained */ 

NULL, /* a network address string is not obtained */ 

NULL, /* an endpoint string is not obtained */ 

NULL /* a network options string is not obtained */ 

); 

CHECK_STATUS ( status, "Can t parse string binding:", RESUME); 

strcpy (protocol_seq, (char *)protseq) ; 

/* free all strings allocated by other runtime routines */ 

status = RpcStringFree(&string_binding) ; 
status = RpcStringFreef&protseq ); 
return; 



Example D- 12: The Makefile for the Explicit Client 

# FILE NAME: Makefile 

# Makefile for the inventory application explicit client 
# 

# definitions for this make file 
# 

APPL=inv 

IDLCMD=midl 

NTRPCLIBS=rpcrt4.1ib rpcns4.1ib libcmt.lib kerne!32.1ib 

! include <ntwin32 .mak> 

## NT c flags 

cflags = -c -WO -Gz -D_X86_=1 -DWIN32 -DMT /nologo 

## NT nmake inference rules 

$(cc) $(cdebug) $ (cflags) $(cvarsmt) /I. /I.. $< 
$(cvtomf ) 

# 

# COMPLETE BUILD of the application 
# 

all: local interface client server 

# 

# INTERFACE BUILD 
# 

interface: $(APPL) .h $ (APPL)_c.obj $ (APPL)_s.obj $ (APPL)_x.obj 

# 

# LOCAL BUILD of the client application to test locally 
# 

local : Iclient . exe 



Appendix D: The Inventory Application J81 

Example D-12-. The Makefile for the Explicit Client (continued) 

lclient.exe: Iclient.obj manager. obj invntry.obj 

$(link) $(linkdebug) $(conflags) -out: lclient.exe -map:lclient.map \ 
Iclient.obj manager. obj invntry.obj \ 
$ (NTRPCLIBS) 

# 

# CLIENT BUILD 
# 

client : client . exe 

client.exe: client. obj getbind.obj intbind.obj $ (APPL)_c.obj $ (APPL)_x.obj 
$(link) $(linkdebug) $(conflags) -out: client. exe -map: client. map \ 

client. obj getbind.obj intbind.obj $(APPL)_c.obj $ (APPL)_x.obj \ 

$ (NTRPCLIBS) 

# 

# SERVER BUILD 
# 

server : server . exe 

server.exe: server. obj manager. obj invntry.obj $ (APPL)_s.obj $ (APPL)_x.obj 
$(link) $(linkdebug) $(conflags) -out : server . exe -map: server. map \ 

server. obj manager. obj invntry.obj $ (APPL)_s.obj $ (APPL)_x.obj\ 

$ (NTRPCLIBS) 

# client and server sources 
client. obj: client. c $ (APPL) .h 
manager. obj: manager. c $(APPL).h 
server . obj : . . \server . c $ (APPL) . h 

$(cc) $(cdebug) $(cflags) $(cvarsmt) /I. /I.. \ 

/Foserver . obj . . \ server . c 
getbind.obj : . . \implicit\getbind.c 

$(cc) $(cdebug) $(cflags) $(cvarsmt) /I. /I.. \ 

/Fogetbind. obj . . \implicit\getbind. c 
intbind.obj : . . \implicit\intbind.c 

$(cc) $(cdebug) $(cflags) $(cvarsmt) /I. /I.. \ 

/Fointbind.obj . .\implicit\intbind.c 
invntry . obj : . . \ invntry . c 

$(cc) $(cdebug) $(cflags) $(cvarsmt) /I. /I.. \ 
/Fo invntry . obj . . \ invntry . c 

# Local client sources 
Iclient.obj: client-.c $(APPL).h 

$(cc) $(cdebug) $(cflags) $(cvarsmt) /DLOCAL /I. /I.. \ 
/Folclient.obj client. c 

# client stubs 

$( APPL) _c. obj: $(APPL)_c.c 
$( APPL )_x. obj: $(APPL)_x.c 

# compile the server stub 
$(APPL)_s.obj : $(APPL)_s.c 

# generate stubs, auxiliary and header file from the IDL file 
$(APPL).h $(APPL)_c.c $(APPL)_x.c $(APPL)_s.c: $(APPL).idl 

$(IDLCMD) $(APPL) .idl 



Microsoft RFC Programming Guide 



Example D- 12: The Makefile for the Explicit Client (continued) 

# clean up for fresh build 
clean: 

del $(APPL)_?.c 

del * . obj 

del $(APPL) .h 

del * .map 

del *.pdb 

clobber: clean 

if exist client.exe del client.exe 
if exist lclient.exe del lclient.exe 
if exist server.exe del server.exe 

Example D- 13: The MIDI File, Explicit Binding 

/* FILE NAME: inv.idl */ 

/* brackets enclose attributes */ 

uuid(cbb7c850-0568-llce-b719-08002bl85ad7), /* universal unique identifier */ 

version(l.O) , /* version of this interface */ 

pointer_default (unique) /* pointer default 

] interface inv /* interface name */ 

{ 

const long MAX_STRING = 30; /* constant for string size */ 

typedef long part_num; /* inventory part number */ 

typedef [string] char part_name [MAX_STRING+1 ] ; /* name of part */ 
typedef [string, unique] char *paragraph; /* description of part */ 

typedef enum { 

ITEM, GRAM, KILOGRAM 
} part_units; /* units of measurement */ 

typedef struct part_price { /* price of part */ 

part_units units; 

double per_unit; 
} part_price; 

typedef union switch (part_units units) total { /* quantity of part */ 

case ITEM: long int number; 

case GRAM: 

case KILOGRAM: double weight; 
} part_quantity; 

typedef struct part_list{ /* list of part numbers */ 

long size; /* number of parts in array */ 

[size_is(size) ] part_num numbers [*]; /* conformant array of parts */ 

} part_list; 

typedef struct part_record { /* data for each part */ 

part_num number ; 
part_name name; 
paragraph description; 
part_price price ; 
part_quantity quantity; 



Appendix D: The Inventory Application 



183 



Example D- 13: The MIDI File, Explicit Binding (continued) 

subparts; 



part_list 
} part_record; 

typedef long account_num; 



/* user account number */ 



/************************ procedure Declarations ************************* 
boolean is_part_available( /* return true if in inventory */ 
[in] handle_t binding_h, /* binding handle for explicit client */ 
[in] part_num number /* input part number */ 



void whatis_part_name ( 

[in] handle_t binding_h, 
[in] part_num number, 
[in, out] part_name name 



/* get part name from inventory */ 
/* binding handle for explicit client */ 
/* input part number */ 

/* output part name */ 



paragraph get_part k _description ( 
[in] handle_t binding_h, 
[in] part_num number 



/* return a pointer to a string */ 
binding handle for explicit client */ 



void whatis_part_price ( 

[in] handle_t binding_h, 
[in] part_num number, 
[out] part_price *price 



/* get part price from inventory */ 
/* binding handle for explicit client */ 



void whatis_part_quantity ( 

[in] handle_t binding_h, 
[in] part_num number, 
[out] part_quantity *quantity 



/* get part quantity from inventory */ 
/* binding handle for explicit client */ 



void whatare_subparts ( 

[in] handle_t binding_h, 
[in] part_num number, 
[out] part_list **subparts 



/* get list of subpart numbers */ 
/* binding handle for explicit client */ 

/* structure containing the array */ 



/* Order part from inventory with part number, quantity desired, and 

/* account number. If inventory does not have enough, output lesser 

/* quantity ordered. Return values: l=ordered OK, 

/* -l=invalid part, -2=invalid quantity, -3=invalid account. 



long order_part( /* order part from inventory, return OK or error code */ 
[in] handle_t binding_h, /* binding handle for explicit client */ 
[in] part_num number, 

[in, out] part_quantity *quantity, /* quantity ordered */ 

[in] account_num account 



} /* end of interface definition */ 



Microsoft RPC Programming Guide 



Example D- 14: Remote Procedures, Explicit Binding 

/* FILE NAME: manager. c */ 

/** Implementation of the remote procedures for the inventory application. **/ 

#include <stdio.h> 
#include <stdlib.h> 
# include "inv.h" 

boolean is_part_available(binding_h, number) 

handle_t binding_h; /* declare a binding handle */ 

part_num number; 

part_record *part; /* a pointer to a part record */ 

int found; 

found = read_part_record( number, &part) ; 
if (found) 

re turn (TRUE) ; 
else 

re turn (FALSE) ; 



void whatis_part_name(binding_h, number, name) 

handle_t binding_h; /* declare a binding handle */ 

part_num number; 

part_name name; 

{ 

part_record *part; /* a pointer to a part record */ 

read_part_record ( number, &part) ; 

strncpy((char *)name, (char *)part->name, MAX_STRING) ; 

return; 



paragraph get_part_description(binding_h, number) 

handle_t binding_h; /* declare a binding handle */ 

par t_num number ; 

part_record *part; /* a pointer to a part record */ 

paragraph description; 
int size; 

if( read_part_record( number, &part) ) { 

/* Allocated data that is returned to the client must be allocated */ 
/* with the MIDL_user_al locate stub support routine. */ 

size = strlen((char *)part->description) + 1; 
description = (paragraph) MIDL_user_allocate( (unsigned) size) ; 
strcpy((char *) description, (char *)part->description) ; 

else 

description - NULL; 
return (description) ; 
} 

void whatis_part_price(binding_h, number, price) 

handle_t binding_h; /* declare a binding handle */ 



Appendix D: The Inventory Application 185 

Example D- 14: Remote Procedures, Explicit Binding (continued) 

part_num number; 
partjprice *price; 
{ 

part_record *part; /* a pointer to a part record */ 

read_part_record ( number , &part ) ; 
price->units = part->price. units; 
price->per_unit = part->price.per_unit; 
return; 



void whatis_part_quantity (binding_h, number, quantity) 

handle_t binding_h; /* declare a binding handle */ 

part_num number; 

part_quantity *quantity; 

{ 

part_record *part; /* a pointer to a part record */ 

read_part_record ( number , &part ) ; 
quantity->units = part-xjuantity. units; 
switch ( quantity- >units) { 

case ITEM: quantity->total. number = part -xjuantity. total. number; 
break; 

case KILOGRAM: 

case GRAM: quantity- >total. weight = part-xjuantity. total. weight; 

break; 
} 
return; 



void whatare_subparts (binding_h, number, subpart_ptr) 

handle_t binding_h; /* declare a binding handle */ 

part_num number; 

part_list **subpart_ptr; 

{ 

part_record *part; /* pointer to a part record */ 

int i; 

int size; 

read_part_record( number, &part) ; 

/* Allocated data that is output to the client must be allocated with */ 

/* the MIDL_user_al locate stub support routine. Allocate for a */ 

/* part_list struct plus the array of subpart numbers. Remember the */ 

/* part_list struct already has an array with one element, hence the -1. */ 
size = sizeof (part_list) + (sizeof (part_num) * (part->subparts.size-l) ) ; 
*subpart_ptr = (part_list *)MIDL_user_al locate ( (unsigned) size) ; 

/* fill in the values */ 

(*subpart_ptr)->size = part->subparts.size; 
for(i = 0; i < (*subpart_ptr) ->size; i++) 

(*subpart_ptr) ->numbers[i] = part ->subparts. numbers [i] ; 
return; 



Microsoft RFC Programming Guide 



Example D- 14: Remote Procedures, Explicit Binding (continued) 

long int order_part (binding_h, number, quantity, account) 
handle_t binding_h; /* declare a binding handle */ 
part_num number; 
part_quantity *quantity; 
account_num account ; 

{ 

part_record *part; /* pointer to a part record */ 

long error = 1; /* assume no error to start */ 

/* Test for valid input */ 

if ( !read_part_record (number, &part) ) /* invalid part number input */ 

error = -1; 
else if (quantity->units == ITEM) /* invalid quantity input 

error = ( quant ity->total. number <= 0) ? -2 : error; 
else if (quantity->units == GRAM I I quantity->units == KILOGRAM) 

error = (quantity->total. weight <= 0.0) ? -2 : error; 
/* else if () invalid account, not implemented */ 
/* error = -3; */ 

if (error < 0) 

return (error) ; 

/* convert input quantity & units if units are not correct for part */ 
if (quantity- >units != par t-xguantity. units) { 

if (part-xjuantity. units == ITEM) /* convert weight to items */ 

quant ity->total. number = (long int }quantity->total. weight; 
else if (quantity- >units == ITEM) /* convert items to weight */ 

quantity- >total .weight = (long float) quantity- >total. number; 
else if (quantity- >units == GRAM && par t-xguantity. units == KILOGRAM) 

quant ity->total. weight /= 1000.0; /* convert grams to kilograms */ 
else if (quantity->units == KILOGRAM && par t-xguantity. units == GRAM) 

quantity- >total. weight *= 1000.0; /* convert kilograms to grams */ 
quantity->units = part-xguantity. units; 



/* check if enough in inventory for this order */ 
switch (part-xguantity. units) { 
case ITEM: 

if (part-xguantity. total. number > quantity- >total . number) 
/* reduce quantity in inventory by amount ordered */ 
part-xguantity. total. number -= quantity- >total . number; 
else { 

/* order all available and reduce quantity in inventory to */ 
quant ity->total. number = part-xguantity. total. number; 
part-xguantity. total. number = 0; 
} 

break; 

case KILOGRAM: 
case GRAM: 

if (part-xguantity. total. weight > quantity- >total . weight) 
/* reduce quantity in inventory by amount ordered */ 
part-xjuantity. total. weight -= quantity- >total. weight; 
else { 

/* order all available and reduce quantity in inventory to 0.0 */ 
quantity->total .weight = part-xjuantity . total .weight ; 



Appendix D: The Inventory Application 



187 



Example D- 14: Remote Procedures, Explicit Binding (continued) 

part-xjuantity. total, weight = 0.0; 
} 
break; 

write_part_record(part) ; /* update inventory */ 
return(l); /* order ok */ 



Example D- 15: The Explicit Client of the Inventory Application 

/* FILE NAME: client. c */ 

/******* Client of the inventory application with explicit method ***********/ 

#include <stdio.h> 

#include <stdlib.h> 

#include "inv.h" /* header file created by the IDL compiler */ 

# inc lude " status . h " 

char instructions [] = "Type character followed by appropriate argument ( s ). \n\ 



Is part available? a 

What is part name? n 

Get part description. d 

What is part price? p 

What is part quantity? q 
What are subparts of this part? s 

Order part. o 

REDISPLAY r\n\ 

EXIT e\n" ; 



[part_number] \n\ 
[part_number] \n\ 
[part_number] \n\ 
[part_number] \n\ 
[part_number] \n\ 
[part_number] \n\ 
part_number quantity\n\ 



main() 



part_record part; 
part_list *subparts; 
account_num account = 1234; 
unsigned long status; 

handle_t binding_h; 



/* structure for all data about a part */ 

/* pointer to parts list data structure */ 

/* a user account number */ 

/* error status */ 

/* declare a binding handle */ 



int i, num_args, done = 0; 

long result; 

char input [100] , . selection[20] , quantity [20] 

puts (instructions) ; 
part. number = 0; 
strcpy (quantity, " " ) ; 



Mfndef LOCAL 

do_import_binding ( " 
#endif 



/* find server in name service database */ 



&binding_h) ; 



status = RpcBindingReset (binding_h) ; 

CHECK_STATUS( status, "Can t reset binding handle", ABORT); 



while (! done) { 

printf ( "Selection: 



/* user makes selections and each is processed */ 
f flush ( stdout ) ; gets ( input ) ; 



188 



Microsoft RFC Programming Guide 



Example D- 15: The Explicit Client of the Inventory Application (continued) 

num_args = sscanf (input, "%s%ld%s", selection, & (part. number ), quantity); 

switch (tolower (selection [0] )) { 

case a : if (is_part_available(binding_h, part. number )) 

puts ( "available : Yes " ) ; 
else 

puts ( " avai lable : No " ) ; 
break; 

case n : whatis_part_name(binding_h, part. number, part. name); 
printf ("name: %s\n" , part. name); 
break; 
case d : part. description = 

get_part_description (binding_h, part . number ) ; 
printf ( "description: \n%s\n" , part .description) ; 
if (part. description ! = NULL) 

f ree (part. description) ; /* free memory allocated */ 
break; 

case p : whatis_part_price(binding_h, part. number, & (part. price) ) ; 
printf ( "price :%10. 2 f\n", part.price.per_unit) ; 
break; 

case q : whatis_part_quantity (binding_h, part. number, &( part, quantity) ) ; 
if (part. quantity. units == ITEM) 

pr int f ( " total i terns : % ld\n " , part . quant i ty . total . number ) ; 
else if (part. quantity. units == GRAM) 

printf ("total grams : %10. 2f \n" , part. quantity. total. weight ); 
else if (part. quantity. units == KILOGRAM) 

printf ("total kilos :%10.2f\n", part. quantity. total. weight ) ; 
break; 

case s : whatare_subparts (binding_h, part. number, &subparts) ; 
for(i =0; i < subparts->size; i++) 

printf ( "%ld " , subparts->numbers [i] ) ; 

printf ("\ntotal number of subparts:%ld\n" , subparts->size) ; 
free(subparts) ; /* free memory for conformant struct */ 
break; 
case o : if (num_args < 3) { 

puts ("Not enough arguments"); 
break; 

/* Assume KILOGRAM units and assign quantity input */ 
part. quantity. units = KILOGRAM; 
part. quantity. total. weight = atof (quantity) ; 
result = 

order_part (binding_h, part. number, & (part. quantity ), account) 
if (result > 0) { 

if (part. quantity. units == ITEM) 

printf ("order :%ld items \n ", part. quantity. total. number ); 
else if (part. quantity. units == GRAM) 

printf ( "order : %10 . 2 f grams \n" , part . quantity . total .weight ) ; 
else if (part. quantity. units == KILOGRAM) 

printf ("order :%10.2f kilos\n", part. quantity. total. weight ); 

else { /* error cases */ 

if (result == -1) puts ("Invalid part number"); 



Appendix D: The Inventory Application 289 

Example D- 15: The Explicit Client of the Inventory Application (continued) 

else if (result == -2) puts ("Invalid quantity"); 
else if (result == -3) puts ("Invalid account number"); 
} 

break; 

case r : /* redisplay selection or bad input displays instructions */ 
default: puts ( instructions ); break; 
case e : done = 1; break; 
} /*end case */ 
} /* end While */ 
} /* end main() */ 

^** *********************************************************************/ 

/*** MIDL_user_allocate / MIDL_user_free ***/ 

/***************** **********************^*^^^^^^^^^^^^^^. fc . fc . fr ^. Ar . fr . fr ^^,. fc . fr . fr . fr ^. 

void * RPC API 
MIDL_user_al locate 



size_t size; 

unsigned char * ptr; 
ptr = malloc ( size ) ; 
return ( (void *)ptr 

} 

void __RPC_API 
MIDL_user_free 

ob j ect 
void * object; 

free (object) ; 




In this Appendix: 
How to Run the 
Application 
Application Files 




The Rflle Application 



The remote file client (rfile.c) copies ASCII data from the client to the server. The 
source can be a data file or the standard input of the client. The target on the 
server system is either a file or the server standard output. The rf ile application 
demonstrates some advanced features of RFC application development including: 

Using a context handle with a context rundown procedure. 

Using the explicit binding method with a primitive binding handle. 

Finding a server using strings of binding information. 

How to Run the Application 

To run the server of the distributed application, type the following: 

C:\SERVER> nmake server 
C:\SERVER> server 

To run the client of the distributed application to transfer ASCII data, use an ASCII 
text file as input and a new data file on the server host as output. Type the follow 
ing: 

C:\CLIENT> nmake client 

C:\CLIENT> client input_file host output_file 

You can also send ASCII data from the client keyboard (stdin) by using the follow 
ing client command: 

C:\CLIENT> client "" host output_file 

Using stdin. Type input: 

data 

data 



191 



Microsoft RFC Programming Guide 



Application Files 

Makefile contains descriptions of how the application is compiled. Some files 
depend on the header file status. h from the arithmetic application for the 
CHECK_STATUS macro. See Example E-l. 

rfile.idl contains descriptions of the data types and procedures for the interface. 
See Example E-2. 

client, c interprets the user input by calling the application-specific procedure 
get_args. A binding handle representing the information about a client-server rela 
tionship is obtained from strings of binding information. The remote procedure 
remote_open is called to open the server target file. A buffer is allocated for a con 
formant array. The application loops, reading source data and sending the data to 
the target with a remote procedure call to remote_send. Finally, the remote proce 
dure remote_close is called to close the target file. See Example E-3. 

getargs.c interprets the user input to obtain the name of a local client ASCII file of 
source data, the server host to use, and the server target file. See Example E-4. 

strbind.c contains the do_string_binding procedure that shows how to find a 
server from strings of binding information. A host name or network address is 
input, and then combined with a generated protocol sequence to create a valid 
binding handle, which is returned as a parameter. See Example E-5. 

crndwn.c is the implementation of a context rundown procedure. The server stub 
calls this procedure automatically if communication breaks between a client and 
the server which is maintaining context for the client. For this application, the con 
text is a file handle of a server data file. This context rundown procedure closes 
the file. See Example E-6. 

manager.c is the implementation of the remote procedures defined in the rfile 
interface. See Example E-7. 

sewer. c initializes the server with a series of runtime calls prior to servicing remote 
procedure calls. In this application, all available protocol sequences are registered. 
The server is not advertised in a name service database. The server s dynamic end- 
points are added to the server s local endpoint map. A client finds this server by 
constructing a string binding containing a protocol sequence and the host name or 
network address. See Example E-8. 

Example E-l: The Makefile for the Remote File Application 

# FILE NAME: Makefile 

# Makefile for the remote file application 
# 

# definitions for this make file 
# 

APPL=rfile 
IDLCMD=midl 
NTRPCLIBS=rpcrt4 . lib rpcns4.1ib libcmt.lib kerne!32.1ib 



Appendix E: The Rflle Application 



Example E- 1: The Makefile for the Remote File Application (continued) 

# Include Windows NT macros 
! include <ntwin32 .mak> 

# NT c flags 

cflags = -c -WO -Gz -D_X86_=1 -DWIN32 -DMT /nologo 

# NT nmake inference rules 

$(cc) $(cdebug) $ (cflags) $(cvarsmt) $< 
S(cvtocnf) 

# 

# COMPLETE BUILD of the application 
# 

all: interface client.exe server.exe 

# 

# INTERFACE BUILD 
# 

interface: $ (APPL) .h $ (APPL)_c.obj $ (APPL)_s.obj $ (APPL)_x.obj 

# 

# CLIENT BUILD 
# 

client : client . exe 

client.exe: client. obj getargs.obj strbind.obj $ (APPL)_c.obj $ (APPL)_x.obj 
$(link) $(linkdebug) $(conflags) -out: client. exe -map: client .map \ 

client. obj getargs.obj strbind.obj $ (APPL)_c.obj $ (APPL)_x.obj \ 

$(NTRPCLIBS) 

# 

# SERVER BUILD 
# 

server : server . exe 

server.exe: server. obj manager. obj crndwn.obj $ (APPL) _s. obj $ (APPL) _x. obj 
$(link) $(linkdebug) $(conflags) -out : server . exe -map: server. map \ 

server. obj manager. obj crndwn.obj $ (APPL) _s. obj $ (APPL) _x. obj \ 

$(NTRPCLIBS) 

# client and server sources 
client. obj: client. c $(APPL).h 
manager . obj : manager . c $ (APPL ) . h 
server . obj : server . c $ (APPL ) . h 
crndwn.obj: crndwn.c $(APPL).h 
getargs . obj : getargs . c 
strbind . obj : strbind . c 

# Local client sources 
Iclient.obj: client. c $(APPL).h 

$(cc) $(cdebug) $ (cflags) $(cvarsmt) /DLOCAL \ 

/Fold ient. obj client. c 
Imanager . obj : manager . c $ (APPL ) . h 

$(cc) $(cdebug) $ (cflags) $(cvarsmt) /DLOCAL \ 

/Folmanager . ob j manager. c 



194 Microsoft RFC Programming Guide 

Example E-l: The Makefile for the Remote File Application (continued) 

# client stubs 
$(APPL)_c.obj: $(APPL)_c.c 
$(APPL)_x.obj: $(APPL)_x.c 

# compile the server stub 
$(APPL)_s.obj : $(APPL)_s.c 

# generate stubs, auxiliary and header file from the IDL file 
$(APPL).h $(APPL)_c.c $(APPL)_x.c : $(APPL).idl 

$(IDLCMD) $(APPL).idl 

# clean up for fresh build 
clean: 

del $(APPL)_?.c 

del *.obj 

del $(APPL) .h 

del *.map 

del *.pdb 

clobber: clean 

if exist client.exe del client.exe 
if exist lclient.exe del lclient.exe 
if exist server.exe del server.exe 

Example E-2: The MIDI File of the Remote File Application 

/* FILE NAME: rfile.idl */ 
[ 

uuid(A6lE4024-A53F-101A-BlAF-08002B2E5B76) , 
version (1.0) , 
pointer_default (unique) 
] 

interface rfile /* file manipulation on a remote system */ 

{ 

typedef [context_handle] void *filehandle; 

typedef byte buffer [ ] ; 

filehandle remote_open( /* open for write */ 

[in] handle_t binding_h, /* explicit primitive binding handle */ 

[in, string] char name[], /* if name is null, use stdout in server */ 

[in, string] char mode[] /* values can be "r", "w" , or "a" */ 

); 

long remote_send( 

[in] filehandle fh, 

[in, max_is(max)] buffer buf, 

[in] long max 
); 

void remote_close ( 

[in, out] filehandle *fh 



Appendix E: The Rflle Application 195 

Example E~3: A Client File of the Remote File Application 

/* FILE NAME: client. c */ 

Mnclude <stdio.h> 

# include <stdlib.h> 

#include <string.h> 

#include "rfile.h" 

#define MAX 200 /* maximum line length for a file */ 

main(argc, argv) 

int argc; 

char *argv [ ] ; 

{ 

FILE *local_fh; /* file handle for client file input */ 

char host [100]; /* name or network address of remote host */ 
char remote_name[100] ; /* name of remote file */ 

rpc_binding_handle_t binding_h; /* binding handle */ 

filehandle remote_fh; /* context handle */ 

buffer *buf_ptr; /* buffer pointer for data sent */ 

int size; /* size of data buffer */ 

get_args(argc, argv, &local_fh, host, (char *)remote_name) ; 
#ifndef LOCAL 

if (do_string_binding(host, &binding_h) < 0) { 

fprintf (stderr, "Cannot get binding\n" ) ; 

exit(l); 
} 
#endif 

remote_fh = remote_open(binding_h, remote_name, (char *)"w"); 
if (remote_fh == NULL) { 

fprintf (stderr, "Cannot open remote file\n"); 

exit(l) ; 
} 

/* The buffer data type is a conformant array of bytes; */ 
/* memory must be allocated for a conformant array. */ 
buf_ptr = (buffer *)malloc( (MAX+1) * sizeof (buffer) ); 

while( fgets((char *)buf_ptr, MAX, local_fh) != NULL) { 

size = ( int )strlen( (char *)buf_ptr); /* data sent will not include \0 */ 
if( remote_send(remote_fh, (*buf_ptr), size) < 1) { 

fprintf (stderr, "Cannot write to remote file\n"); 

exit(l) ; 



remote_close(&remote_fh) ; 
} 

Example E-4-. The get_args Procedure 

/* FILE NAME: getargs.c */ 
ttinclude <stdio.h> 
#include <stdlib.h> 
#include <string.h> 

get_args(argc, argv, local_fh, host, remote_name) 
int argc ; 



Microsoft RFC Programming Guide 



Example E-4-. The get_args Procedure (continued) 

char *argv[] ; 
FILE **local_fh; 
char host [ ] ; 
char remote_name [ ] ; 
{ 

char local_name[100] ; 

switch (argc) { 
case 1: 

case 2: printf ("Usage: %s [local_file] host [remote_f ile] \n" , argv[0]) 
puts ("Use \"\" for local stdin."); 
exit(O); 
break; 

case 3: strcpy (local_nanie, argv[l]); /* use the same file name */ 
strcpy ( remote_name , local_name ) ; 
strcpy (host , argv [2 ] ) ; 
break; 

default : strcpy ( local_name , argv [ 1 ] ) ; 
strcpy (host , argv [2 ] ) ; 
strcpy ( remote_name , argv [ 3 ] ) ; 
break; 
} 

if (strlen(local_name) ==0) { 
(*local_fh) = stdin; 
puts ("Using stdin. Type input:"); 
} 
else 

if( ( (*local_fh) = fopen(local_name, "r")) == NULL ) { 
puts ("Cannot open local file"); 
exit ( 1 ) ; 
} 
return; 



Example E-5: The do_string_binding Procedure 

/* FILE NAME: strbind.c */ 

/* Find a server binding handle from strings of binding information */ 

/* including protocol sequence, host address, and server process endpoint. */ 

ttinclude <stdio.h> 

#include "rfile.h" 

ttinclude " status. h" /* contains the CHECK_STATUS macro */ 

int do_string_binding(host, binding_h) /*return=0 if binding valid, else -1 */ 
char host[]; /* server host name or network address input */ 

rpc_binding_handle_t *binding_h; /* binding handle is output */ 

{ 

RPC_PROTSEQ_VECTOR *protseq_vector; /* protocol sequence list */ 
unsigned char *string_binding; /* string of binding information */ 
unsigned long status; /* error status */ 

int i , result ; 

status = 

RpcNetworklnqProtseqs ( /* obtain a list of valid protocol sequences */ 
&protseq_vector /* list of protocol sequences obtained */ 



Appendix E: The Rflle Application 197 

Example E-5: The do_string_binding Procedure (continued) 

); 

CHECK_STATUS( status, "Can t get protocol sequences:", ABORT); 

/* loop through protocol sequences until a binding handle is obtained */ 
for(i=0; i < protseq_yector->Count; i++) { 

status = 

RpcStringBindingCompose ( /* make string binding from components */ 

NULL, /* no object UUIDs are required */ 

protseq_vector->Protseq[i] , /* protocol sequence */ 

(unsigned char *)host, /* host name or network address */ 

NULL, /* no endpoint is required */ 

NULL, /* no network options are required */ 

&string_binding /* the constructed string binding */ 

); 

CHECK_STATUS( status, "Can t compose a string binding:", RESUME); 

status = 

RpcBindingFromStringBinding ( /* convert string to binding handle */ 

string_binding, /* input string binding */ 

binding_h /* binding handle is obtained here */ 

); 

CHECK_STATUS( status, "Can t get binding handle from string:", RESUME); 
if (status != RPC_S_OK) { 

result = -1; 

CHECK_STATUS( status, "Can t get binding handle from string:", RESUME); 
} 
else 

result = 0; 

status = 

RpcStringFree ( /* free string binding created */ 

&string_binding 
); 

CHECK_STATUS( status, "Can t free string binding :", RESUME); 
if (result == 0) break; /* got a valid binding */ 

} 

status = 

RpcProtseqVectorFree ( /* free the list of protocol sequences */ 

&prot seq_vector 
); 

CHECK_STATUS( status, "Can t free protocol sequence vector :", RESUME); 
ret urn (result) ; 
} 

Example E-6: The Context Rundown of the Remote File Application 

/* FILE NAME: crndwn.c */ 
#include <stdio.h> 
#include "rfile.h" 

void filehandle_rundown(remote_fh) 

filehandle remote_fh; /* the context handle is passed in */ 

{ 

fprintf (stderr, "Server executing context rundown\n" ) ; 



198 Microsoft RPC Programming Guide 

Example E-6: The Context Rundown of the Remote File Application (continued) 

if ( (FILE *)remote_fh != stdout ) 

f close ( (FILE *)remote_fh ) ; /* file is closed if client is gone */ 
remote_fh = NULL; /* must set context handle to NULL */ 

return; 
} 

Example E- 7: Remote Procedures of the Remote File Application 

I* FILE NAME: manager. c */ 

# include <stdio.h> 
#include <string.h> 

# include <io.h> 

# include <errno.h> 
ttinclude "rfile.h" 

filehandle remote_open(binding_h, name, mode) 

rpc_binding_handle_t binding_h; 

char name t ] ; 

char mode [ ] ; 

{ 

FILE *FILEh; 

if (strlen( (char *)name) == 0) /* no file name given */ 

if (strcmp( (char *)mode, "r") == 0) 

FILEh = NULL; /* cannot read nonexistent file */ 

else FILEh = stdout; /* use server stdout */ 

else if (_access ( (char *)name, 0) == 0) /* file exists */ 

if (strcmp( (char *)mode, "w" ) == 0) 

FILEh = NULL; /* do not overwrite existing file */ 

else FILEh = f open ((char *)name, (char *)mode) ; /* open read/append */ 

else /* file does not exist */ 

if (strcmp( (char *)mode, "r") == 0) 

FILEh = NULL; /* cannot read nonexistent file */ 

else FILEh = f open ( (char *)name, (char *)mode); /* open write/append */ 

return( (filehandle) FILEh ); /* cast FILE handle to context handle */ 



long int remote_send(fh, buf, max) 

filehandle fh; 

buffer buf; 

long int max; 

{ 

/* write data to the file (context) , which is cast as a FILE pointer */ 

return( fwrite(buf, max, 1, fh) ) ; 



void remote_close(fh) 

filehandle *fh; /* the client stub needs the changed value upon return */ 

{ 

if( (FILE *) (*fh) != stdout ) 
f close ( (FILE *) (*fh) ); 

(*fh) = NULL; /* assign NULL to the context handle to free it */ 



Appendix E: The Rflle Application 199 

Example E- 7: Remote Procedures of the Remote File Application (continued) 

return; 

} 

Example E-8: Server Initialization of the Remote File Application 

/* FILE NAME: server. c */ 

ttinclude <stdio.h> 

#include "rfile.h" /* header created by the idl compiler */ 

# include " status. h" /* contains the CHECK_STATUS macro */ 

main () 

{ 

unsigned long status; /* error status */ 

rpc_binding_vector_t *binding_vector; /* binding handle list */ 

status = /* error status */ 

RpcServerRegisterlf ( /* register interface with the RFC runtime */ 

rfile_vl_0_s_ifspec, /* handle for interface specification */ 

NULL, 

NULL 
); 
CHECK_STATUS ( status, "Can t register interface", ABORT); 

status = 

RpcServerUseAllProtseqs ( /* establish protocol sequences */ 

RPC_C_PROTSEO_MAX_REQS_DEFAULT, /* queue length for remote calls */ 
NULL /* no security descriptor */ 

); 

CHECK_STATUS( status, "Can t establish protocol sequences", ABORT); 

status = 

RpcServerlnqBindings ( /* get set of this server s binding handles */ 

&binding_vector 
); 
CHECK_STATUS( status, "Can t get binding handles", ABORT); 

status = 

RpcEpRegister ( /* add endpoint to local endpoint map */ 

rfile_vl_0_s_ifspec, /* handle for interface specification */ 

binding_yector, /* vector of server binding handles */ 

NULL, /* no object UUIDs to register */ 

(unsigned char *) "remote_file server" /* annotation (not required) */ 

); 

CHECK_STATUS( status, "Can t add endpoints to local endpoint map:", ABORT); 

puts ("Listening for remote procedure calls..."); 

RpcTryFinally 

{ 

status = 

RpcServerListen ( /* listen for remote calls */ 

1, /* Minimum number of threads */ 

RPC_C_LISTEN_MAX_CALLS_DEFAULT, /* Maximum number of threads */ 
NULL 
); 
CHECK_STATUS( status, "rpc listen failed:", RESUME); 



200 Microsoft RFC Programming Guide 

Example E- 8: Server Initialization of the Remote File Application (continued) 

RpcFinally 
{ 

puts ( "Removing endpoints from local endpoint map."); 

status = 

RpcEpUnregister ( /* remove endpoints from local endpoint map */ 
rfile_vl_0_s_ifspec, /* handle for interface specification */ 
binding_vector, /* vector of server binding handles */ 

NULL /* no object UUIDs to unregister */ 

); 

CHECK_STATUS( status, "Can t remove endpoints from endpoint map:", RESUME); 

status = 

RpcBindingVectorFree ( /* free set of binding handles */ 

&binding_vector 
); 

CHECK_STATUS ( status , "Can t free binding handles and vector", ABORT); 
} 

RpcEndFinally 
} 

/*** MIDL_user_al locate / MIDL_user_free ***/ 

void * __RPC_API 
MIDL_user_al locate 



size_t size; 
{ 

unsigned char * ptr; 
ptr = malloc ( size ) ; 
return ( (void *)ptr 



void __RPC_API 
MIDL_user_free 
( 

object 
) 

void * object; 
{ 

free (object) ; 



In this Appendix: 

How to Build and 
Run the Application 

Application Files 




The Windows 
Phonebook Application 



The phonebook application demonstrates a simple Windows client interface to a 
Microsoft RFC application. The Windows client looks up names in a phonebook 
database file maintained by the phonebook server (phnbkd.exe). The client does 
not use the Microsoft Locator name service, so you need to supply the server host 
name or address to a dialog box in the client interface. 

How to Build and Run the Application 

To build and run the server of the distributed application, type the following: 

C:\SERVER> nmake phnbkd.exe 
C:\SERVER> phiibkd 

To build and run the Windows client of the distributed application, type the fol 
lowing: 

C:\CLIENT> nmake phnbk.exe 
C:\CLIENT> phnbk 

Enter a hostname or address into the Server Host Name dialog box. Try the browse 
feature first to see some names. Then enter names into the Search String dialog 
box. 

Application Files 

Makefile contains descriptions of how the application is compiled. See Example 
F-l. 

phnbk.idl contains descriptions of the data types and procedures for the interface. 
See Example F-2. 



207 



202 Microsoft RFC Programming Guide 

pbnbk.acf is an attribute configuration file that specifies implicit binding as the 
client binding method. See Example F-3. 

wclient.c provides a Windows user interface to the server (phnbkd.exe). The client 
invokes remote procedure calls based on user actions. See Example F-4. 

wpbnbk.defis a Windows module definition file. It defines the name of the appli 
cation, the type of image to be produced, and other attributes of the application. 
See Example F-5. 

wphnbk.h is a header file that defines constants used in wphnbk.c and in the 
resource file wpbnbk.rc. See Example F-6. 

wphnbk.rc is a Windows resource file. It describes the size and appearance of the 
Windows dialog box and of the controls (such as buttons and edit boxes) used by 
the application. See Example F-7. 

manager, c is the implementation of the remote procedures defined in the phnbk 
interface. The remote procedures look up names contained in the phnbk.txt 
database file. See Example F-8. 

server. c initializes the server with a series of runtime calls prior to servicing remote 
procedure calls. This application specifies to use the TCP/IP protocol sequence. 
The server is not advertised in a name service database. The server s dynamic end- 
points are added to the server s local endpoint map. A client finds this server by 
constructing a string binding containing a protocol sequence and the host name or 
network address. See Example F-9. 

phnbk.txt is an ASCII file containing the database of names used by the phonebook 
server. We created it using a text editor. You can add your own lines to this file. 
Make sure lines are under 100 characters in length. See Example F-10. 

Example F-l: The Makefile for the Windows Phonebook Application 

# 
# 

# Build phnbk client and server for Windows NT 
# 

# 

! INCLUDE <ntwin32.mak> 

includes = -I. 

all : phnbk.exe phnbkd.exe 

# 

# Link simple client 
# 

phnbk.exe: wclient.obj wphnbk.obj phnbk_c.obj 

$(link) $(linkdebug) $(guiflags) -out: phnbk.exe \ 
wclient.obj phnbk_c.obj wphnbk.obj \ 
rpcrt4.1ib rpcns4.1ib rpcndr.lib $(guilibs) 



Appendix F: The Windows Phonebook Application 203 

Example F-l: The Makefile for the Windows Phonebook Application (continued) 

# Link server 

# 

phnbkd.exe: server. obj manager. obj phnbk_s.obj 

$(link) $ (linkdebug) $(conflags) -out: phnbkd.exe \ 

server. obj manager. obj phnbk_s.obj \ 

rpcrt4.1ib rpcns4.1ib rpcndr.lib $(conlibs) 
# 

# .RES 
# 

wphnbk . obj : wphnbk . re 

re -r wphnbk. re 

cvtres -$(CPU) wphnbk. res 
# 

# Compile simple client source code 

# . 

wclient.obj: wclient.c phnbk.h 

$(cc) $(cflags) $(cvars) $(scall) $ (includes) wclient.c 

# 

# Compile server source code 
# 

server. obj: server. c phnbk.h 

$(cc) $(cflags) $(cvars) $(scall) $ (includes) server. c 

manager. obj: manager. c phnbk.h 

$(cc) $(cflags) $(cvars) $(scall) $ (includes) manager. c 

# 

# Compile client stubs 
# 

phnbk_c.obj : phnbk_c.c phnbk.h 

$(cc) $(cflags) $(cvars) $(scall) $ (includes) phnbk_c.c 

## 

# $(cc) $(cflags) $(cvars) $(scall) $ (includes) phnbk_x.c 

# 

# Compile server stubs 
# 

phnbk_s.obj : phnbk_s.c 

$(cc) $(cflags) $(cvars) $(scall) $ (includes) phnbk_s.c 

#phnbk_v.obj : phnbk_y.c 

# $(cc) $(cflags) $(cvars) $(scall) $ (includes) phnbk_y.c 

# 

# Generate stubs and header file from interface definition 
# 

phnbk.h : phnbk.idl phnbk.acf 
midl phnbk.idl 

# 

# Clean up for fresh build 

# 
clean : 



Microsoft RFC Programming Guide 



Example F-l: The Makefile for the Windows Phonebook Application (continued) 

del phnbk_*.* 
del *.obj 
del phribk.h 

# 

# Clean up all byproducts of build 

# 

clobber : clean 

del phnbk.exe 

del phnbkd.exe 

del *.res 

Example F-2: The MIDI File of the Windows Phonebook Application 

/* 

** Interface definition file for irrplicit phnbk client 

*/ 



uuid(F2FE85AO-OC28-1068-A726-AA0004007EFF) , 

version (1.0) , 

pointer_default (ref ) ] 
interface phnbk 
{ 

/* 

** Constant for maximum line size 
*/ 
const long LINESIZE = 100; 

/* 

** Flag for hitting end of phonebook file 

*/ 

const short END = -1; 

/* 

** Flag for normal completion of operation 

*/ 

const short NORMAL = 0; 

/* 

** Define all possible operations on phonebook file 
*/ 

typedef enum 
{ 

FIRSTMATCH, 

NEXTMATCH, 

BROWSE, 

RESET, 

BROWSE_RESET 
} operations; 

/* 

** Perform some operation on the phonebook 

*/ 

short 

lookup 



Appendix F: The Windows Phonebook Application 205 

Example F- 2: The MIDI File of the Windows Phonebook Application (continued) 

( 

[in] short operation, 

[in, string] char search_string [LINESIZE] , 
[out, string] char return_string [LINESIZE] 
); 
} 

Example F~3: The ACF File of the Windows Phonebook Application 

[inplicit_handle (handle_t xhandle) ] interface phnbk {} 

Example F-4: Client File of the Windows Phonebook Application 

/* 
** 

** 

** MODULE: wclient.c 



** PROGRAM: Windows wphnbk application 
** 

** 

** 
** 

*/ 

ttinclude <windows.h> 
ttinclude <stdlib.h> 
# include <string.h> 
# include <ctype.h> 

Mnclude "phnbk. h" 
#include "wphnbk. h" 



int lookup_status ; /* lookup return status */ 

error_status_t status; /* rpc status */ 

unsigned char input [LINESIZE] ; /* find search string */ 

char output [LINESIZE] ; /* string returned from database */ 

char oldmatch [LINESIZE] ;/* previous find string */ 

unsigned char server [80]; /* string binding for server */ 

short operation; /* operation requested */ 

short no_handle; /* handle not initialized flag */ 

unsigned char hostname [ 32 ]; /* phnbk server host name */ 

long FAR PASCAL WndProc (HWND, WORD, WDRD, LONG) ; 

int 

PASCAL WinMain 

( 

HANDLE hlnstance, 

HANDLE hPrevInstance, 

LPSTR IpszCmdLine, 

int nCmdShow 



206 



Microsoft RFC Programming Guide 



Example F-4: Client File of the Windows Phonebook Application (continued) 



char szAppName [] = "WPHNBK" 
HWND hwnd ; 

MSG msg; 

WNDCLASS wndclass ; 



/* 

** Initialize strings 

*/ 

input [0] 

output [0] 

oldmatch[0] = 

server [ ] = 

hostname [ ] = 

no_handle = TRUE; 

/* 

** Standard Windows stuff. 

*/ 

if ( IhPrevInstance) 



wndclass 
wndclass 
wndclass 
wndclass 
wndclass . 
wndclass . 
wndclass . 
wndclass . 
wndclass . 
wndclass . 



style 

IpfnWndProc 

cbClsExtra 

cbWndExtra 

hlnstance 

hlcon 

hCursor 

hbrBackground 

IpszMenuName 

IpszClassName 



CS_HREDRAW I CS_VREDRAW; 
(WNDPROC) WndProc ; 



= 



DLGWINDOWEXTRA ; 
hlnstance ; 

Loadlcon (hlnstance, szAppName) ; 
LoadCursor ( (HINSTANCE)NULL, IDC_ARRCW) 
(HBRUSH) (COLORJWINDOW + 1) ; 
NULL ; 
szAppName ; 



RegisterClass (&wndclass) ; 

hwnd = CreateDialog (hlnstance, szAppName, 0, NULL) 

ShowWindow (hwnd, nCmdShow) ; 

SetFocus ( GetDlgltem (hwnd, HOSTNAMEBOX ) ) ; 

/ * 

** Start accepting messages 

*/ 

while ( GetMessage (&msg, NULL, 0, 0) ) 

TranslateMessage (&msg) ; 
DispatchMessage (&msg) ; 

return msg.wParam ; 



short 
InitHandle 



HWND hwnd 



Appendix F: The Windows Phonebook Application 207 

Example F- 4: Client File of the Windows Phonebook Application (continued) 



I* 

** Read server host name 

*/ 

GetDlgltemText (hwnd, HOSTTSIAMEBOX, hostname, 16 ) ; 

/* 

** Warn user if they haven t specified a host name 
*/ 

if (hostname [0] == \0 ) 
{ 

MessageBox 
( 

hwnd, 

"Please enter server host name", 
"ERROR", 
MB_OK 
); 

SetFocus ( GetDlgltem (hwnd, HOSTOAMEBOX) ) ; 
return (-1) ; 



/* 

** Build server string binding 
*/ 

strcat (server, "ncacn_ip_tcp: " ) ; 
strcat (server, hostname) ; 
/* 

** Convert the character string binding into an RFC handle 
*/ 

status = RpcBindingFromStringBinding 
( 

server, 

&xhandle 



if (status) 
{ 
MessageBox 



hwnd, 

"Invalid string binding", 

"ERROR", 

MB_OK 



exit (EXIT_FAILURE) ; 
} 

no_handle = FALSE; 
return (0); 



208 Microsoft RFC Programming Guide 

Example F-4-. Client File of the Windows Phonebook Application (continued) 



void 
ShowResult 

HWND hwnd 
) 
{ 

/* 

** Display lookup results, based on the context of 

** the requested operation 

*/ 

if (operation == BROWSE) 

/* 

** BROWSE return next entry 

*/ 

if ( lookup_status == NORMAL) 

/* 

** Everything ok, display next entry 

*/ 

SetDlgltemText (hwnd, RESULTSBOX, output ) ; 
else 

/* 

** Otherwise, we hit end of file... 

*/ 

SetDlgltemText (hwnd, RESULTSBOX, " " ) ; 

SetDlgltemText (hwnd, INFOBOX, "No more entries"); 



else 



/* 

** Operation was a Find or Find Next. . .tailor message 

** syntax to reflect the operation. 

*/ 

if ( lookup_status == NORMAL) 

{ 

/* 

** Print results 

*/ 

SetDlgltemText (hwnd, RESULTSBOX, output ) ; 

/* 

** Determine if this was first match, or subsequent match 

*/ 

if (operation == FIRSTMATCH) 

SetDlgltemText (hwnd, INFOBOX, "Match found" ) ; 
else 

SetDlgltemText (hwnd, INFOBOX, "Another match found" ) ; 



Appendix F: The Windows Phonebook Application 209 

Example F- 4: Client File of the Windows Phonebook Application (continued) 

else 
/* 

** Hit end of file during search 
*/ 
if (operation == FIRSTMATCH) 

SetDlgltemText (hwnd, INFOBOX, "Match not found" ) ; 
else 

SetDlgltemText (hwnd, INFOBOX, "No other matches found" ) ; 
} 

return; 



long 

FAR PASCAL WndProc 
( 

HWND hwnd, 
WORD message, 
WORD wParam, 
LONG iParam 



/* 

** We switch cursors to the hourglass during 

** a lookup RPC. This is for saving the 

** regular pointer. 

*/ 

HCURSOR OldCursor; 

/* 

** First thing, save the match string from last time around 

*/ 

strcpy (oldmatch, input) ; 

/* 

** Switch on the incoming message type (standard Windows 

** programming) 

*/ 

switch (message) 

{ 

/* 

** Got a button pushed 

*/ 

case WM_COMMAND: 

switch (wParam) 
{ 

/* 

** Either a Find or a Find Next 
*/ 

case FINDBUTTON: 
if (no_handle) 

if (InitHandle(hwnd) ) break; 



210 Microsoft RFC Programming Guide 

Example F- 4: Client File of the Windows Phonebook Application (continued) 

/* 

** Clear current text 

*/ 

SetDlglterrtText (hwnd,RESULTSBOX, " " ) ; 

SetDlgltemText (hwnd, HSJFOBOX, " " ) ; 

/* 

** Read the search string 

*/ 

GetDlgltemText (hwnd, SEARCHBOX, input , 32 ) ; 

/* 

** Make sure user entered a search string 
*/ 

if (input[0] == (unsigned char) \0 ) 
{ 

MessageBox 
( 

hwnd, 

"Missing Search String!", 
"ERROR", 
MB_OK 
); 
/* 

** Set focus back to SEARCHBOX so user can 
** enter search string 
*/ 
SetFocus ( GetDlgltem (hwnd, SEARCHBOX) ) ; 



else 



/* 

** Search string is present. Save existing 

** pointer and display hourglass 

*/ 

OldCursor = SetCursor (LoadCursor (NULL,IDC_WAIT) 

ShowCursor (TRUE) ; 

/* 

** Determine desired operation 

*/ 

if (strcmpfoldmatch, input) ) 

operation = FIRSTMATCH; 
else 

operation = NEXTMATCH; 

/* 

** Perform the requested operation 

*/ 

lookup_status = lookup 

( 

operation, 

input , 

output 



Appendix F: The Windows Phonebook Application 211 

Example F- 4: Client File of the Windows Phonebook Application (continued) 



/* 

** Restore pointer cursor 

*/ 

ShowCursor (FALSE) ; 

SetCursor ( OldCursor ) ; 

/* 

** Display lookup results 

*/ 

ShowResult (hwnd) ; 



break; 

/* 

** BROWSE return next entry 

*/ 

case BROWSEBUTTON: 

if (no_handle) 

i f ( Ini tHandle ( hwnd ) ) break ; 

/* 

** Clear existing text and display status 

*/ 

SetDlgltemText (hwnd, RESULTSBOX, " " ) ; 

SetDlgltemText (hwnd, SEARCHBOX, "" ) ; 

SetDlgltemText (hwnd, INFOBOX, "Browsing. . . " ) ; 

/* 

** Switch to hourglass cursor 

*/ 

OldCursor = SetCursor (LoadCursor (NULL,IDC_WAIT) 

ShowCursor (TRUE) ; 



operation = BROWSE; 

/* 

** Perform the requested operation 

*/ 

lookup_status = lookup 
( 

operation, 
input, 
output 



/* 

** Restore pointer cursor 

*/ 

ShowCursor (FALSE) ; 

SetCursor ( OldCursor ) ; 



212 Microsoft RFC Programming Guide 

Example F- 4: Client File of the Windows Phonebook Application (continued) 

** Display operation results 

*/ 

ShowResult (hwnd) ; 

break; 

/* 1 

** User has requested a RESET. This clears all 

** text and rewinds the phonebook file 

*/ 

case RESETBUTTON: 

if (no_handle) 

if (InitHandle(hwnd) ) break; 

/* 

** Clear all text 

*/ 

SetDlgltemText (hwnd, RESULTSBOX, " " ) ; 

SetDlglteinText (hwnd, INFOBOX, " " ) ; 

SetDlgltemText (hwnd, SEARCHBOX, " " ) ; 

input [0] = \0 ; 
operation = RESET; 

/* 

** Perform the requested operation 

*/ 

lookup_status = lookup 

( 

operation, 

input , 

output 
); 

break; 



return ; 

/* 

** User has closed the application 
*/ 

case WM_DESTROY: 
if (!no_handle) 
{ 

/* 

** Free binding handle, post quit message and leave 
*/ 

status = RpcBindingFree 
( 
&xhandle 



PostQuitMessage (0) ; 



Appendix F: The Windows Phonebook Application 213 

Example F-4: Client File of the Windows Phonebook Application (continued) 

return ; 

/* 

** Ignore other messages 

*/ 

default : 

return DefWindowProc (hwnd, message, wParam, iParam) ; 



Example F-5: Window Module Definition File 

; WPHNBK.DEF module definition file 



NAME WPHNBK 

DESCRIPTION Windows RFC Phonebook 

EXETYPE WINDOWS 

STUB WINSTUB.EXE 

CODE PRELOAD FIXED DISCARDABLE 

DATA PRELOAD FIXED MULTIPLE 

HEAPSIZE 8192 

STACKSIZE 8192 

EXPORTS WndProc 

Example F-6: Header File 

#define SEARCHBOX 102 
#define RESULTSBOX 104 
#define INFOBOX 106 
#define FINDBUTTON 113 
#define BROWSEBUTTON 112 
#define RESETBUTTON 110 
ttdefine HOSTNAMEBOX 109 

Example F- 7: Resource File 

ttinclude <windows.h> 
#include "wphnbk.h" 

WPHNBK DIALOG 15, 33, 315, 102 

CAPTION "Windows RFC Phonebook" 

STYLE WS_OVERLAPPED | WS_BORDER I WS_CAPTION I WS_SYSMENU I WS_MINIMIZEBOX 

CLASS "WPHNBK" 

BEGIN 

CONTROL "Search String:", 100, "static", SS_LEFT I WS_CHILD, 
13, 18, 47, 10 

CONTROL "Input", 101, "button", BS_GROUPBOX I WS_TABSTOP I WS_CHILD, 

5, 3, 173, 32 

CONTROL "", 102, "edit", ES_LEFT I WS_BORDER I WSJTABSTOP I WS_CHILD, 

63, 17, 108, 12 

CONTROL "Search Results:", 103, "static", SS_LEFT | WS_CHILD, 

6, 50, 58, 7 

CONTROL "", 104, "edit", ES_LEFT | WS_BORDER | WS_TABSTOP I WS_CHILD, 

64, 48, 239, 12 



214 Microsoft RPC Programming Guide 

Example F- 7: Resource File (continued) 

CONTROL "Status:", 105, "static", SS_LEFT I WS_CHILD, 6, 80, 26, 8 
CONTROL "", 106, "edit", ES_LEFT I WS_BORDER I WSJTABSTOP I WS_CHILD, 

30, 78, 133, 12 
CONTROL "Output", 108, "button", BS_GROUPBOX I WS_TABSTOP I WS_CHILD, 

4, 36, 305, 31 
CONTROL "Information", 111, "button", BS_GROUPBOX I WS_TABSTOP I WS_CHILD, 

4, 68, 305, 31 
CONTROL "Find / Find Next", 113, "button", 

BS_PUSHBUTTCN I WSJTABSTOP I WS_CHILD, 192, 6, 112, 14 
CONTROL "Reset", 110, "button", BS_PUSHBUTTON I WS_TABSTOP I WS_CHILD, 

192, 22, 50, 14 
CONTROL "Browse", 112, "button", BS_PUSHBUTTCN I WS_TABSTOP I WS_CHILD, 

258, 22, 46, 14 
CONTROL "", HOSTNAMEBOX, "edit", ES_LEFT I WS_BORDER | WS_TABSTOP I WS_CHILD, 

228, 78, 76, 12 
CONTROL "Server Host Name: ",107, "static", SS_LEFT I WS_CHILD, 

166, 80, 62, 8 
END 



Example F-8: Remote Procedures 

/* 
** 



MODULE: manager. c 



* PROGRAM: phnbk application 

I 
** 

** 
** 
** 

*/ 

#include <stdio.h> 
#include <string.h> 
ttinclude <malloc.h> 
#include <stdlib.h> 

ttinclude "phnbk. h" 

#ifdef WIN32 
#endif 

extern FILE *filehandle; /* Phonebook file filehandle */ 

extern short previous_operation; /* Keeps track of previous operation */ 

/* 

** 

** FUNCTION: getfileline 
** 

** PURPOSE: 

** Retrieve Lines from input file 



Appendix F: The Windows Phonebook Application 215 

Example F- 8: Remote Procedures (continued) 

*/ 
int 

getfileline 
( 

line, 
phone 
) 

unsigned char * line; 
FILE * phone; 
{ 

/* 

** Each call of this routine returns a line of the 

** phonebook file. On EOF, it returns -1. 

*/ 

char ch; 

while ((ch = fgetc (phone) ) != \n && ch != EOF) 
{ 

/* 

** Tabs are unpredictable, so substitute 
** three spaces if you run across a tab. . . 
*/ 
if (ch == \t ) 

{ 

*line++ = ; 

*line++ = ; 

*line++ = ; 

} 
else 

*line++ = ch; 



*line++ = \0 ; 

if (ch == EOF) 

return (END) ; 
else 

return (NORMAL) ; 
} 

/* 
** 

** FUNCTION: lookup 
** 

** PURPOSE: 

Look up entries in database 
** 

*/ 

short 
lookup 
( 

op, 

stringin, 



Microsoft RFC Programming Guide 



Example F-8: Remote Procedures (continued) 

stringout 
) 

short op; 

unsigned char stringin[LINESIZE] ; 
unsigned char stringout [LUSESIZE] ; 
{ 

unsigned char buf [LINESIZE] ; 

/* 

** Switch on requested operation 
*/ 

switch (op) 
{ 
case RESET: 

/* 

** Reset context 

*/ 

printf ( "Phonebook: \tRESET\n" ) ; 

rewind (filehandle) ; 
previous_operation = FIRSTMATCH; 
return (NORMAL) ; 
break; 

case FIRSTMATCH: 
/* 

** Look for first match of a string, starting at the 
** beginning of the file... 
*/ 
printf ( "Phonebook: \tFIRSTMATCH\n" ) ; 

rewind (filehandle) ; 
break; 

case NEXTMATCH : 
/* 

** Nothing special here, fall out and continue search 
*/ 

printf ( "Phonebook: \tNEXTMATCH\n" ) ; 
break; 

case BROWSE : 
/* 

** A BROWSE operation just returns the next entry... 
** 

** If the last operation was a BROWSE that got an EOF, 

** then rewind and start cycling through again. 

*/ 

printf ( "Phonebook: \tBROWSE\n" ) ; 

if (previous_operation == BROWSE_RESET) 
rewind (filehandle); 



Appendix F: The Windows Phonebook Application 217 

Example F-8: Remote Procedures (continued) 

if ((getfileline(buf,filehandle)) != -1) 
{ 

/* 

** If not EOF, then just return next entry. 

*/ 

strcpy ( ( char * ) stringout , ( char * ) buf ) ; 

printf ("Phonebook: \tFound %s\n", buf); 
previous_operation = BROWSE; 

return (NORMAL) ; 
} 

else 
{ 

/* 

** This allows the client to flag "no more entries" 
** before cycling through the file again on 
** another BROWSE request. 
*/ 
previous_operation = BROWSE_RESET; 

return (END) ; 



/* 

** Keep track of previous operation in p_context 

*/ 

previous_operation = op; 

/* 

** Either return the line of the file that contains a string 

** match, or return -1... 

*/ 

while ( (getfileline(buf,filehandle) ) != -1) 
{ 
if ( (strstrf (char *)buf, (char *)stringin)) != (char *) NULL) 

{ 

printf ("Phonebook: \tFound %s\n" , buf); 

strcpy ( (char *) stringout, (char *)buf) ; 

return (NORMAL) ; 



return (END) ; 



Example F-9: Server Initialization 

/* 
** 

** 

** MODULE: server. c 
** 



218 Microsoft RFC Programming Guide 

Example F- 9: Server Initialization (continued) 
** 

** PROGRAM: phribk application 

** 

** 

** 

** 

** 

*/ 

#include <stdio.h> 
#include <string.h> 
ttinclude <stdlib.h> 
#include <malloc.h> 

#include "phnbk.h" 

#ifdef WIN32 

#define MAIN_DECL _CRTAPIl 

#else 

#define MAIN_DECL 

#include <dce/rpcexc.h> 

#endif 

#define IFSPEC phnbk_vl_0_s_ifspec 

FILE * filehandle; /* File handle used for phonebook file */ 

short previous_operation; /* Keeps track of previous phonebook operation */ 

int 

MAIN_DECL main 
( 

ac, 
av 
) 

int ac; 
char *av [ ] ; 
{ 

unsigned int i; 

error_status_t status ; 

unsigned char *string_binding; 

RPC_BINDING_VECTOR *bvec; 

/* 

** 

** Specify TCP/IP as a protocol sequences 

*/ 

status = RpcServerUseProtseq 

( 

"ncacn_ip_tcp" , 

5, 

NULL 
); 

if (status != RPC_S_OK) 



Appendix F: The Windows Phonebook Application _ 219 

Example F-9: Server Initialization (continued) 

printf("No available protocol sequences \n "); 

exit (EXIT_FAILURE) ; 

} 

/* 

** register the server interface 
*/ 

status = RpcServerRegisterlf 
( 

IFSPEC, 
NULL, 
NULL 
); 

if (status != RPC_S_OK) 
{ 

printf ("Can t register interface \n"); 
exit (EXIT_FAILURE) ; 

} 

/* 

** find out what binding information is actually available 

*/ 

status = RpcServerlnqBindings 

( 
&bvec 

); 

if (status != RPC_S_OK) 
{ 

printf ("Can t inquire bindings \n"); 
exit (EXIT_FAILURE) ; 

} 

/* 

** register with endpoint mapper 
*/ 

status = RpcEpRegister 
( 

IFSPEC, 

bvec, 

NULL, 

(unsigned char *)"phnbk endpoint" 
); 

if (status != RPC_S_OK) 
{ 

printf ("Can t register endpoint \n "); 
exit (EXIT_FAILURE) ; 



** Get the string bindings and print them 

*/ 

for (i = 0; i < bvec->Count; i++) 



220 Microsoft RFC Programming Guide 

Example F-9: Server Initialization (continued) 



** For each binding, convert it to a 
** string representation 
*/ 

status = RpcBindingToStringBinding 
( 

bvec->BindingH [ i ] , 
&string_binding 
); 

if (status != RPC_S_OK) 
{ 

print f ("Can t get string binding \n"); 
exit (EXIT_FAILURE) ; 
} 

printf ( " %s\n" , string_binding) ; 
} 

/* 

** Open the phonebook file 

*/ 

f ilehandle = f open ( "phnbk . txt " , " r " ) ; 

/* 

** Server is all ready to start listening for client 

** requests. . . 

*/ 

status = RpcServerListen 



1, 
2, 





if (status != RPC_S_OK) 

printf ( "Error: rpc_server_listen ( ) returned \n" ) ; 

return (EXIT_FAILURE) ; 
} 
#ifdef WIN32 

/*** MIDL_user_allocate / MIDL_user_free ***/ 

void * __RPC_API 
MIDL_user_allocate 



size_t size; 
{ 

unsigned char * ptr; 



Appendix F: The Windows Phonebook Application 221 

Example F-9: Server Initialization (continued) 

ptr = malloc ( size ) ; 
return ( (void *)ptr ) ; 



void _RPC_API 
MIDL_user_free 

object 
void * object; 

free (object) ; 

#endif 

Example F- 1 0: Sample Input Data 

Mickey Mouse 555-2345 

Donald Duck 555-2342 

Pluto 555-4564 

James T. Kirk 555-2342 

Fred Flintstone 555-2342 

Spider Man 555-2345 

Bat Man 555-2342 

George Jetson 555-2342 

Peter Pan 555-4312 

John Doe 555-8888 

Charlie Brown 555-2374 



Index 



[] (brackets) in MIDL, 30 

ACF (attribute configuration file), 42-44 

automatic binding, 49 

binding handles, 53 

binding methods, 48 

controlling errors, 44 

example of, 43 

exceptions, 44 

explicit binding, 53 

implicit binding, 51, 176 

separating client/server output, 42 

windows phnbk application, 205 

(see also binding methods) 
ACF attributes 

autojiandle, 43, 48-49, 140 

byte_count, 98 

code, 44, 140 

comm_status, 44, 140 

context_handle, 139-140 

dont_free, 98 

explicit_handle, 43, 48, 53, 140 

fault_status, 44, 140 

implicit_handle, 43-44, 48, 51, 140 

nocode, 44, 140 

(see also MIDL attributes) 
active context handles (see context handles) 
address, host network, 104 
advertising the server, 107-109 
aliasing, pointer, 83, 87 



allocating memory 

buffers, 97-98 

for conformant arrays, 93-94 

for context handles, 135 

freeing, 87 

inventory application, 158 

node-by-node, 96-97 

(see also memory management) 
applications 

arithmetic, 3, 149-156 

distributed, 149 

files, 150-156 

inventory, 30, 157-189 

managing, routines for, 145, 147 

memory management, 96 

producing and running, 21-24 

rfile, 129, 191-200 
arith.bat, 150 
arith.idl, 150 
arithmetic application, 3, 149-156 

CHECK_STATUS macro, 155 

client file, 153 

initialization, 153 

interface, 152 

Makefile, 150 

remote procedure, 153 

server shell script, 152 
array attribute, 137-138 
arrays, 34, 79, 90-94, 149 

conformant, 90-94, 116-117 
as procedure parameters, 93 
managing size of, 91-94 



223 



224 



Microsoft RFC Programming Guide 



arrays, conformant (cont d) 

memory allocation, 93-94 

fixed, 34, 90 

limiting transmission of, 34 

max_is, 35 

MIDI attributes of, 137-138 

size_is, 35 

specifying size of, 91-93 

varying, 90-91 

attribute configuration file (see ACF) 
attributes 

ACF (see ACF attributes) 

array, 137-138 

binding methods, 48 

data, 30-38, 139 

dont_free, 98 

header, 29, 137 

interface definition, 28 

MIDI (see MIDL attributes) 

pointer types, 138 

procedure, 139-140 

structure member, 139 

union case, 139 
authentication, 71 

binding information, 47 

managing, routines for, 43, 147 
authorization information, 47 
automatic binding, 49-50 

finding server, 122 

(see also binding methods) 
autojiandle attribute, 43, 48-49, 140 
auxiliary files, MIDL compiler, 41 

bind procedure, 68-69 
binding handles, 20, 45-70 

bind/unbind procedures, 68-69 
client, 113 

context handles, 133 
customized, 66-70 

designing, 67 
defining, 53-54 
endpoints in, 59 
fully bound, 59 
importing, 61-63 
looking up, 64 
managing, 46-55 

by clients, 47 

routines for, 43, 144 
partially bound, 59 



server initialization, 112 
binding information, 45-48 

client authentication, 47 

client, in server code, 113 

context handles, 48 

creating 

for servers, 104-107 
routines for, 43, 146 

exporting, 20, 125-126 

finding servers, 64-66 

host network address, 104 

in server entry, 123 

interpreting, 60-6 1 

inventory application, 158 

NSI routines, 14 

server endpoint map, 109 

to name service, 108 

with dynamic endpoints, 104-106, 123 
binding methods, 13-17, 46-55 

applying to interface(s), 47 

attributes, 48 

automatic, 46-50 
finding server, 122 
overriding, 50 

choosing, 48-49 

comparison of, 46 

establishing, 48 

explicit, 46, 52-55 

implicit, 46-47, 50-52 
and ACF, 51 
overriding, 52 

selecting with ACF, 43-44 
BITFTP, xix 

buffers, allocating, 97-98 
byte_count attribute, 98 

case keyword, 37 

Cell Directory Service (CDS), 14, 121 

char data type, 34 

CHECK_STATUS macro, 73-74, 104, 150, 155 

client files, generating, 42 

/client none, MIDL compiler, 42 

client.c, 150 

clients 

allocating buffers in, 97-98 

authentication information, 47 

authorization information, 47 

binding handles, 113 

binding information, 113 



Index 



225 



clients (cont d) 

interpreting, 6l 
managing handles, 47 

building, 149 

compiling, 21-23, 74-77 

context handles in, 131-133 

copying text to server, 129 

developing 

for automatic binding, 49-50 
for explicit binding, 54 
for implicit binding, 51-52 

development, errors in, 72-74 

example of, 9 

exception handling, 72 

finding from strings, 64-66 

inventory application file, 172 

linking, 21-23, 74-77 

managing, routines for, 43, 145 

of arithmetic application, 152 

phonebook application, 205 

producing, 74 

protocol sequences for, 58 

rfile applications, 195 

server communication break, 134, 136 

using discriminated unions, 38 

using name service, 6l 

writing, 45-77 

(see also servers) 
close_inventory procedure, 111 
code attribute, 44, 140 
communication breakdown, client/server, 

134, 136 

comm_status attribute, 44, 140 
compiler, MIDL (see MIDL compiler) 
compiling 

clients, 21-23, 74-77 

interfaces, 40-42 

of interface definition, 7 

servers, 21-23, 117-119 
CompuServe, xvi 
conformant arrays, 34, 90 

allocating memory, 93-94, 116-117 
dynamic, 93 

as procedure parameters, 93 

managing size of, 91-94 

MIDL attributes, 138 
conformant strings, 34-35 
conformant structure, 92, 94 
const keyword, 33 



constants, MIDL file, 33 
context handles, 48, 129-136 

active, 129, 134 

allocating memory for, 135 

establishing active, 132 

freeing, 133, 135 

in clients, 131-133 

in interface definition, 130-131 

in servers, 133-136 

opaque structure, 131 

with binding methods, 132 

writing procedures with, 134-135 
context rundown procedures, 130, 197 

writing, 136 
context storage, 98 

context_handle attribute, 130, 139-140 
contiguous server memory, 97 
conventions for entry names, 23 
crndwn.c, 192 
customizing 

binding handles, 66-70 

interface with ACF, 42-44 

data 

describing with MIDL attributes, 28 

limiting transmission, 34 

marshalling, 32 

privacy/integrity (see authentication) 

sharing between formats, 32 

structures. 101-102 
data attributes, MIDL, 30-38 

user-defined, 33 
datatypes, 139, 150 

DCE Cell Directory Service (CDS), 107, 121 
debugging remote procedures, 76 
DECnet, protocols with, 56 
DefaultEntry, 63 
directory service, 14 
discriminated unions, 36-38 

application code example, 37 

pointers as, 89 
distributed applications, 149 
do_import_binding, 54, 60, 62, 159, 178 
do_interpret_binding, 60, 63, 159, 179 
domain controllers, 126-127 
dont_free attribute, 98 
do_string_binding, 64, 68, 132, 196 
dynamic endpoints, 59-60, 110 

exporting, 108 



226 



Microsoft RFC Programming Guide 



dynamic endpoints (cont d) 

in binding information, 104-106, 123 

endpoint attribute, 106, 137 
endpoint map 

local, 15 

system, 109-110, 112 
endpoints 

dynamic, 104-106 

exporting, 108 

finding, 59-60 

managing 

in server, 109-110, 112 
routines for, 43, 144, 146 

server process, 14 

well-known, 106-107 

with client call requests, 100 
entry names, conventions, 23 
enum keyword, 35 
enumerated types, 35 
errors, 155 

ACF control, 44 

handling, 72-74 

reporting, routines for, 102 

(see also exceptions) 
error_status_t, 73, 140 

data type, 31, 44 
exceptions 

ACF, 44 

as parameters, 141 

handling, 43, 72-74 
routines for, 145, 147 

listening for RPCs, 111-112 

(see also errors) 
explicit binding, 52-55 

inventory application, 180 

MIDI file, 182 

remote procedures, 184 

(see also binding methods) 
explicitjiandle attribute, 43, 48, 53, 140 
exporting 

binding information, 20, 125-126 

endpoints, 108 

servers to name service, 147 

fault_status attribute, 44, 140 
filehandle_rundown procedure, 136 
finding servers, 13, 55-66 
with name service, 61-64 



nrst_is attribute, 90, 138 

fixed arrays, 34, 90 

floating-point numbers (see discriminated 

unions) 

free routine, 113 
FTP (file transfer program), xviii 
FTPMAIL, xix 

full pointers, 33, 80, 86-90, 140 
fully bound binding handle, 59 

get_args, 131, 195 
getargs.c, 192 
getbind.c, 62 

get_part_description, 115, 158 
group entries, RFC, 107 

handle attribute, 66, 139 
handles 

binding (see binding handles) 

context (see context handles) 

interface (see interfaces, handles) 
handle_t data type, 31, 43, 51, 53 
handling 

errors (exceptions), 72-74, 145 
inventory application, 158 

exceptions, 111-112 
header 

attributes, 137 
interface, 29-30 

files, 101-102 

generating a, 7 
header files, 102 
host network address, 104 

/I option, MIDL compiler, 42 

IDL (Interface Definition Language), 4 

(see also MIDL) 
if spec, 103 
ignore attribute, 139 
implicit binding, 50-52 

ACF file for, 176 

(see also binding methods) 
implicitjiandle, 43-44, 48, 51, 140 
in attribute, 38-40, 140 
indirection, multiple levels of, 84 
initializing 

arithmetic application, 153 

context handles, 132 

inventory application, 169 



Index 



227 



initializing (cont d) 

servers, 15, 18-19, 99-112 

advertising, 107-109 

creating binding information, 104-107 

header files, 101-102 

listening for RPCs, 110-112 

managing endpoints, 109-110, 112 

registering interfaces, 102-104 
input parameters, pointers as, 82-84 
intbind.c, 61 

interface definition, 4-7, 27-44 
attributes, 28 
binding methods, 48 
compiling, 7 

declaring varying array, 90 
defining conformant arrays, 91 
defining context handles, 130-131 
definition of, 4 
explicit binding and, 52 
generating UUID in, 6 
inventory application, 157 
language (IDL), 4 
specifying array size in, 91-93 
structure of, 29 
template for, 6 
interfaces 

applying binding methods, 47 

array attributes, 137 

attributes of procedure parameters, 139 

compiling, 40-42 

customizing with ACF, 42-44 

data type attributes, 139 

data types, 150 

defining binding handle, 54 

defining strings in, 34 

definition of, 2 

developing 

for automatic binding, 49 

for explicit binding, 53-54 

for implicit binding, 51 
handles, 19, 103 
header attributes, 29-30, 137 
identifying (naming), 30, 123 
information management routines, 43, 

145-146 

inventory application, 16 1 
pointer type attributes, 138 
procedure attributes, 140 
registering, 102-104 



simple, 4 

specification, client call, 100 

structure member attributes, 139 

union case attributes, 139 
international character types, 31 
Internet, protocols with, 56-57 
inv.h, 101 
inventory application, 30, 157-189 

ACF file, 176 

automatic binding, 172 

do_import_binding, 178 

do_interpret_binding, 179 

explicit binding, 183 

how to run, 158 

inventory implementation, 166 

Makefile, 160, 174 

MIDL file of, 161 

remote procedures, 163, 184 

server, 169 
invntry.c, 159 
ISO_LATIN_1, 31 
ISO_MULTI_LINGUAL, 31 
ISOJJCS, 31 

LAN for protocol sequences, 58 
last_is attribute, 90, 138 
length_is attribute, 90, 138 
levels of indirection, 84 
libraries for Microsoft RFC, 21 
linked lists, 95 
linking 

clients, 21-23, 74-77 

servers, 21-23, 117-119 
listening for RPCs, 110-112 
local attribute, 137 
local endpoint map, 15 
local RFC (ncalrpc transport), 58 
LOCAL symbol, 132 
locating servers, 13, 55-66 

with name service, 61-64 
Locator (see Microsoft Locator) 
long integers (see discriminated unions) 

maintaining context, 129-136 

in servers, 133-136 
Makefile, 150, 159-160, 192 

implicit client, 174 

Windows phnbk application, 202 
malloc, 113, 135 



228 



Microsoft RFC Programming Guide 



manager code (see remote procedures) 
manager, c, 150 

max_is attribute, 35, 91-93, 138 
memory management, 94-98 
allocating 

buffers, 97-98 

for conformant arrays, 93-94 
conformant arrays, 116-117 
context handle, 135 
contiguous server, 97 
in remote procedures, 112-115 
inventory application, 158 
node-by-node allocation, 96-97 
persistent storage, 98 
routines for, 145, 147 
Microsoft Locator, 14, 52, 126-127 
group operations, 108 
(see also name service) 
Microsoft RFC, 46 

libraries, 21 

Microsoft Windows NT, 97 
MIDL (Microsoft Interface Definition Lan 
guage) 

arithmetic application, 152 
brackets in, 30 
constants, 33 
data types, 30-38 

arrays, 34 

denning new, 33 

discriminated unions, 36-38 

enumerated types, 35 

international, 31 

pointers, 33 

strings, 34-35 

structures, 35-36 

void, 40 

default names, 103 
definition of, 4 

file of, phonebook application, 204 
generating template, 6 
handle_t data type, 51 
naming an interface, 30 
/oldnames option, 103 
parameter attributes, 38-40 
pointers (see pointers) 
procedure declarations, 27, 38-40 
rfile application, file of, 194 
type definitions, 30-38 
MIDL attributes, 28 



array, 137-138 

context_handle, 130, 139-140 

data type, 139 

endpoint, 106, 137 

first_is, 90, 138 

handle, 66, 139 

in, 38-40, 140 

interface header, 137 
interface keyword, 30 

last_is, 90, 138 

length_is, 90, 138 

local, 137 

max_is, 35, 91-93, 138 

out, 38-40, 140 

pointer_default, 30, 137 

pointer types, 138 

procedure parameter, 139-140 

ptr, 140 

ref, 33, 138 

size_is, 35, 91-93, 138 

string, 34, 138, 140 

structure member, 139 

transmit_as, 139 

union case, 139 

unique, 33, 138, 140 

uuid, 30, 137 

version, 30, 103, 137 

(see also ACF attributes) 
MIDL compiler, 7-21, 40-42, 141 

auxiliary files, 41 
client, 74 

/client none option, 42 

generating client/server files, 42 

/I option, 42 

inv.h, 101 

/out option, 42 

/server none option, 42 

specifying ACF, 43 

stub files, 41 

midl_user_allocate, 19, 95, 113-115, 135 
midl_user_free, 19, 95, 113-115 
multi-threaded RFC, 48 
multiple levels of indirection, 84 

name service, 46, 50-54, 56, 121-127 
advertising servers, 107 
definition of, 14 
entries, 122 
finding servers, 61-64 



Index 



229 



name service (cont d) 

importing from, 61-63 

independent (NSI) routines, 14 

managing, routines for, 144-147 

names in, 122 

selecting binding handles, 64 

server entries, 123-126 
named pipe (np transport), 58 
nbase.h, 102 

ncacn_dnet_nsp protocol, 56 
ncacn_ip_tcp protocol, 56 
ncacn_nb_nb protocol, 57 
ncacn_nb_tcp protocol, 57 
ncacn_np protocol, 57 
ncacn_spx protocol, 57 
ncadg_ip_udp protocol, 56 
ncalrpc protocol, 57 
ncalrpc transport (local RFC), 58 
NetBEUI transport, 57 
NetBEUI, NCA connection using, 56 
NetBIOS, NCA connection using, 56 
network 

address 

finding, 58-59 
host, 104 

RFC binding, 14 

services protocol (nsp), 57 
Network Computing Architecture (NCA), 

56-57 

Network Data Representation (NDR), 32 
nocode attribute, 44, 140 
node-by-node allocation, 96-97 
np transport (named pipe), 58 
NSI (name service independent) routines, 14 
nsp (network services protocol), 57 
null pointers, 80, 83 

object types, managing, 43, 147 
opaque structure, 100, 131 
open_inventory procedure, 109 
out attribute, 38-40, 140 
/out option, MIDL compiler, 42 
outdated endpoints (see endpoints, manag 
ing) 
output parameters, pointers as, 80-82 

parameter attributes, 38-40 
partially bound binding handle, 59 



pass by 

reference, 7 

value, 38 

persistent memory storage, 98 
phnbk.txt, 202 
phonebook (phnbk) application, 201-221 

ACF file, 205 

client file, 205 

header file, 213 

input, 221 

Makefile, 202 

MIDL file of, 204 

remote procedures, 214 

resource file, 213 

server, 217 

window module definitions, 213 
pipes, NCA connection using, 56 
pointer attributes, 80, 86 
pointer_default attribute, 30, 85, 137 
pointers, 33 

aliasing, 83, 87 

as input parameters, 82-84 

as output parameters, 80-82 

as procedure return values, 86-87 

default, 85, 89 

definition of, 79 

differentiating between, 87-90 

full. 33. 80, 86-90. 140 

interface handles, 103 

managing, 87-90 

in remote procedures, 113-115 

MIDL attributes, 138 

multiple, 89 

multiple levels of indirection, 84 

null, 80, 83 

reference, 80, 114, 138 

server context handles, 133 

to other pointers, 84-86 

to strings, 138 

unique, 80, 83, 114-115, 138 
privacy, data, 71 
procedures 

conformant arrays as parameters, 93 

context rundown (see context rundown 
procedures) 

declaration, 27, 38-40 
contents of, 4 

excluding unused, 44 

parameter attributes, 139-140 



230 



Microsoft RFC Programming Guide 



procedures (cont d) 

remote (see remote procedures) 

returning pointers, 86-87 

with context handles, 134-135 
protocol sequences, 56 

definition of, 14 

finding, 56-58 

inventory application, 158 

LAN for, 58 

RFC routines, 43, 145 

selecting at server initialization, 104-107 

timeouts for, 58 

WAN for, 58 
protocol, selecting a, 58 
ptr attribute, 140 

queue, client request, 100 

ref attribute, 33, 138 

reference pointers, 33, 80, 84, 87-90, 114 
registering server interfaces, 102-104 
remote file applications (see rfile applica 
tions) 
remote procedures 

calls, multi-threaded, 48 

handling errors, 72-74 

implementing, 11-12 

inventory application, 163 

managing memory in, 112-115 

multiple implementations, 104 

of arithmetic application, 153 

phnbk application, 214 

renaming in server code, 104 

returning context handle, 130 

rfile applications, 198 

testing and debugging, 76 

with binding handles, 133 

with context handles, 133-135 

writing, 112-117 
remote_close RFC, 133 
remote_open RFC, 132 
remote_send RFC, 132 
rfile applications, 129, 191-200 

client, 195 

context rundown procedures, 197 

do_string_binding, 196 

get_args, 195 

how to run, 191 

interface, 194 



Makefile, 192 

MIDL file, 194 

remote procedures, 198 

server, 199 
RFC (remote procedure calls) 

client binding information in, 113 

finding servers, 55 

group entries, naming, 107 

handling, 99-101 

(see also servers, initializing) 

listening for, 110-112 

multi-threaded, 48 

runtime library 

context runtime procedures, 136 
handling client request, 100-101 
registering server interfaces, 102 
role of, 17 

runtime routines, 143-147 

interpreting binding information, 60 
name service database, 61-64 
reporting errors, 102 
RpcBindingFree, 63, 66, 68-69 
RpcBindingFromStringBinding, 56, 

59-60, 66 

RpcBindinglnqAuthClient, 71 
RpcBindinglnqAuthlnfo, 71 
RpcBindingReset function, 51 
RpcBindingSetAuthlnfo, 71 
RpcBindingToStringBinding, 61 
RpcMgmtlnqComTimeout, 58 
RpcMgmtSetComTimeout, 58 
RpcNetworklnqProtseqs, 56, 66 
RpcNsBindinglmport, 56, 58 
RpcNsBindinglmportBegin, 63 
RpcNsBindinglmportDone, 63 
RpcNsBindinglmportNext, 63 
RpcNsBindingLookup, 56, 58, 64 
RpcNsBindingSelect, 64 
RpcProtseqVectorFree, 66 
RpcStringBindingCompose, 56, 59, 66 
RpcStringBindingParse, 61 
RpcStringFree, 6l, 66 
vector data structure, 102 

security, 71 

(see also authentication) 

selecting array portion, 90-91 

service, server s, 106 
rpc_binding_handle_t, 31, 53 
RpcBindingVectorFree, 19, 110, 112 



Index 



231 



rpc_binding_vector_t, 102 
RPC_C_NS_SYNTAX_DEFAULT, 63, 108 
RPC_C_PROTSEQ_MAX_CALLS_DEFAULT, 

105 

rpcdce.h, 102 

RpcEndExcept macro, 111-112 
RpcEpRegister, 19, 106, 110 
RpcEpUnregister, 110, 112 
RpcExcept macro, 111-112 
rpc.h, 102 

RpcMgmtStopServerListening, 110 
RpcNsBindingExport, 19, 108, 125 
RpcNsBindingUnexport, 126 
rpc_protseq_vector_t, 102 
RpcServerAllProtseqlf, 110 
RpcServerlnqBindings, 105, 112 
RpcServerListen, 19, 110-113 
RpcServerRegisterlf, 19, 104 
RpcServerUseAllProtseqs, 105 
RpcServerUseAUProtseqsIf, 106 
RpcServerUseProtseq, 105 
RpcServerUseProtseqEp, 106, 110 
RpcServerUseProtseqlf, 106, 110 
RpcTry Except macro , 111-112 
running applications (see applications) 

search_spec_bind, 69 
search_spec_unbind, 69 
security, 71 

selecting binding method (see binding meth 
ods) 
sequences, protocol (see protocol 

sequences) 

server entries, 123-126 
creating, 125-126 
naming, 124 

server files, generatiJng, 42 
/server none, MIDL compiler, 42 
server.c, 150, 159 
servers 

advertising, 107-109 
binding information 

automatic, 50 

client, 113 

creating, 104-107 

explicit, 55 

implicit, 52 

interpreting, 61 

with binding handles, 133 



building, 149 

client communication break, 134, 136 
compiling and linking, 21-23, 117-119 
context handles, 133-135 
contiguous memory, 97 
copying text from clients, 129 
data structures, 102 
developing, 11 

errors in, 72-74 
endpoint map, 106 
finding/locating, 13 

from strings, 64-66 

host, 58-59 

particular, 45-66 

with name service, 61-64 
handling 

client request, 100-101 

exceptions, 72 
header files, 102 
initializing, 15, 18-19, 99-112, 153 

data structures, 101-102 

header files, 101-102 

inventory application, 169 

managing endpoints, 109-110, 112 

rfile applications, 199 

selecting protocol sequences, 104-107 
listening for RPCs, 110-112 
managing 

context in, 133-136 

routines for, 147 
naming conventions, 107 
naming multiple, 122 
phnbk application, 217 
producing, 117 
registering interfaces, 102-104 
remote procedure implementations, 99 
stub auxiliary file, 117 
using discriminated unions, 38 
writing, 99-119 
(see also clients) 
size_is attribute, 35, 91-93, 138 
spx transport, 58 
SPX, NCA connection using, 57 
status.h, 74, 150 
strbind.c, 192 

string attribute, 34, 138, 140 
strings, 34-35 

pointers to, 138 
struct keyword, 35 



232 



Microsoft RFC Programming Guide 



structure members 

attributes, 139 

pointers as, 89 
structures, 35-36 
stubs 

code for memory management, 96 

data transmission, 32 

definition of, 1 

generating, 7 

with MIDL compiler, 41 

support routines, 113 
sum_arrays, 11, 149 
switch keyword, 37 

tcp, 57 

TCP/IP, protocols with, 56 

testing remote procedures, 76 

text variables (see strings) 

threads 

for processing client requests, 100 

for RPCs, 112-113 
timeouts, protocol sequences, 58 
transmission control protocol, 57 
transmit_as attribute, 139 
transport protocol, 57 

in RPC binding, 14 
type definitions, MIDL, 30-38 
typedef keyword, 33 

unbind procedure, 68-69 
union case attributes, 139 
unique attribute. 33, 138, 140 
unique pointers, 33, 80, 84, 87-90 

allocating memory, 114-115 
unsigned32 variable 

reporting errors, RPC, 102 
UUID (universal unique identifier) 

definition of, 5 

management routines for, 43, 144, 146 
uuid attribute, 30, 137 
uuidgen, use of, 5 

varying arrays, 34, 90-91 

declaring, 90 

MIDL attributes, 138 

selection portion of, 90-91 
vectors, 102 

version attribute, 30, 103, 137 
version number, interface, 30 



void data type, 40 

WAN, protocol sequences, 58 

wchar_t data type, 31 

well-known endpoints, 59-60, 110, 137 

creating binding information with, 106 

exporting, 108 

in binding information, 123 

server binding information with, 106-107 
whatare_subparts, 11 6, 158 
Windows NT, Microsoft, 97 

security, 71 

Windows phonebook application, 201-221 
wphnbk.def, 202 
wphnbk.h, 202 
wphnbk.rc, 202 
writing 

clients, 45-77 

procedures, 134-135 
remote, 112-117 

servers, 99-119 



About the Author 



John Shirley is a consultant in the development of software and documentation, 
particularly in the field of distributed computing. He earned a B.A. from Alfred 
University with a dual major in mathematics and geology, an M.S. in geology from 
Miami University with a specialty in structural geology, and an M.S. in computer 
science from Pace University. John lives in Newtown, Connecticut. 

Prior to consulting, John s career included six years in the oil industry as a geophys- 
icist and international explorationist. His work included the analysis of seismic data 
from New Zealand, Australia, Turkey, Norway, the Dominican Republic, Jamaica, 
and the United States. He also worked as a software engineer developing programs 
for scientific instrument manufacturers. 

Ward Rosenberry is a technical writing consultant and author concentrating on 
distributed computing and computer networking technologies. Ward has distin 
guished himself writing about the Open Software Foundation s Distributed 
Computing Environment since 1989, when he helped write Digital Equipment 
Corporation s original DCE design documents. He has since co-authored two other 
O Reilly books about distributed computing: Understanding DCE and Distributing 
Applications Across DCE and Windows NT. He continues his close DCE involvement 
designing and developing DCE information both at Digital and at OSF and now 
operates a consulting firm, Rosenberry Associates, in Chelmsford, Massachusetts. 

Ward graduated from the University of Lowell in 1979 with a B.A. in English. Ward, 
his wife Patricia Pestana, and their two children, William and John, live in North 
Chelmsford, Massachusetts. 

Colophon 

The animal on the cover of Microsoft RFC Programming Guide is a starfish, a marine 
invertebrate animal of the phylum Echinodermata, class Asteroidea. The approxi 
mately 1500 known living species of starfish are found throughout the world, at all 
ocean depths, and range in size from 1 cm to 68 cm wide. Most starfish have five 
arms, but can have as few as four or as many as 50. 

Starfish are equipped with five double rows of outgrowths called tube feet. These 
tube feet, which are usually tipped with "suction cups," function in the respiratory 
process, enable the starfish to move, and are used to catch prey. The tube feet are 
connected via a water- vascular system unique to echinoderms. A ring canal in the 
disc-shaped body trunk connects to a radial canal in each arm, through which 
gaseous exchange takes place. 



When a starfish needs to move, pressure in the water-vascular system causes the 
tube feet to become erect, lifting up the body. The tube feet then take small steps, 
moving the starfish slowly forward. One arm takes the lead in movement; when the 
direction changes, the lead shifts to another arm. Most of the time, however, starfish 
are sedentary creatures who prefer to stay anchored in one place. They will move 
to search for food, or if there is a change in external conditions. 

The majority of starfish are predators, feeding on bivalves, crustaceans, and other 
echinoderms. By anchoring its arms on the sea floor, the starfish is able to use the 
suction pull of the tube feet to pry open the shells of bivalves. The starfish can then 
extrude its stomach through its mouth and into the tiny crevice of the bivalve shell, 
and begin the digestive process outside of its body. 

Many species of starfish can reject an arm if it is injured in an attack. The body will 
generate a new arm, but this is a slow process that can take more than a year to 
complete. In a few speciess, the arm that has broken off will generate a body trunk 
and four new arms. At least one species of starfish eschews sexual reproduction in 
favor of this asexual mode, and has developed the ability to break off an arm at will. 

Starfish usually reproduce by releasing eggs and sperm into the waves. The fertilized 
eggs form free-swimming larvae, although the female adult will provide some form 
of brood care in colder regions. 

Edie Freedman designed the cover of this book, using a 19th-century engraving from 
the Dover Pictorial Archive. The cover layout was produced with Quark XPress 3.3 
using the ITC Garamond font. 

The inside layout was designed by Edie Freedman and Jennifer Niederst and imple 
mented in gtroff by Lenny Muellner. The text and heading fonts are ITC Garamond 
Light and Garamond Book. The illustrations that appear in the book were created in 
Aldus Freehand 4.0 by Chris Reilley. This colophon was written by Clairemarie Fisher 
O Leary, with assistance from Kiersten Nauman. 




FORM 

Books from O Reilly & Associates, Inc. 



Fortran/Scientific Computing 



Fall/Winter 1994-95 




Migrating to Fortran 90 

By James F. Kerrigan 

1st Edition November 1993 

389 pages, ISBN 1-56592-049-X 

Many Fortran programmers do not know 
where to start with Fortran 90. What is new 
about the language? How can it help them? 
How does a programmer with old habits 
learn new strategies? 

This book is a practical guide to Fortran 90 
for the current Fortran programmer. It 
provides a complete overview of the new 
features that Fortran 90 has brought to the 
Fortran standard, with examples and suggestions for use. 
The book discusses older ways of solving problems both 
in FORTRAN 77 and in common tricks or extensions and 
contrasts them with the new ways provided by Fortran 90. 

The book has a practical focus, with the goal of getting the 
current Fortran programmer up to speed quickly. Two dozen 
examples of full programs are interspersed within the text, 
which includes over 4,000 lines of working code. 

Topics include array sections, modules, file handling, 
allocatable arrays and pointers, and numeric precision. 
Two dozen examples of full programs are interspersed 
within the text, which includes over 4,000 lines of 
working code. 

"This is a book that all Fortran programmers eager to 
take advantage of the excellent feature of Fortran 90 will 
want to have on their desk." FORTRAN Journal 



High Performance Computing 

By Ketin Dou d 

1st Edition June 1993 

398 pages, ISBN 1-56592-032-5 




HigT 
Performance 
Computing 



High Performance Computing makes 
sense of the newest generation of work 
stations for application programmers 
and purchasing managers. It covers 
everything, from the basics of modern 
workstation architecture, to structuring 
benchmarks, to squeezing more perfor 
mance out of critical applications. It also 
explains what a good compiler can do 
and what you have to do yourself. The book closes with a look 
at the high-performance future: parallel computers and the 
more "garden variety" shared memory processors that are 
appearing on people s desktops. 

UNIX for FORTRAN Programmers 

By Mike Loukides 

1st Edition August 1990 

264 pages, ISBN 0-937 175-5 1-X 

This handbook lowers the UNIX entry 
barrier by providing the serious scientific 
programmer with an introduction to 
the UNIX operating system and its tools. 
It familiarizes readers with the most 
important tools so they can be productive 
as quickly as possible. Assumes some 
knowledge of FORTRAN, none of UNIX or C. 




FOR INFORMATION: 800-998-9938 707-829-0515; NUTS@ORA.COM 



C Programming Libraries 



POSIX.4 

By Bill Gallmeister 

1st Edition Winter 1994-95 (est.) 

400 pages (est.), ISBN 1-56592-074-0 



POSIX.4 



A general introduction to real-time 
programming and real-time issues, 
this book covers the POSIX.4 standard 
and how to use it to solve "real-world" 
problems. If you re at all interested in 
real-time applications which include 
just about everything from telemetry 
to transation processing this book is 
for you. An essential reference. 



POSIX Programmer s Guide 

By Donald Lewine 

1st Edition April 1991 

640 pages, ISBN 0-937175-73-0 



POSIX 

PROGRAMMER S 
GUIDE 



Most UNIX systems today are POSIX 
compliant because the Federal govern 
ment requires it for its purchases. 
Given the manufacturer s documenta 
tion, however, it can be difficult to 
distinguish system-specific features 
from those features defined by POSIX. 
The POSIX Programmer s Guide, 
intended as an explanation of the 
POSIX standard and as a reference for 

the POSIX. 1 programming library, helps you write more 

portable programs. 

"If you are an intermediate to advanced C programmer and 
are interested in having your programs compile first time on 
anything from a Sun to a VMS system to an MSDOS system, 
then this book must be thoroughly recommended." 
Sun UK User 

Understanding and Using COFF 

By Gintaros R. Gircys 

1st Edition November 1988 

196 pages, ISBN 0-9371 75-31-5 

COFF Common Object File Format is 
the formal definition for the structure of 
machine code files in the UNIX System V 
environment. All machine code files are 
COFF files. This handbook explains COFF 
data structure and its manipulation. 




COFF 




Using C on the UNIX System 

By Dave Curry 

1st Edition January 1989 

250 pages, ISBN 0-937 175-23-4 

This is the book for intermediate to 
experienced C programmers who want 
to become UNIX system programmers. 
It explains system calls and special library 
routines available on the UNIX system. It 
is impossible to write UNIX utilities of any 
sophistication without understanding the 
material in this book. 

"A gem of a book.... The author s aim is to provide a guide to 
system programming, and he succeeds admirably. His balance 
is steady between System V and BSD-based systems, so readers 
come away knowing both." SUN Expert 

Practical C Programming 

By Steve Oualline 

2nd Edition January 1993 

396 pages, ISBN 1-56592-035-X 

C programming is more than just getting 
the syntax right. Style and debugging 
also play a tremendous part in creating 
programs that run well. Practical C 
Programming teaches you not only the 
mechanics of programming, but also 
how to create programs that are easy 
to read, maintain, and debug. There 
are lots of introductory C books, but 

this is the Nutshell Handbook! In this edition, programs 

conform to ANSI C. 

"This book is exactly what it states a practical book in 
C programming. It is also an excellent addition to any C 
programmer s library." Betty Zinkarun, Books & Bytes 

Programming with curses 

By John Strung 

1st Edition 1986 

76 pages, ISBN 0-937175-02-1 

Curses is a UNIX library of functions for 
controlling a terminal s display screen 
from a C program. This handbook 
helps you make use of the curses 
library. Describes the original Berkeley 
version of curses. 





TO ORDER: 800-889-8969 (CREDIT CARD ORDERS ONLY); ORDER@ORA.COM 



C Programming Tools 




Software Portability with imake 

By Paul DuBois 

1st Edition July 1993 

390 pages, ISBN 1-56592-055-4 

imake is a utility that works with make 
to enable code to be compiled and 
installed on different UNIX machines. 
imake makes possible the wide portability 
of the X Window System code and is widely 
considered an X tool, but it s also useful 
for any software project that needs to be 
ported to many UNIX systems. 

This Nutshell Handbook the only book available on 
imake is ideal for X and UNIX programmers who want 
their software to be portable. The book is divided into two 
sections. The first section is a general explanation of imake, 
X configuration files, and how to write and debug an Imakefile. 
The second section describes how to write configuration files 
and presents a configuration file architecture that allows 
development of coexisting sets of configuration files. Several 
sample sets of configuration files are described and are 
available free over the Net. 

Managing Projects with make 

By Andrew Oram & Steve Talbott 
2nd Edition October 1991 
152 pages, ISBN 0-937175-90-0 

make is one of UNIX s greatest contribu 
tions to software development, and this 
book is the clearest description of make 
ever written. It describes all the basic 
features of make and provides guidelines 
on meeting the needs of large, modern 
projects. Also contains a description 
of free products, that contain major 
enhancements to make, 

"I use make very frequently in my day to day work and 
thought I knew everything that I needed to know about it. 
After reading this book I realized that I was wrong! 
Rob Henley, Siemens-Nixdorf 

"If you can t pick up your system s yp Makefile, read every 
line, and make sense of it, you need this book." 
Rootjournal 





Checking C Programs with lint 

By Ian F. Darwin 

1st Edition October 1988 

84 pages. ISBN 0-937175-30-7 

The lint program checker has proven 
time and again to be one of the best tools 
for finding portability problems and certain 
types of coding errors in C programs, lint 
verifies a program or program segments 
against standard libraries, checks the 
code for common portability errors, and 
tests the programming against some tried 
and true guidelines. Linting your code is 
a necessary (though not sufficient) step in writing clean, 
portable, effective programs. This book introduces you to lint, 
guides you through running it on your programs, and helps 
you interpret lint s output. 

"I can say without reservation that this book is a must for 
the system programmer or anyone else programming in C." 
Rootjournal 

lex & yacc 

By John Letine, Tony Mason & Doug Brown 
2nd Edition October 1992 
366 pages, ISBN 1-56592-000-7 

Shows programmers how to use two 
UNIX utilities, lex and yacc, in program 
development. The second edition contains 
completely revised tutorial sections for 
novice users and reference sections for 
advanced users. This edition is twice the 
size of the first, has an expanded index, 
and now covers Bison and Flex. 



Power Programming with RPC 

By John Bloomer 

1st Edition February 1992 

522 pages, ISBN 0-937175-77-3 

RPC, or remote procedure calling, is the 
ability to distribute the execution of func 
tions on remote computers. Written from 
a programmer s perspective, this book 
shows what you can do with RPCs, like 
Sun RPC, the de facto standard on UNIX 
systems. It covers related programming 
topics for Sun and other UNIX systems 
and teaches through examples. 





FOR INFORMATION: 800-998-9938, 70 7-829-05 15; HUTS@ORA.COM 



Multi-Platform Programming 




Guide to Writing DCE Applications 

By John Shirley, WeiHu & David Magid 

2nd Edition May 1994 

462 pages, ISBN 1-56592-045-7 

A hands-on programming guide to OSF s 
Distributed Computing Environment (DCE) 
for first-time DCE application programmers. 
This book is designed to help new DCE 
users make the transition from conventional, 
nondistributed applications programming 
to distributed DCE programming. In addi 
tion to basic RFC (remote procedure 
calls), this edition covers object UUIDs 

and basic security (authentication and authorization). 

Also includes practical programming examples. 

"This book will be useful as a ready reference by the side of 
the novice DCE programmer." ; login 

Distributing Applications Across DCE 
and Windows NT 

By Ward Rosenbeny &Jim league 
1st Edition November 1993 
302 pages. ISBN 1-56592-047-3 

This book links together two exciting 
technologies in distributed computing 
by showing how to develop an application 
that simultaneously runs on DCE and 
Microsoft systems through remote proce 
dure calls (RFC). Covers the writing of 
portable applications and the complete 
differences between RFC support in the 
two environments. 



Understanding DCE 

By Ward Rosenbeny, David Kmney & Gerry Fisher 

1st Edition October 1992 

266 pages, ISBN 1-56592-005-8 

A technical and conceptual overview of 
OSF s Distributed Computing Environment 
(DCE) for programmers, technical 
managers, and marketing and sales 
people. Unlike many O Reilly & Associates 
books, Understanding DCE has no hands- 
on programming elements. Instead, the 
book focuses on how DCE can be used 
to accomplish typical programming tasks 

and provides explanations to help the reader understand all 

the parts of DCE. 






Encyclopedia of Graphics File Formats 

By James D. Murray & William vanRyper 

1st Edition July 1994 

928 pages (CD-ROM included), ISBN 1-56592-058-9 

The computer graphics world is a veri 
table alphabet soup of acronyms; BMP 
DXF, EPS, GIF, MPEG, PCX, PIC, RTF, 
TGA, RIFF, and TIFF are only a few of 
the many different formats in which 
graphics images can be stored. 
The Encyclopedia of Graphics 
File Formats is the definitive 
work on file formats the 
book that will become a classic 
for graphics programmers and 

everyone else who deals with the low-level technical details 
of graphics files. It includes technical information on nearly 
100 file formats, as well as chapters on graphics and file 
format basics, bitmap and vector files, metafiles, scene 
description, animation and multimedia formats, and file 
compression methods. 

Best of all, this book comes with a CD-ROM that collects many 
hard-to-find resources. We ve assembled original vendor file 
format specification documents, along with test images and 
code examples, and a variety of software packages for MS- 
DOS, Windows, OS/2, UND(, and the Macintosh that will let 
you convert, view, and manipulate graphics files and images. 

Multi-Platform Code Management 

By Kevin Jameson 

1st Edition August 1994 

354 pages (two diskettes included), ISBN 1-56592-059-7 

For any programmer or team struggling 
with builds and maintenance, this 
book and its accompanying software 
(available for fifteen platforms, 
including MS-DOS and various UNIX 
systems) can save dozens of errors 
and hours of effort. A "one-stop-shop 
ping" solution for code management 
problems, it shows you how to structure 
a large project and keep your files and builds under control 
over many releases and platforms. The building blocks are 
simple: common-sense strategies, public-domain tools that 
you can obtain on a variety of systems, and special utilities 
developed by the author. The book also includes two 
diskettes that provide a complete system for managing 
source files and builds. 




TO ORDER: 800-889-8969 (CREDIT CARD ORDERS ONLY); ORDER@ORA.COM 



Database 




Understanding Japanese Information Processing 

By Ken Lutuie 

1st Edition September 1993 

470 pages. ISBN 1-56592-043-0 

Understanding Japanese Information 
Processing provides detailed information 
on all aspects of handling Japanese text 
on computer systems. It brings all of the 
relevant information together in a single 
book and covers everything from the 
origins of modern-day Japanese to the 
latest information on specific emerging 
computer encoding standards. Appendices 
provide additional reference material, such as a code conver 
sion table, character set tables, mapping tables, an extensive 
list of software sources, a glossary, and more. 

"A programmer interested in writing a computer program 
which will handle the Japanese language will find the book 
indispensable." Multilingual Computing 

"Ken Lunde s book is an essential reference for everyone 
developing or adapting software for handling Japanese text. 
It is a goldmine of useful and relevant information on fonts, 
encoding systems and standards." 
Professor Jim Breen, Monash University, Australia 



Business 
Building a Successful Software Business 

By Dare Rodin 

1st Edition April 1994 

394 pages, ISBN 1-56592-064-3 

This handbook is for the new software 
entrepreneur and the old hand alike. 
If you re thinking of starting a company 
around a program you ve written and 
there s no better time than the present 
this book will guide you toward success. 
If you re an old hand in the software 
industry, it will help you sharpen your 
skills or will provide a refresher course. It covers the basics 
of product planning, marketing, customer support, finance, 
and operations. 

"A marvelous guide through the complexities of marketing 
high-tech products. Its range of topics, and Radin s insights, 
make the book valuable to the novice marketeer as well as 
the seasoned veteran. It is the Swiss Army Knife of high-tech 
marketing." Jerry Keane, Universal Analytics Inc. 





ORACLE Performance Tuning 

By Peter Corrigan & Mark Gurry 
1st Edition September 1993 
642 pages, ISBN 1-56592-048-1 

The ORACLE relational database 
management system is the most 
popular database system in use today. 
Organizations, ranging from government 
agencies to small businesses, from large 
financial institutions to universities, 
use ORACLE on computers as diverse 
as mainframes, minicomputers, work 
stations, PCs, and Macintoshes. 

ORACLE offers tremendous power and flexibility, but at 
some cost. Demands for fast response, particularly in online 
transaction processing systems, make performance a major 
issue. With more organizations downsizing and adopting 
client-server and distributed database approaches, perfor 
mance tuning has become all the more vital. 

Whether you re a manager, a designer, a programmer, 
or an administrator, there s a lot you can do on your own 
to dramatically increase the performance of your existing 
ORACLE system. Whether you are running RDBMS Version 6 
or Version 7, you may find that this book can save you the 
cost of a new machine; at the very least, it will save you a 
lot of headaches. 

"This book is one of the best books on ORACLE that I have 
ever read.... [It] discloses many Oracle Tips that DBA s and 
Developers have locked in their brains and in their planners.... 
I recommend this book for any person who works with 
ORACLE, from managers to developers. In fact, I have to keep 
[it] under lock and key, because of the popularity of it." 
Mike Gangler 



FOR INFORMATION: 800-998-9938 707-829-0515; NUTS@ORA.COM 



O Reilly & Associates- 

GLOBAL NETWORK NAVIGATOR 

The Global Network Navigator (GNN) is a unique kind of information service that makes the Internet easy and enjoyable 
to use. We organize access to the vast information resources of the Internet so that you can find what you want. We also help 
you understand the Internet and the many ways you can explore it. 



Global Network Navigator 




Charting the Interj%M. 



In GNN you ll find: 



Navigating the Net with GNN 

The Whole Internet Catalog contains a 
descriptive listing of the most useful Net 
resources and services with live links to those resources. 



The GNN Business Pages are where 
you ll learn about companies who have 



established a presence on the Internet and use its worldwide 
reach to help educate consumers. 



The Internet Help Desk helps folks who 
are new to the Net orient themselves and 
gets them started on the road to Internet exploration. 

News 

NetNews is a weekly publication that 
reports on the news of the Internet, with 
weekly feature articles that focus on Internet trends and 
special events. The Sports, Weather, and Comix Pages round 
out the news. 

Special Interest Publications 

Whether you re planning a trip or are just 
interested in reading about the journeys 
of others, you ll find that the Travelers Center contains a 
rich collection of feature articles and ongoing columns about 
travel. In the Travelers Center, you can link to many helpful 
and informative travel-related Internet resources. 

The Personal Finance Center is the place 
to go for information about money manage 
ment and investment on the Internet. Whether you re an old 
pro at playing the market or are thinking about investing for the 
first time, you ll read articles and discover Internet resources 
that will help you to think of the Internet as a personal finance 
information tool. 



All in all, GNN helps you get more value for the 
time you spend on the Internet. 




S The Best of the Web 



GNN received "Honorable Mention" for 

Best Overall Site," "Best Entertainment Service," 

and "Most Important Service Concept." 

The GNN NetNews received "Honorable Mention" 
for "Best Document Design." 



Subscribe Today 

GNN is available over the Internet as a subscription service. 
To get complete information about subscribing to GNN, 
send email to info@gnn.com. If you have access to a World 
Wide Web browser such as Mosaic or Lynx, you can use the 
following URL to register online: http : / /gun . com/ 

If you use a browser that does not support online forms, 
you can retrieve an email version of the registration form 
automatically by sending email to form@gnn.com. 
Fill this form out and send it back to us by email, and 
we will confirm your registration. 



TO ORDER: 800-889-8969 (CREDIT CARD ORDERS ONLY); ORDER@ORA.COM 



O Reilly on the Net- 



ONLINE PROGRAM GUIDE 



O Reilly & Associates offers extensive information through our online resources. If you ve got Internet access, we invite you to 
come and explore our little neck-of-the-woods. 



Online Resource Center 

Most comprehensive among our online offerings is the O Reilly 
Resource Center. Here, you ll find detailed information and 
descriptions on all O Reilly products: titles, prices, tables of 
contents, indexes, author bios, software contents, reviews... you 
can even view images of the products themselves. We also supply 
helpful ordering information: how to contact us, how to order 
online, distributors and bookstores world wide, discounts, 
upgrades, etc. In addition, we provide informative literature in 
the field: articles, interviews, and bibliographies that help you 
stay informed and abreast. 



^-M The Best of the Web 

The O Reilly Resource Center was voted "Best Commercial 
Site" by users participating in "Best of the Web 94." 



Ora-news 

An easy way to stay informed of the latest projects and products 
from O Reilly & Associates is to subscribe to "ora-news," our 
electronic news service. Subscribers receive email as soon as 
the information breaks. 



To subscribe to "ora-news": 

Send email to: 
listproc@online.ora.com 

and put the following information on the first line of your message 

(not in "Subject"): 

subscribe ora-news "your name" of "your company" 

For example: 

subscribe ora-news Jim Dandy of Mighty Fine Enterprises 



To access ORA s Online Resource Center: 

Point your Web browser (e.g., mosaic or lynx) to: 
http : / /gnn . com/ or a/ 



Email 

Many customer services are provided via email. Here s a few of 
the most popular and useful. 



For the plaintext version, telnet or gopher to: 
gopher . ora . com 
(telnet login: gopher) 



FTP 

The example files and programs in many of our books are 
available electronically via FTP. 

To obtain example flies and programs 
from O Reilly texts: 

ftp to: 
ftp.ora.com 

or 
ftp.uu.net 

cd published/oreilly 



nuts@ora.com 

For general questions and information. 
bookquestions@ora.com 

For technical questions, or corrections, concerning 

book contents. 
order@ora.com 

To order books online and for ordering questions. 
catalog@ora.com 

To receive a free copy of our magazine/catalog, "ora.com 

(please include a postal address). 



Snail mail and phones 

O Reilly & Associates, Inc. 

103A Morris Street, Sebastopol, CA 95472 

Inquiries: 707-829-0515, 800-998-9938 

Credit card orders: 800-889-8969 (Weekdays 6a.m.- 6p.m. PST) 
FAX: 707-829-0104 



FOR INFORMATION: 800-998-9938 707-829-0515: NUTS@ORA.COM 



O Reilly & Associates- 

LISTING OF TITLES 



INTERNET 

!%@:: A Directory of Electronic Mail 

Addressing & Networks 

Connecting to the Internet: An O Reilly Buyer s Guide 
Internet In A Box 

The Mosaic Handbook for Microsoft Windows 
The Mosaic Handbook for the Macintosh 
The Mosaic Handbook for the X Window System 
Smileys 
The Whole Internet User s Guide & Catalog 

SYSTEM ADMINISTRATION 

Computer Security Basics 

DNS and BIND 

Essential System Administration 

Linux Network Administrator s Guide (Winter 94/95 est) 

Managing Internet Information Services 

Managing NFS and NIS 

Managing UUCP and Usenet 

sendmail 

Practical UNIX Security 

PGP: Pretty Good Privacy (Winter 94/95 est.) 

System Performance Tuning 

TCP/IP Network Administration 

termcap & terminfo 

X Window System Administrator s Guide: Volume 8 

The X Companion CD for R6 (Winter 94/95 est.) 

USING UNIX AND X 

BASICS 

Learning GNU Emacs 

Learning the Korn Shell 

Learning the UNIX Operating System 

Learning the vi Editor 

MH & xmh: Email for Users & Programmers 

SCO UNIX in a Nutshell 

The USENET Handbook (Winter 94/95 est.) 

Using UUCP and Usenet 

UNIX in a Nutshell: System V Edition 

The X Window System in a Nutshell 

X Window System User s Guide: Volume 3 

X Window System User s Guide, Motif Ed.: Vol. 3M 

X User Tools (with CD-ROM) 

ADVANCED 

Exploring Expect (Winter 94/95 est.) 

The Frame Handbook 

Learning Perl 

Making TeX Work 

Programming perl 

sed&awk 

UNIX Power Tools (with CD-ROM) 



PROGRAMMING UNIX, 
C, AND MULTI-PLATFORM 

FORTRAN/SCIENTIFIC COMPUTING 

High Performance Computing 

Migrating to Fortran 90 

UNIX for FORTRAN Programmers 

C PROGRAMMING LIBRARIES 

Practical C Programming 

POSIX Programmer s Guide 

POSIX.4: Programming for the Real World 

(Winter 94/95 est) 
Programming with curses 
Understanding and Using COFF 
Using C on the UNIX System 

C PROGRAMMING TOOLS 

Checking C Programs with lint 
lex & yacc 

Managing Projects with make 
Power Programming with RPC 
Software Portability with imake 

MULTI-PLATFORM PROGRAMMING 

Encyclopedia of Graphics File Formats 
Distributing Applications Across DCE and 

Windows NT 

Guide to Writing DCE Applications 
Multi-Platform Code Management 
ORACLE Performance Tuning 
Understanding DCE 
Understandingjapanese Information Processing 

BERKELEY 4.4 SOFTWARE 
DISTRIBUTION 

4.4BSD System Manager s Manual 

4.4BSD User s Reference Manual 

4.4BSD User s Supplementary Documents 

4,-iBSD Programmer s Reference Manual 

4.4BSD Programmer s Supplementary Documents 

4.4BSD-Lite CD Companion 

4.4BSD-Lite CD Companion: International Version 



X PROGRAMMING 

Motif Programming Manual: Volume 6A 

Motif Reference Manual: Volume 6B 

Motif Tools 

PEXlib Programming Manual 

PEXlib Reference Manual 

PHIGS Programming Manual (soft or hard cover) 

PHIGS Reference Manual 

Programmer s Supplement for Release 6 (Winter 94/95 est) 

Xlib Programming Manual: Volume 1 

Xlib Reference Manual: Volume 2 

X Protocol Reference Manual, R5: Volume 

X Protocol Reference Manual, R6: Volume 

(Winter 94/95 est.) 

X Toolkit Intrinsics Programming Manual: Vol. 4 
X Toolkit Intrinsics Programming Manual, 

Motif Edition: Volume 4M 
X Toolkit Intrinsics Reference Manual: Volume 5 
XView Programming Manual: Volume 7A 
XView Reference Manual: Volume 7B 

THE X RESOURCE 

A QUARTERLY WORKING JOURNAL FOR 
X PROGRAMMERS 

The X Resource: Issues through 13 
(Issue 13 available 1/95) 

BUSINESS/CAREER 

Building a Successful Software Business 
Love Your Job! 

TRAVEL 

Travelers Tales Thailand 

Travelers Tales Mexico 

Travelers Tales India (Winter 94/95 est) 

AlTDIOTAPES 

INTERNET TALK RADIO S 

"GEEK OF THE WEEK" INTERVIEWS 

The Future of the Internet Protocol, 4 hours 
Global Network Operations, 2 hours 
Mobile IP Networking, 1 hour 
Networked Information and 
Online Libraries, 1 hour 
Security and Networks, 1 hour 
European Networking, 1 hour 

NOTABLE SPEECHES OF THE INFORMATION AGE 

John Perry Barlow, 1.5 hours 



TO ORDER: 800-889-8969 (CREDIT CARD ORDERS ONLY): ORDER@ORA.COM 



O Reilly &Associates- 

INTERNATIONAL DISTRIBUTORS 

Customers outside North America can now order O Reilly & Associates books through the following distributors. They offer our 
international customers faster order processing, more bookstores, increased representation at tradeshows worldwide, and the high- 
quality, responsive service our customers have come to expect. 



EUROPE, MIDDLE EAST, AND AFRICA 

(except Germany, Switzerland, and Austria) 

INQUIRIES 

International Thomson Publishing Europe 

Berkshire House 

168-173 High Holborn 

London WC1V7M 

United Kingdom 

Telephone: 44-71-497-1422 

Fax: 44-71-497-1426 

Email: ora.orders@itpuk.co.uk 

ORDERS 

International Thomson Publishing Services, Ltd. 

Cheriton House, North Way 

Andover, Hampshire SP10 5BE 

United Kingdom 

Telephone: 44-264-342-832 (UK orders) 

Telephone: 44-264-342-806 (outside UK) 

Fax: 44-264-364418 (UK orders) 

Fax: 44-264-342761 (outside UK) 



GERMANY, SWITZERLAND, AND AUSTRIA 

International Thomson Publishing GmbH 

O Reilly-International Thomson Verlag 

Attn: Mr. G. Miske 

Konigswinterer Strasse 418 

53227 Bonn 

Germany 

Telephone: 49-228-970240 

Fax: 49-228-441342 

Email: anfragen@orade.ora.com 



ASIA 

(except Japan) 

INQUIRIES 

International Thomson Publishing Asia 
221 Henderson Road 
#05 10 Henderson Building 
Singapore 03 15 
Telephone: 65-272-64% 
Fax: 65-272-6498 

ORDERS 

Telephone: 65-268-7867 
Fax: 65-268-6727 



AUSTRALIA 

WoodsLane Pty. Ltd. 

Unit 8, 101 Darley Street (P.O. Box 935) 

MonaValeNSW2103 

Australia 

Telephone: 61-2-979-5944 

Fax: 61-2-997-3348 

Email: woods@tmx.mhs.oz.au 



NEW ZEALAND 

WoodsLane New Zealand Ltd. 
21 Cooks Street (P.O. Box 575) 
Wanganui, New Zealand 
Telephone: 64-6-347-6543 
Fax: 64-6-345-4840 
Email: woods@tmx.mhs.oz.au 



THE AMERICAS, JAPAN, AND OCEANIA 

O Reilly & Associates, Inc. 

103A Morris Street 

Sebastopol, CA 95472 U.S.A. 

Telephone: 707-829-0515 

Telephone: 800-998-9938 (U.S. & Canada) 

Fax: 707-829-0104 

Email: order@ora.com 



FOR INFORMATION: 800-998-9938, 707-829-0515; NUTS@ORA.COM 



Here s a page we encourage readers to tear out... 




Please send me the following: 

Q ora.com 

O Reilly s magazine/catalog, 
containing behind-the-scenes 
articles and interviews on the 
technology we write about, and 
a complete listing of O Reilly 
books and products. 

G Global Network Navigator 
Information and subscription. 



Which book did this card come from? 



Please print legibly 



Where did you buy this book? 

Q Bookstore Q Direct from O Reilly 

Q Bundled with hardware/software LI Class/seminar 

Your job description: G SysAdmin G Programmer 

Q Other 

What computer system do you use? Q UNIX 

QMAC QDOS(PC) LI Other 



Name 



Company/Organization Name 



Address 



Citv 



State 



Zip/Postal Code 



Country 



Telephone 



Internet or other email address (specify 7 network) 



vineteenth century wood engraving 
>f the horned owl from the O Reilly 
i Associates Nutshell Handbook 
.earning the i.MX Operating System 





NO POSTAGE 
NECESSARY IF 
MAILED IN THE 
UNITED STATES 



BUSINESS REPLY MAIL 

FIRST CLASS MAIL PERMIT NO. 80 SEBASTOPOL, CA 



Postage will be paid by addressee 

O Reilly & Associates, Inc. 

103A Morris Street 
Sebastopol, CA 95472-9902 



O Reilly & Associates, Inc. 



Microsoft RFC Programming Guide 

Remote Procedure Call (RFC) is the glue that holds together MS-DOS, Windows 3.x, and 
Windows NT. It is a client-server technology a way of making programs on two different 
systems work together like one. The advantage of RFC over other distributing 
programming techniques is that you can link two systems together using simple C calls, 
as in a single-system program. 

The most common use for client-server technology is to combine the graphical display 
capabilities of a desktop PC with the database and number-crunching power of a large 
central system. But peer-to-peer programs can run equally well. 

Like many aspects of Microsoft programming, RFC forms a small world of its own, with 
conventions and terms that can be confusing. But once you understand the purpose 
behind each feature, programming with RFC is not difficult. This book lays out the 
concepts and the programming tasks so that you can use this powerful API. 

Microsoft RFC is a new technology based on the RFC used in the Distributed Computing 
Environment (DCE). This book builds on O Reilly s successful DCE series. It provides a 
solid foundation for programmers learning to use Microsoft RFC, including: 

Controlling communications through the Microsoft Interface Definition Language 
(MIDL) and the Attribute Configuration File (ACF) 

How the server advertises itself 

How a client chooses a server (binding) 

Types of pointers and arrays 

Memory management 

Administration tasks for an RFC server 

Maintaining state through context handles 

This edition covers version 2.0 of Microsoft RFC. Four complete examples are included. 



ISBN 1-56592-070-8 RepKover, 

90000 




Printed on Recycled Paper 

9 781565 920705 

- - - 1 ISBN 1-56592-070-8