Guide to Writing DCE Applications

Preface. Audience. Related Documentation. Conventions. Book Organization. How to Use this Book. Obtaining the Example Programs FTP. FTPMAIL. BITFTP. UUCP. PC-DCE Examples. Acknowledgments Joint Venture. Chapter 1: Overview of an RPC Application A Simple Interface Universal Unique Identifiers The Interface Definition Stub and Header Generation Using the IDL Compiler A Simple Client A Minimal Server Remote Procedure Implementation A Distributed Application Environment Server Initialization Producing the Application DCE Libraries Compile and Link the Client Code Compile and Link the Server Code Running the Application. Chapter 2: Using a DCE RPC Interface Interface Definition Language (IDL) Attributes Structure of an Interface Definition Interface Header Attributes The Inventory Application Type Definitions, Data Attributes, and Constants Procedure Declarations and Parameter Attributes Using the IDL Compiler Generating Client Files Generating Server Files Using an ACF To Customize Interface Usage Selecting a Binding Method Controlling Errors and Exceptions Excluding Unused Procedures Controlling Marshalling and Unmarshalling. Chapter 3: How to Write Clients Binding Implementing a Binding Method Automatic Binding Management Implicit Binding Management Explicit Binding Management Steps in Finding Servers Finding a Protocol Sequence Finding a Server Host Finding an Endpoint Interpreting Binding Information Finding a Server from a Name Service Database Finding a Server from Strings of Binding Data Customizing a Binding Handle Error Parameters or Exceptions Using Exception Handlers in Clients or Servers Using Remote Procedure Parameters To Handle Errors Compiling and Linking Clients Local Testing. Chapter 4: Pointers and Arrays Kinds of Pointers Pointers as Output Parameters Pointers as Input Parameters Using Pointers to Pointers for New Output Pointers as Procedure Return Values Pointer Summary Kinds of Arrays Selecting a Portion of a Varying Array Managing the Size of a Conformant Array. Chapter 5: How to Write a Server Some Background on Call Processing Initializing the Server Registering Interfaces Creating Server Binding Information Advertising the Server Managing Server Endpoints Listening for Remote Procedure Calls Writing Remote Procedures Managing Memory in Remote Procedures Allocating Memory for Conformant Arrays Compiling and Linking Servers. Chapter 6: Using a Name Service Naming Environment Variables Server Entries Creating a Server Entry and Exporting Binding Information Group Entries Creating a Group Entry and Adding a Member Profile Entries Creating a Profile and Adding Elements Accessing the Database Hierarchy with Default Elements. Chapter 7: Using Object UUIDs Servers and Resources Ways to Advertise and Locate Servers by Resource Advertising and Locating Resources by Name Only Advertising and Locating Resources by Object UUID Object UUIDs and the Binding Process Representing UUIDs An OK Usage Model for Exporting by Resource Initializing the Server Server Manager Code Server Termination Client Initialization Finding a Server Based on Interface Shortcomings A Better Usage Model for Exporting by Resource Initializing the Server Server Manager Code Server Termination Client Initialization Summary. Chapter 8: Using Authenticated RPC The Grade Server Application The DCE Security Model Principals Secret Key Authentication Authorization Authenticated RPC Writing the get_GPA Client Selecting a Protection Level Determining the Server Principal Name Running the get_GPA Client Security Setup Running the Grade Server Application. Chapter 9: Writing a Server that Uses Authenticated RPC Server Login Authenticating the Server Setting the Default Login Context Maintain Server Login Context Manage Server Key Register Principal Name with RPC The Reference Monitor Security Policy Grade Server Reference Monitor Administrative Operations Security Setup CDS set up Running the Grade Server Application. Chapter 10: Context Handles The Remote_file Application Declaring Context in an Interface Definition Using a Context Handle in a Client Binding Handles and Context Handles Managing Context in a Server Writing Procedures That Use a Context Handle Writing a Context Rundown Procedure. Chapter 11: Using Pipes for Large Quantities of Data The Transfer_data Application Defining Pipes in an Interface Definition The Pipe State Using an Input Pipe Using an Input Pipe in a Client Managing an Input Pipe in the Server Using an Output Pipe Using an Output Pipe in a Client Managing an Output Pipe in the Server Managing Multiple Pipes. Appendix A: IDL and ACF Attributes Quick Reference Appendix B: DCE RPC Runtime Routines Quick Reference Appendix C: The Arithmetic Application How To Run the Application Application Files Appendix D: The Inventory Application How To Run the Application Application Files Appendix E: The OK Banking Application How To Run the Application Appendix F: The Better Banking Application How To Run the Application Application Files Appendix G: The Grade Server Application How to Run the Application Application Files Appendix H: The Remote_file Application How To Run the Application Application Files Appendix I: The Transfer_data Application How To Run the Application Application Files. Figures. Chapter 1: Overview of an RPC Application 1-1 Client-server model 1-2 RPC mechanism 1-3 Application development 1-4 Arithmetic application: interface development 1-5 Arithmetic application: client development 1-6 Arithmetic application: server development 1-7 Binding 1-8 Binding information 1-9 Server initializing 1-10 Client finding a server 1-11 Completing a remote procedure call 1-12 Arithmetic application: complete development. Chapter 2: Using a DCE RPC Interface 2-1 Producing an interface. Chapter 3: How to Write Clients 3-1 A comparison of binding management methods 3-2 How a customized binding handle works 3-3 Producing a client. Chapter 5: How to Write a Server 5-1 How the server runtime library handles a call 5-2 Producing a server. Chapter 6: Using a Name Service 6-1 Server entries in the name service database 6-2 A simple use of a name service database 6-3 Group entries in a name service database 6-4 A simple search in a name service database 6-5 Profile entries in a name service database 6-6 Organizing entries in a name service database 6-7 Default elements in a name service database. Chapter 7: Using Object UUIDs 7-1 Inventory server with multiple databases 7-2 Multiple inventory servers 7-3 Resource-based server entries in the name service database 7-4 Object UUIDs in name service database entries 7-5 Exporting by resource 7-6 Importing by resource 7-7 Simple banking example name service database usage 7-8 Example UUID vector 7-9 Banking example using group entries as resource entries Chapter 8: Using Authenticated RPC 8-1 DCE security model for the grade server application 8-2 Kerberos authentication exchange. Chapter 9: Writing a Server that Uses Authenticated RPC 9-1 Major steps in implementing a server 9-2 Establishing the login context 9-3 DCE login 9-4 Reference monitor. Chapter 11: Using Pipes for Large Quantities of Data 11-1 Structure of pipe application code 11-2 Pipe data transfer from a client 11-3 Input pipe data transfer to a server 11-4 Pipe data transfer to a client 11-5 Output pipe data transfer from a server Examples. Chapter 1: Overview of an RPC Application 1-1 A Simple Interface Definition 1-2 A Simple Client 1-3 A Remote Procedure Implementation 1-4 A Minimal Server Initialization. Chapter 2: Using a DCE RPC Interface 2-1 Interface Header Attributes 2-2 IDL Type Definitions 2-3 Defining Strings in IDL 2-4 Defining an Enumerated Type in IDL 2-5 Defining Structures in IDL 2-6 Defining a Discriminated Union in IDL 2-7 A Discriminated Union Generated by the IDL Compiler 2-8 Using a Discriminated Union in Application Code 2-9 Procedure Declarations and Parameter Attributes 2-10 An Attribute Configuration File (ACF). Chapter 3: How to Write Clients 3-1 An ACF for the Implicit Binding Method 3-2 A Client with the Implicit Binding Method 3-3 Adding Binding Handles with an ACF 3-4 Defining a Binding Handle in the Interface Definition 3-5 A Client with the Explicit Binding Method 3-6 Interpreting Binding Information 3-7 Importing a Binding Handle 3-8 Setting a Binding Handle from Strings 3-9 Defining a Customized Binding Handle 3-10 Bind and Unbind Procedures 3-11 A Client with a Customized Binding Handle 3-12 The CHECK_STATUS Macro. Chapter 4: Pointers and Arrays 4-1 Defining an Output Parameter 4-2 Defining Optional Procedure Parameters 4-3 Defining Pointers to Pointers for Memory Allocation 4-4 Defining a Procedure that Returns a Pointer 4-5 How to Determine Kinds of Pointers 4-6 A Conformant Array in an Interface Definition. Chapter 5: How to Write a Server 5-1 Server Header Files and Data Structures 5-2 Registering an Interface with the Runtime Library 5-3 Creating Server Binding Information 5-4 Advertising the Server to Clients 5-5 Managing Endpoints in an Endpoint Map 5-6 Listening for Remote Procedure Calls 5-7 Memory Management in Remote Procedures 5-8 Conformant Array Allocation in a Remote Procedure. Chapter 7: Using Object UUIDs 7-1 Exporting by Resource: Dryer Parts Databases 7-2 Banking Server Header Files and Data Structures 7-3 Registering an Interface with the RPC Runtime Library 7-4 Creating Server Binding Handles 7-5 Advertising by Interface 7-6 Initializing the Object UUID/Resource Map 7-7 Exporting Resources to the Namespace 7-8 Creating a UUID List 7-9 Registering Resources in the Endpoint Map 7-10 Registering a Management Authorization Function 7-11 Listening for Remote Procedure Calls 7-12 Getting an Object UUID and Resource 7-13 Creating and Advertising a New Resource 7-14 Deleting and Removing a Resource 7-15 Shutting Down a Server 7-16 Locating a Server Based on Interface 7-17 Locating a Server Based on Resource 7-18 Binding Handle with an Object UUID from String 7-19 Exporting Resources to the Namespace 7-20 Deleting and Removing a Resource 7-21 Locating a Server Based on Resource. Chapter 8: Using Authenticated RPC 8-1 IDL File for Grade Server Application 8-2 Structure of Client Code 8-3 Inquiring the Server for Its Principal Name 8-4 Administrative Operations To Set Up the Grade Server 8-5 Running the Grade Server Application. Chapter 9: Writing a Server that Uses Authenticated RPC 9-1 Starting the Server from a Shell Script 9-2 Get Grade_Server's Network Credentials 9-3 Starting Up a Thread To Maintain the Login Context 9-4 Starting Up the Key Management Thread 9-5 Register Authentication Information with RPC 9-6 Remaining Server Initialization Code 9-7 Checking Authentication Parameters 9-8 A Reference Monitor 9-9 Administrative Operations Setup 9-10 Setting the Right Permissions in the Namespace 9-11 Running the Application. Chapter 10: Context Handles 10-1 Defining Context Handles 10-2 Using a Context Handle in a Client 10-3 Procedures that Use Context Handles 10-4 A Context Rundown Procedure. Chapter 11: Using Pipes for Large Quantities of Data 11-1 Defining Pipes 11-2 A Pipe Structure Generated by the IDL Compiler 11-3 A Pipe State Structure 11-4 Using an Input Pipe in a Client 11-5 A Client Alloc Procedure for a Pipe 11-6 A Client Pull Procedure for an Input Pipe 11-7 Processing an Input Pipe in a Remote Procedure 11-8 Using an Output Pipe in a Client 11-9 A Client Push Procedure for an Output Pipe 11-10 Processing an Output Pipe in a Remote Procedure 11-11 Processing Multiple Pipes in a Remote Procedure. Appendix C: The Arithmetic Application C-1 The Makefile for the Arithmetic Application C-2 The Client Shell Script for the Arithmetic Application C-3 The Server Shell Script for the Arithmetic Application C-4 The IDL File of the Arithmetic Application C-5 The Client File of the Arithmetic Application C-6 Remote Procedure of the Arithmetic Application C-7 Server Iniialization of the Arithmetic Application C-8 The Check Error Status Macro Appendix D: The Inventory Application D-1 The Makefile for the Inventory Application D-2 The Client Shell Script for the Inventory Application D-3 The IDL File of the Inventory Application D-4 Remote Procedures of the Inventory Application D-5 The Inventory Implementation D-6 Server Initialization of the Inventory Application D-7 The Automatic Client File of the Inventory Application D-8 The Implicit Client of the Inventory Application D-9 The Explicit Client of the Inventory Application D-10 The Makefile for the Implicit Client D-11 An ACF File for Implicit Binding D-12 The do_import_binding Procedure D-13 The do_interpret_binding Procedure D-14 The Makefile for the Explicit Client D-15 An ACF File for Explicit Binding Appendix E: The OK Banking Application E-1 The Makefile for the OK Banking Application E-2 The IDL File of the OK Banking Application E-3 The ACF of the OK Banking Application E-4 Check Error Status Macros E-5 The svr_support.h File E-6 Server Initialization of the OK Banking Application E-7 Remote Procedures of the OK Banking Application E-8 Supporting Functions for the OK Banking Application E-9 Shutdown Procedure for the OK Banking Application E-10 A Client File of the OK Banking Application E-11 Client Import Operations Appendix F: The Better Banking Application F-1 The Makefile for the Better Banking Application F-2 Server Initialization F-3 Remote Procedures F-4 Shutdown Procedure for the Better Banking Application F-5 A Client File of the Better Banking Application F-6 Import Operations in the Better Banking Application Appendix G: The Grade Server Application G-1 The Makefile for the Grade Server Application G-2 The IDL Fill of the Grade Server Application G-3 Client File of the Grade Server Application G-4 Server Initialization of the Grade Server Application G-5 Remote Procedure for the Grade Server Appendix H: The Remote_file Application H-1 The Makefile for the remote_file Application H-2 The IDL File of the remote_file Application H-3 A Client File of the remote_file Application H-4 The get_args Procedure H-5 The do_string_binding Procedure H-6 The Context Rundown of th remote_file Application H-7 Remote Procedures of the remote_file Application H-8 Server Initialization of the remote_file Application Appendix I: The Transfer_data Application I-1 The Makefile for the transfer_data Application I-2 The Float File Generating Utility I-3 The IDL File of the transfer_data Application I-4 A Client that Uses an Input Pipe I-5 A Client that Uses an Output Pipe I-6 Bind and Unbind Procedures I-7 The send_floats Procedure I-8 The receive_floats Procedure I-9 Server Initialization of the transfer_data Application I-10 The pipe_state Structure I-11 The client_alloc Procedure I-12 The in_pull Procedure I-13 The out_push Procedure Tables. Chapter 2: Using a DCE RPC Interface 2-1 IDL Basic Data Types 2-2 Notes on IDL Data Types. Chapter 3: How to Write Clients 3-1 Valid Protocol Sequences. Chapter 4: Pointers and Arrays 4-1 A Summary of Reference and Full Pointers. Chapter 5: How to Write a Server 5-1 Creating Binding Information with Well-known Endpoints. Chapter 10: Context Handles 10-1 Binding Handles and Context Handles in a Call Appendix A: IDL and ACF Attributes Quick Reference A-1 IDL Interface Header Attributes A-2 IDL Array Attributes A-3 IDL Pointer Type Attributes A-4 IDL Data Type Attributes A-5 IDL Structure Member Attributes A-6 IDL Union Case Attributes A-7 IDL Procedure Parameter Attributes A-8 IDL Procedure Attributes A-9 ACF Attributes