Windows NT Systems Programming

[ Home | Syllabus |Course Notes]

Design Issues Version 5

(Review Home Grown Solution)

Design Issues

• Why RPC?
• Performance
• Cross Platform
• Marshalling Parameters
• Types of Parameters
• Network Transport
• Setting up Server
• Finding Server

Why?

• Hybrid Operations
  • Computation resources
  • Data base resources
  • Memory resources
  • Other services
• Avoid Distribution
  • Code is proprietary
  • Reduces installation management
  • Access to latest version
• Finer Control
  • Keep statistics
  • Charge by access
  • Customized access
• Parallel Operation - distribute homogeneous or hetrogeneous computations over many procsessors
• Abstract Programmer's view of distributed computation - simplifies programming

Performance

Sources of significant overhead:

• Network Overhead
• Moving between address spaces
• Moving between platforms
• Finding the RPC Server

Cross Platform: Open Software Foundation (OSF)

Based on Unix DCE( Distributed Computing Environment)

• Cross platform
• multiple network protocols
• Hide network layer

Marshalling Parameters

Annotate function prototype with type + use information

Basic Types supported:

• boolean
• byte (8 bit)
• char (8 bit unsigned)
• double (64 bit real number)
• float (32 bit real number)
• long (32 bit integer - signed or unsigned)
• short (16 bit integer)
• small (8 bit integer)
• wchar_t (wide character)

Limited support for Pointers:

• array
  • first_is
  • last_is
  • length_is
  • max_is
  • min_is
  • ptr
  • ref
  • size_is
  • unique
• string
• in
• out

Network Protocols

endpoint(“protocol-sequence:[endpoint-port]” [ , ...] )

protocol-sequence

Specifies a character string that represents a valid combination of an RPC protocol (such as “ncacn”), a transport protocol (such as “tcp”), and a network protocol (such as “ip”). Microsoft RPC supports the following protocol sequences:

endpoint-port

Specifies a string that represents the endpoint designation for the specified protocol family. The syntax of the port string is specific to each protocol sequence.

Examples

endpoint("ncacn_np:[\\pipe\\rainier]")

endpoint("ncacn_ip_tcp:[1044]", "ncacn_np:[\\pipe\\shasta]")

Remarks

The endpoint attribute specifies a well-known port or ports (communication endpoints) on which servers of the interface listen for calls.

The endpoint specifies a transport family such as the TCP/IP connection-oriented protocol, a NetBIOS connection-oriented protocol, or the named-pipe connection-oriented protocol.

The protocol-sequence value determines the valid values for the endpoint-port. The MIDL compiler checks only general syntax for the endpoint-port entry. Port specification errors are reported by the run-time libraries. For information about the allowed values for each protocol sequence, see the topic for that protocol sequence.

The following protocol sequences specified by DCE are not supported by the MIDL compiler provided with Microsoft RPC: ncacn_osi_dna and ncadg_dds.

Make sure that you correctly quote backslash characters in endpoints. This error commonly occurs when the endpoint is a named pipe. Endpoint information specified in the IDL file is used by the RPC run-time functions RpcServerUseProtseqIf and RpcServerUseAllProtseqsIf.

Setting up the Server

• Manual binding: machine to known machine
• Assisted Manual binding: Get location of RPC server from Name Server
• Automated binding: Each RPC call automatically interrogates name server to find RPC server.

Server has to register its availability to "Name Server" with the last two.

Name Server

• NT locator
  • look on local machine
  • enumerate all machines on network and query each in turn OR
  • declare one machine to be the RPC name server. OR
  • can use a UNIX cell directory service
• UNIX cell directory server
• CAn divide the work among multiple RPC servers
•  

Simple Example

(source here)

Routine to Sum the integers from 1 to N, shown below:

#include <windows.h>

#include "sum.h" // generated by MIDL compiler (also generates sum_s.c)



long SumUp(short sumVal)

{

    short iter;

    long theSum;



    theSum=0;

    for (iter=1; iter<=sumVal; theSum+=iter, iter++);

    return(theSum);

}

RPC Client

/*

This program uses an autobinding RPC call to

calculate a running sum.

*/



#include <windows.h>

#include <iostream.h>

#include <rpc.h>

#include <stdlib.h>

#include "sum.h"

#include "memstub" // used by hidden functions in sum.h to allocate/free memory



INT main(VOID)

{

  CHAR sumUpToStr[10];

  long theSum;



  cout << "Enter a value to compute running sum: ";

  cin.getline(sumUpToStr, 10);



  theSum=SumUp((short)atoi(sumUpToStr));



  cout << "The running sum is: " << theSum << endl;



  return(0);

}

Interface Definition Langauge file (sum.idl) MANDATORY

[

  uuid (22449651-4321-1234-4321-987654321CBA), // generated by uuidgen -i (in VC/bin directory)

  version(1.0),

  endpoint ("ncacn_np:[\\pipe\\autorpc]",

                  "ncacn_ip_tcp:[1050]") // network connections permitted (can be multiple ones)

]

interface sumup // function names available

{

  long SumUp([in] short sumVal); // annotated function prototype

}

Attribute Configuration File (.ACF) - optional

[

  auto_handle

]

interface sumup

{

}

Server Body

• Responsible for setting up server
• Registering with name server (optional)
• Listening
•  

// autoserv.cpp



#include <windows.h>

#include <iostream.h>

#include <rpc.h>

#include "sum.h"

#include "memstub"



INT main(VOID)

{

  RPC_BINDING_VECTOR *bindVector;



  // use the protocols specified in the

  // IDL file for this interface

  if (RpcServerUseAllProtseqsIf(1,

    sumup_v1_0_s_ifspec, NULL))

  

  // register the interface

  if (RpcServerRegisterIf(sumup_v1_0_s_ifspec,

    NULL, NULL))

  

  // get binding handles for the interface

  if (RpcServerInqBindings(&bindVector))

  

  // add an entry in the name service 

  // for the interface

  if (RpcNsBindingExport(RPC_C_NS_SYNTAX_DEFAULT,

    (UCHAR *) "/.:/autorpc", 

    sumup_v1_0_s_ifspec, bindVector, NULL))

  

  // listen for and service RPC requests

  if (RpcServerListen(1, 5, FALSE))

  }

• F1: Obtains protocol and endpoint information generated by IDL file. Registers with RPC run time library. RPC library creates one binding handle for each protocol registered.
• F2: defined in "sum_s.c" - contains protocol and endpoint information
  RPC_IF_HANDLE sumup_v1_0_s_ifspec = (RPC_IF_HANDLE)& sumup___RpcServerInterface;
• F3: Registers interfaces (can be unlimited number of RPC function calls)
• F4: List of all bindings provided which were created in RpcServerUseAllProtseqsIf
• F5: Registers RPC server with name server
• F6: serves forever

Manual Binding

Automatic is easier to code but inefficient since every RPC call needs to query Name Server
So let's try manual binding or assisted manual.

// conserv.cpp



#include <windows.h>

#include <iostream.h>

#include <rpc.h>

#include "sum.h"

#include "memstub"



INT main(VOID)

{

  // use the specified protocol and endpoint

  if (RpcServerUseProtseqEp(

    (UCHAR *) "ncacn_ip_tcp", 1,

    (UCHAR *) "55449", NULL))

 

  // register the interface

  if (RpcServerRegisterIf(sumup_v1_0_s_ifspec,

    NULL, NULL))

 

  // listen for and service RPC requests

  if (RpcServerListen(1, 5, FALSE))

 

 

• F7: Alternate way to specify endpoint/protocol information (instead of IDL file)
• IDL file is simpler - does not need above information
• Does not need to register with the name server.

ACF

[

  implicit_handle(handle_t SumUpHandle)

]

interface sumup

{

}

Complicates Client Code

// conclnt.cpp



/*

This program calls an RPC function 

using a manual handle.

*/



#include <windows.h>

#include <iostream.h>

#include <rpc.h>

#include <stdlib.h>

#include "sum.h"

#include "memstub"



INT main(VOID)

{

  CHAR sumUpToStr[10];

  long theSum;

  UCHAR *stringBinding;                   



  cout << "Enter a value to compute running sum: ";

  cin.getline(sumUpToStr, 10);



  // put together string binding

  if (RpcStringBindingCompose(NULL,            

    (UCHAR *) "ncacn_ip_tcp", 

    (UCHAR *) "localhost",

    (UCHAR *) "55449", NULL, &stringBinding))



  // bind to server using string binding info

  if (RpcBindingFromStringBinding(stringBinding,

    &SumUpHandle))

  

  // free the string binding info

  if (RpcStringFree(&stringBinding))

  

  theSum=SumUp((short)atoi(sumUpToStr));



  cout << "The running sum is: " << theSum << endl;



  // release binding to server

  if (RpcBindingFree(&SumUpHandle))

  

  

• F8: Creates binding handle string from machine name, protocol and endpoint
• F9: Binds to server SumUpHandle defined in "sum.h" file

Copyright chris wild 1997.
For problems or questions regarding this web contact [Dr. Wild].
Last updated: October 29, 1997.