Previous section.

CDE 1.1: Remote Procedure Call
Copyright © 1997 The Open Group

Introduction to the RPC API

This chapter provides a general description of the programming model implemented by the RPC Application Programming Interface (API). This description includes definitions of many of the concepts used throughout the RPC API manual pages. As such, it is a necessary prerequisite to the understanding of the manual pages, and the manual pages assume knowledge of this chapter, even when they do not make explicit reference to it.

The description serves three purposes:

The general information covers topics, such as binding and name service usage, that are relevant to many of the manual pages. Typically, several routines perform tasks related to a given topic. This introduction provides a general model within which the tasks performed by individual routines and suites of routines can be understood. This general model also provides a rationale for the set of routines included in this document. It describes the underlying operations required for RPC programming and shows how the set of RPC APIs included in this document gives access to these operations.

In showing how the RPC API routines are meant to be used, this chapter provides certain guidelines for consistent RPC client/server interface usage. These guidelines cover such areas as using the naming services and organising server resources. By following them, programmers can simplify the task of maintaining and enhancing server interfaces and writing client programs.

RPC Programming Model Overview

The RPC programming model can be viewed along two axes:

Each view describes important aspects of the use of the RPC API.

Client/Server Model

The client/server view of RPC programming describes the distributed resource model implemented by the RPC mechanism. In this view, programming tasks are divided between servers, which provide services or make resources available to remote clients, and clients, which seek and make use of these services or resources.

Interfaces

The central component of the client/server model is the interface. An interface is a set of remotely callable operations offered by a server and invokable by clients. Interfaces are implemented by managers, which are sets of server routines that implement the interface operations. RPC offers an extensive set of facilities for defining, implementing and binding to interfaces.

The RPC mechanism itself imposes few restrictions on the organisation of operations into interfaces. RPC does provide a means to specify interface versions and a protocol to select a compatible interface version at bind time (see Interface Definition Language and Remote Procedure Call Model ). When an interface is specified as a new version of an existing interface, the server manager code must provide the required version compatibility. Beyond this restriction, the programmer is free to place any set of remotely callable operations in a given interface.

Remoteness

The RPC paradigm makes remote calls an extension of the familiar local procedure call mechanism. Specifically, the call itself is made as a local procedure call, and the underlying RPC mechanism handles the remoteness transparently. Server interface programming is thus similar to local procedure call programming, except that the handler of the call runs in a separate address space and security domain.

From this point of view, a local procedure call is a special simple case of the more general call mechanism provided by RPC. RPC semantics extend local procedure call semantics in a variety of ways:

Reliability
Network transports may offer varying degrees of reliability. The RPC run-time system handles these transport semantics transparently, but RPC call specifications include a specification of execution semantics that indicates to the RPC protocols the required guarantees of success and the permissibility of multiple executions on a possibly unreliable transport. Server application code must be appropriate for the specified execution semantics.

Binding
RPC binding occurs at run time and is under program control. Client and server use of the RPC binding mechanism is discussed extensively in this chapter.

No Shared Memory
Because calling and called procedures do not share the same address space, remote procedure calls with input/output parameters use copy-in, copy-out semantics. For the same reason, RPC has no notion of "global data structures" shared between the caller and callee; data must be passed via call parameters.

Failure Modes
A number of failure possibilities arise when the caller and callee are on physically separate machines. These include remote system or server crashes, communications failures, security problems and protocol incompatibilities. RPC includes a mechanism to return such remote errors to the caller.

Cancels
RPC extends the local cancel mechanism by forwarding cancels that occur during an RPC to the server handling the call, allowing the server application code to handle the cancel. RPC adds a cancel time-out mechanism to ensure that a caller can regain control within a specified amount of time if a cancelled call should fail to return.

Security
Executing procedures across physical machine boundaries and over a network creates additional requirements for security. The RPC API includes an interface to the underlying security services.

The RPC API provides programmers with the means to apply these extended semantics, but it shields applications from the rigours of transport level send-and-receive programming. The RPC programming paradigm gives the programmer control of the remote semantics at two points: in the interface specification and through the RPC API.

Binding

A remote procedure call requires a remote binding. The calling client must bind to a server that offers the interface it wants, and the client's local procedure call must invoke the correct manager operation on the bound-to server. Because the various parts of this process occur at run time, it becomes possible to exercise nearly total programmatic control of binding. The RPC API provides access to all aspects of the binding process.

Each binding consists a set of components that can be separately manipulated by applications, including protocol and addressing information, interface information and object information. This allows servers to establish many binding paths to their resources and allows clients to make binding choices based on all of the components. These capabilities are the basis for defining a variety of server resource models.

Name Services

Servers need to make their resources widely available, and clients need some way to find them without knowing the details of network configuration and server installation. Hence, the RPC mechanism supports the use of name services, where servers can advertise their bindings and clients can find them, based on appropriate search criteria. The RPC API provides clients and servers with a variety of routines that can be used to export and import bindings to and from name services.

Resource Models

The client/server model views servers as exporters of services-via RPC interfaces-and clients as importers of those services. Exported services typically take the form of access to resources, such as computational procedures, data, communications facilities, hardware facilities, or any other capabilities available to an application on a networked host. The RPC mechanism does not distinguish among such resource types in any way. On the contrary, it provides a uniform means of access-the remote procedure call-and allows the programmer to define the underlying resource model freely.

RPC does, however, provide specific mechanisms that implicitly support different approaches to resource modeling. These mechanisms take advantage of the flexibility of the binding process and the name services. The RPC mechanism supports three basic resource models:

By Server
In this model, clients seek to bind to a specific server instance that provides an interface of interest.

By Service
In this model, clients seek a service-as represented by an interface-without concern for the specific server instance that provides that service or any objects that the server manages.

By Object
In this model, clients seek a binding to any server that manages a specific object. An object may be any computational resource available to a server.

The RPC programming mechanism does not explicitly enforce these models. Instead, they are supported implicitly by making available a set of run-time binding and name service facilities through the RPC API. Programmers may use these facilities according to their application requirements. However, this document recommends that programs follow the models specified here in order to ensure consistent use of the client/server interface.

Security Services

The RPC API provides access to a variety of security services: client-to-server and server-to-client authentication, authorisation of access to server resources (which may carry delegation information inserted by security routines), and varying degrees of cryptographic protection of client/server communications.

Server Implementation

The client/server view of RPC is necessarily asymmetric. The model is based on providing services remotely via the export of RPC interfaces. Since servers are the means for implementing remote interfaces, the model is server-centred. The RPC architecture provides certain server facilities that make the implementation of servers more efficient. These include

Server Concurrency
Implementations may buffer RPC requests at the server and automatically provide multiple threads to handle concurrent requests, relieving the application programmer of these tasks.

Remote Management
The RPC run-time system automatically offers a set of remote server management interfaces that can be used for such purposes as querying and stopping servers.

Application/Stub/Run-time System

The application/stub/run-time system view of RPC describes the division of labour between application code and other RPC components in implementing a remote procedure call.

RPC Run Time

At the core of this model is the RPC run-time system, which is a library of routines and a set of services that handle the network communications that underlie the RPC mechanism. In the course of an RPC call, client-side and server-side run-time systems' code handle binding, establish communications over an appropriate protocol, pass call data between the client and server, and handle communications errors.

The RPC API is the programmer's interface to the run-time system. The run-time system makes use of a number of services, such as the endpoint mapper, name services and security services. The RPC API also provides an interface to these services for carrying out RPC-specific operations. Portable usage of the RPC API is fully specified in this section of this document.

Stubs

The stub is application-specific code, but it is not directly generated by the application writer and therefore appears as a separate layer from the programmer's point of view. The function of the stub is to provide transparency to the programmer-written application code. On the client side, the stub handles the interface between the client's local procedure call and the run-time system, marshaling and unmarshaling data, invoking the RPC run-time protocol, and if requested, carrying out some of the binding steps. On the server side, the stub provides a similar interface between the run-time system and the local manager procedures that are executed by the server.

RPC transparency to the application programmer is provided by the interface specification mechanism. The programmer specifies interfaces using an Interface Definition Language (IDL), and the IDL compiler generates stubs automatically from the specification. Thus, the actual operations performed by the stub are largely invisible to the programmer, although they form part of the application-specific program code.

This chapter does not cover the interface specification mechanism itself; this is documented in Interface Definition Language . What is covered here are the assumptions that the RPC programming model makes about stubs, such as well-known stub names and stub memory management.

Application Code

RPC application code falls into two categories:

In the first category are the procedures written by the programmer to implement the client and server operations of the remote procedure call. On the client side, these are simply local calls to the stub interfaces for the remote procedures. On the server side, these are a set of manager routines that implement the operations of the interface. In most applications, manager routines are presumably a major part of the server code. Recall that, aside from requiring managers to conform to the specified execution semantics and version behaviour, the RPC mechanism imposes no specific constraints on manager implementations.

The programmer-written application code interacts with the RPC run-time system principally through the stub. This makes run-time operations largely transparent to the application code. Nevertheless, in order to control binding, security and other aspects of the RPC mechanism, the application often needs direct access to run-time operations. The RPC API provides applications with such access to the RPC run-time system and related services.

API Operations

The RPC API provides access to an extensive set of run-time operations. RPC API Routine Taxonomy provides a detailed taxonomy of APIs according to the operations performed. This section offers an overview, based on a somewhat broader set of categories.

Subsequent sections of this chapter cover many of these groups of operations in detail.

Binding-related Operations

Binding-related operations establish a relationship between a client and server that makes possible a remote procedure call. These operations may be roughly divided into two categories:

Operations in the first category include the creation of communications endpoints by the server for the set of protocols over which it wishes to receive remote procedure calls. Servers typically export information about the bindings thus created to a name service and an endpoint map. Clients typically import such binding information from a name service and an endpoint map (see Name Service Operations and Endpoint Operations ).

Operations in the second category establish a set of mappings that the server can use to route calls internally to the appropriate manager routine. This routing is based on the interface and version, operation and any object requested by the call.

Name Service Operations

The RPC name service API includes an extensive set of operations for exporting and importing binding information to and from name services. These operations make use of a set of RPC-specific name service entry attributes to structure the exported binding information so that it can easily be found and interpreted by clients.

Endpoint Operations

Servers listen for remote procedure call requests over one or more protocol-specific endpoints. Typically, such endpoints are allocated dynamically when a server begins to listen, and their lifetime is only a single server instantiation. RPC provides an endpoint mapper mechanism that allows such volatile endpoint information to be maintained separately from the more stable components of a binding. Typically, servers export stable binding information to a name service and register their volatile endpoints with the local endpoint mapper. The endpoint mapper then resolves endpoints for calls made on bindings that do not contain them.

Endpoint operations are used by servers to register their endpoints with the endpoint mapper.

Security Operations

These operations establish the authentication and authorisation services and protection levels used by remote procedure calls.

Internationalisation Support Operations

These operations are used by applications to implement character and code set interoperability, which permits clients and servers to transfer international character data in a heterogeneous character set and code sets environment.

Stub Memory Management Operations

These operations are used by applications to manage stub memory. They are typically used by RPC applications that pass pointer data.

Management Operations

Management operations include a variety of operations with the potential to affect applications other than the one making the management call. Servers automatically export a set of remote management functions.

UUID Operations

UUIDs (Universal Unique Identifiers) are used frequently by the RPC mechanism for a variety of purposes. The UUID operations enable applications to manipulate UUIDs.

Binding

Binding refers to the establishment of a relationship between a client and a server that permits the client to make a remote procedure call to the server. In this document, the term "binding" usually refers specifically to a protocol relationship between a client and either the server host or a specific endpoint on the server host, and "binding information" means the set of protocol and addressing information required to establish such a binding. But, for a remote procedure call, such a binding occurs in a context that involves other important elements, paralleling the notion of a binding in a local procedure call. In order for an RPC to occur, a relationship must be established that ties a specific procedure call on the client side with the manager code that it invokes on the server side. This requires both the binding information itself and a number of additional elements (see Information Required to Complete an RPC ). The complete list is as follows:

  1. a protocol sequence that identifies the RPC and underlying transport protocols

  2. an RPC protocol version identifier

  3. a transfer syntax identifier

  4. a server host network address

  5. an endpoint of a server instance on the host

  6. an object UUID that can optionally be used for selection among servers and/or manager routines

  7. an interface UUID that identifies the interface to which the called routine belongs

  8. an interface version number that defines compatibility between interface versions

  9. an operation number that identifies a specific operation within the interface.

Figure: Information Required to Complete an RPC
Note:
The discussion in this chapter is intentionally vague about how any of this information is communicated between client and server. The underlying RPC protocol packages the required information for transmission. However, API usage is protocol-independent, and this chapter provides a protocol-independent description of RPC. Hence, this chapter typically refers to the binding information "contained" in a call without specifying how such information is actually transmitted or received. This is left to the RPC protocol specifications in Part 4, RPC Services and Protocols.

The binding information itself covers the first five elements of the list-the protocol and address information required for RPC communications to occur between a client and server.

Information Required to Complete an RPC also shows the object UUID as part of the binding information. This is explained in Binding Handles .

In RPC terminology, such a binding can be partial or full. A partial binding is one that contains the first four elements of the list, but lacks an endpoint. A full binding contains an endpoint as well. The distinction is that a partial binding is sufficient to establish communications between a client and a server host, whereas a full binding allows communications to a specific endpoint on the server host.

Binding Handles

The binding information required to make remote procedure calls is maintained by the client and server run-time systems on behalf of applications. The run-time system provides applications with opaque binding handles to refer to locally maintained binding information. Applications use binding handles to manipulate bindings via calls to the RPC API.

It is important to understand that binding handles are only valid in the context of the local client or server instance that created them. They are not used directly to communicate binding information between servers and clients. Typically, servers advertise binding information by exporting it to name service entries. When a client imports binding information from a name service, it receives a binding handle from the client run-time system that refers to the local copy of the imported binding information.

Note:
On the server side, such a binding handle refers to the first five elements shown in Information Required to Complete an RPC . On the client side, such a binding handle also refers to an object UUID associated with the binding information. For this reason, the figure includes the object UUID with the binding information even though it is not part of the protocol and address information required to establish communications between the client and server. The role of the object UUID is described in Interface and Manager Selection .
Client and Server Binding Handles

Binding information may refer either to a server or a client. Most of the time, binding information refers to servers, since it is servers to which clients need to bind in order to make remote procedure calls. When a binding refers to a server, a binding handle for it is called a server binding handle. Server binding handles are used both by clients and servers in the course of the binding process.

In some cases, servers need binding information for clients that call them. A binding handle that refers to such binding information is called a client binding handle. A small number of RPC APIs take client binding handles as arguments.

Obtaining Binding Handles

Applications obtain server binding handles by calling any of several RPC API routines. (See RPC Data Types for a list of routines that return server binding handles.)

A server obtains a client binding handle as the first argument passed by the run-time system to a server manager routine.

String Bindings

A string binding is a string representation of binding information, including an optional object UUID. String bindings provide binding information in human-readable form. Applications can use RPC API calls to request a string binding from the run-time system or convert a string binding into a binding that the runtime system can use to make a remote procedure call. String binding format is specified in RPC Data Types .

Binding Steps

In order to complete an RPC call, all of the elements listed in Information Required to Complete an RPC must be present. RPC divides the process of assembling these elements into several steps and organises the assembled information in a way that provides maximum flexibility to the binding process. To understand this, consider the opposite possibility: a binding mechanism that seeks to imitate a local procedure call's static binding to a local library routine. In this case, all the elements would be preassembled into a well-known binding to which the calling program would bind in an all-or-nothing fashion.

RPC is close to the other dynamic extreme. It purposely avoids creating static links among all the elements so that a final routing-from the client procedure call to the server manager routine invoked-can be dynamically determined at the time of the RPC. From the programmer's point of view, one of the principal differences between a local procedure call and a remote procedure call is that the binding process-the way all these components are linked together-occurs at run time and can be carried out, optionally, under application program control.

This serves several purposes:

The binding process consists of a series of steps taken by the client and server to create, make available and assemble all the necessary information, followed by the actual RPC, which creates the final binding and routing using the elements established by the previous steps. To break the process down in more detail:

Each of the components listed in Information Required to Complete an RPC is involved at some stage of this process. Some components are involved at more than one stage and may be used in more than one way. The following sections consider each stage and component in some detail.

Server Binding Steps

The server takes a number of steps to establish binding state in the server side run-time system, the name service and the endpoint mapper. The server's basic task is to acquire a set of endpoints from the run time and set up a series of relationships among binding elements that will then be used to construct the final routing at call time.

Server Binding Relationships shows the set of relationships that a server must establish to receive remote procedure calls. As the figure indicates, these are maintained in several places:

Figure: Server Binding Relationships

The server takes several steps (some of them optional) to establish the necessary relationships, as indicated in Server Binding Relationships . The steps are as follows:

  1. The server application or stub code defines a manager Entry Point Vector (EPV) for each manager that the server implements. Recall that a manager is a set of routines that implements the operations of an interface and that servers may implement more than one manager for an interface; for example, to provide for different versions or object types. Each EPV is a vector of pointers to the operations of the manager. When an RPC request arrives, the operation number is used to select an element from one of the manager EPVs.

  2. The server registers a set of object UUID/type UUID associations with the RPC run-time system.

  3. The server registers interface identifier/type UUID/EPV associations with the RPC run-time system. Together with the previous step, this establishes the mappings that permit the run-time system to select the appropriate manager, based on the interface ID and any object UUID contained in a call.

  4. The server application tells the run-time system what protocol sequences to use, and the run-time system establishes a set of endpoints for the protocol sequences requested. The server may ask the run-time system for its bindings, and the run time will return a set of binding handles that refer to the binding information for these endpoints.

  5. The server may register binding information, consisting of a set of interface identifier/binding information/object UUID tuples, with the endpoint mapper. For each interface, the registered data consists of a cross product of the bindings and object UUIDs that the server wants to associate with that interface. When a call is received with a partial binding (that is, one lacking an endpoint) the endpoint mapper is able to use this information to select an endpoint that is capable of handling the call.

  6. The server may export binding information to one or more name service entries. The information exported here looks quite similar to the information registered in the endpoint map in the previous step, with one important difference. The binding information exported to the name service generally lacks an endpoint, consisting of protocol and host address information only. Therefore the name service contains only the most persistent part of the binding information while the endpoint map contains the volatile endpoint portion.

    (The format is also different. See Name Service Interface for information about the format of server entries.)

Note that not all of these steps are required. Servers may construct their own bindings, by using string bindings, rather than request them from the run-time system as described in step 4. Servers may also avoid exporting binding information to a name service and endpoint map as described in steps 5 and 6. In such a case, clients must then construct bindings from string bindings obtained by some other means.

Having completed the required steps, the server has established a set of relationships that allows the server run-time system to construct a complete binding, with routing to a specific server operation, for a call that contains the following information:

The algorithms used are described in some detail in Search Algorithm . That discussion will show how the relationships established make possible a large number of paths to the interface and manager that are ultimately selected.

Note that the server run-time enironment itself maintains only a very limited set of relationships: interface identifier/type UUID/manager EPV and object UUIDs/type UUIDs. It is especially worth noting that the run-time system maintains no relationships between the protocol-address bindings it has created and any of the other information. The server merely advertises the relationships it wants to export in a name service and registers them in the endpoint map.

When the exported information is used by clients to find the server, client calls arriving at the server endpoints should contain interface identifier/object UUID pairs that the server can, in fact, service, although the RPC mechanism itself can provide no guarantee of this. This means that name service operations, while they are not, strictly speaking, a required part of an RPC call, usually play an important role in constructing bindings. Server Resource Models shows how this makes the name service a key element in the organisation of server resources.

The indirect mapping from object UUID to type UUID to EPV (and hence to the manager called) also gives the server great flexibility in organising its resources based on objects UUIDs. This is explained in Server Resource Models .

Client Binding Steps

The client binding steps are considerably simpler than those taken by the server. The basic task of the client is to find a suitable binding and use it to make a call, as described in the following steps.

Note:
The following steps outline the explicit binding method. Client application code can avoid explicitly having to carry out step 1 by using the automatic binding method. In this case, the stub code takes care of importing suitable bindings. In step 2, clients can avoid having to supply an explicit binding handle for each call by choosing either the automatic or the implicit binding method. Binding methods are described in Binding Steps and Interface Definition Language .

  1. Clients get suitable bindings by importing them from a name service. (Clients may also construct suitable bindings from binding information otherwise known to them, but here we describe the more general mechanism.)

    To make a call, the client needs a compatible binding: that is, one that offers the interface and version desired, uses a mutually supported protocol sequence, and if requested, is associated with a specific object UUID.

    Clients find compatible bindings by making calls to RPC API routines that search the name service. Recall that a name service entry binding attribute stores a set of associations between interface IDs and binding information. The client needs to find an element that specifies the desired interface and an acceptable protocol sequence and import the binding information from that element.

    Typically, the client specifies the interface desired, and the run-time system takes responsibility for finding bindings with protocol sequences that it can use. The client may also further select a specific protocol sequence.

    The client's selection of a binding may also depend on an object UUID. Recall that each name service entry may also store a set of object UUIDs. If the client requires a specific object UUID, it imports bindings only from name service entries that store that object UUID.

    For each binding that the client imports, the run-time system provides a server binding handle that refers to the binding information maintained by the client run-time system. This differs somewhat from the binding information referred to by a server binding handle on the server side. Recall that on the server, a server binding handle refers to a combination of protocol sequence and server address information. On the client side, a server binding handle may additionally refer to an object UUID, if the client has selected its bindings by object UUID.

  2. Once the client has found a compatible binding, it makes a call using the binding handle for that binding. Depending on the binding method chosen, the client application code may supply the binding handle explicitly or it may leave this to the stub code (see Binding Steps and Interface Definition Language ). When the call is made, the client run-time system has available to it the binding information and any object UUID referred to by the binding handle. Also available in the stub code are the interface identifier of the interface on which the call was made, and the operation number of the routine being called. Recall that the last three items of this tuple of information- the object UUID/interface identifier/operation number-are precisely what the server needs to route the call to a specific manager operation.

Call Routing Algorithms

Once the server and client have taken all the necessary steps to set up server and client side relationships, the call mechanism can use them to construct a complete binding and call routing when the call is made. This section specifies the algorithms used. In following these algorithms, it may be useful to refer to Server Binding Relationships to see how each of the relationships described there is used.

Endpoint Selection
When the client makes a call with a binding that lacks an endpoint, the endpoint is acquired from the endpoint mapper on the target host. The endpoint mapper finds a suitable endpoint by searching the local endpoint map for a binding that provides the requested interface UUID, and if requested, object UUID. The flowchart in Decisions in Looking Up an Endpoint shows the algorithm.
Figure: Decisions in Looking Up an Endpoint

What is important to note in this algorithm is that the interface and protocol information must match to find an endpoint, but an object UUID match may not be required. A server can provide a default UUID match by registering the nil UUID. Calls with a nil or unmatched object UUID follow the default path.

The endpoint map permits multiple endpoints to be registered with identical interface, protocol and object UUID information. Such endpoints are assumed to be interchangeable, and the endpoint mapper selects among them using an implementation-dependent algorithm.

Interface and Manager Selection

Having selected an endpoint, a call can be routed to one of the endpoints being used by a compatible server instance. The server can unambiguously select the correct interface and operation by using the interface identifier and operation number contained in the call. A call's interface identifier matches an interface identifier registered by the server when the interface UUIDs and major version numbers are equal and the call's minor version number is less than or equal to the minor version number registered by the server.

Recall, however, that the RPC mechanism makes it possible for a server to implement multiple managers for an interface. Hence it may be necessary to select the correct manager. Manager selection is based on the object UUID contained in the call. The selection mechanism depends on two of the relationships established by the server: the object UUID/type UUID mapping and the interface ID/type UUID/manager UUID mapping. The flowchart in Decisions for Selecting a Manager shows the selection algorithm.

Figure: Decisions for Selecting a Manager

Here the server provides a default path by registering a default manager for the nil type UUID. Calls containing the nil object UUID, or any UUID for which the server has not set another type UUID, will be directed to the default manager.

Dispatching via the Manager EPV

Once the manager is selected, the call is dispatched via the selected manager EPV. Recall that a manager EPV is a vector of pointers to manager routines, one for each operation of the interface. The operation number is used to select the appropriate routine.

The actual call-via the manager EPV-to the server manager code is made by the server stub. Up to this point, the binding discussion has deliberately avoided questions of implementation. The run-time system maintains a set of relationships logically required by the binding algorithms, but the way in which these are implemented is entirely outside the purview of this document. The case of the manager EPV is different, however. The manager EPV is an interface-specific data structure that must be declared by server code. The stub normally declares a default manager EPV, but when there is more than one manager for an interface, the application code must declare further manager EPVs. RPC Data Types shows how to construct the appropriate declaration.

Binding Methods

Client applications can exercise varying degrees of control over the binding process outlined in Client Binding Steps .

The automatic and implicit binding methods are interface wide and thus mutually exclusive. The explicit binding method may be specified per call and takes precedence over implicit or automatic binding specified for an interface.

Clients applications choose a binding method for an interface by specifying an ACS binding attribute, as documented in Interface Definition Language .

Name Service Interface

The RPC API provides an extensive name service interface that applications use to export and import binding information. In general, name services can support much broader usage, but the RPC API is designed to support the RPC binding mechanism, rather than as a generalised name service interface. The following sections describe those aspects of name services that are relevant to the name service interface and binding.

The name service interface is designed to be independent of the underlying name service. Hence, it is referred to as the Name Service-independent (NSI) interface. As far as possible, these sections describe the name service interface without reference to any specific underlying name service. However, applications using the name service interface need to pass name service-specific names to the interface and therefore must be aware of the details of naming for the underlying services. These issues are discussed in Name Syntax Tags .

Name Service Model

The name service interface is designed to allow servers to export binding information, and clients to find it, in an efficient manner. The interface permits servers to organise their binding information in a variety of ways. These support the server resource models described in Server Resource Models .

The name service interface makes two general assumptions about the underlying name service:

The name service interface is used to store associations between bindings, interfaces and objects in name service entries. For each interface offered by a server, the server exports a set of protocol towers to the name service. A protocol tower combines binding information (not including an object UUID) for a single binding with an interface identifier. The set of protocol towers exported for an interface thus represents available bindings to the server for that interface. Servers can also export sets of object UUIDs associated with arbitrary resources they offer. The binding information exported by servers may be organised in a number of name service entries. The API makes use of several entry attributes, as described in Name Service Attributes , to store binding-related information.

Clients make name service API calls to search for suitable bindings, specifying the interface and, possibly, any object UUID they are interested in, as well as a starting point for the search. The name service search operations search name service entries and return bindings that are compatible with the requirements of the client.

A client search of the namespace beginning at a given entry follows a path through name service entries determined by the algorithm given in Search Algorithm . The name service interface permits applications to define prioritised paths through the namespace, including default paths. Default paths make it possible to minimise the amount of knowledge about the namespace required by a client to begin searching for bindings.

Name Syntax Tags

The name service interface maintains its name service independence by using name syntax tags. Each interface that takes an entry name argument also takes an entry name syntax tag argument that indicates which name service syntax is to be used to interpret the name. Supported values for this argument are specified in Name Syntax Constants .

RPC ISO C implementations provide an RPC_DEFAULT_ENTRY_SYNTAX environment variable that specifies a default entry name syntax tag.

Name Service Attributes

The name service interface defines four RPC-specific name service attributes. These are as follows:

Binding Attribute
The binding attribute stores a set of protocol towers. An entry with the binding attribute is known as a server entry.

Group Attribute
The group attribute stores a set of entry names of the members of a single group. An entry with the group attribute is known as a group entry.

Profile Attribute
The profile attribute stores a set of profile elements. An entry with the profile attribute is known as a profile entry.

Object Attribute
The object attribute stores a set of object UUIDs.

Code Sets Attribute
The code sets attribute stores a code set array.

While the name service interface does not impose any explicit restrictions on the use of these entries (there are no enforced schema), the name service model is designed to support applications that structure their name service entries according to the following recommended rules:

The following sections describe the contents of the entry types in detail.

Server Entries

Server entries contain bindings for a single server. Server entries may also contain an object attribute that specifies a set of object UUIDs associated with the server.

The binding attribute in a server entry stores a set of protocol towers. Recall that a protocol tower consists of an interface identifier along with binding information. Typically, the binding information lacks an endpoint so that the information represents a partial binding.

The information stored by the binding attribute does not include object UUIDs. Instead, when a server wishes to associate object UUIDs with the bindings stored in a server entry, it exports them to an object attribute in that entry. As described in Interface and Manager Selection , object UUIDs may be used to map calls to object-specific type managers, but servers may also use object UUIDs to identify any arbitrary server resource. When clients import bindings, they can specify object UUIDs so as to import bindings only for servers that provide a required resource. This usage of object UUIDs plays an important role in the server resource models described in Server Resource Models .

Group Entries

A group entry contains names of one or more server entries, other groups or both. A group provides a way to organise the server entries of different servers that offer a common RPC interface or object. Since a group can contain group names, groups can be nested. Each server entry or group named in a group is a member of the group. A group's members should offer one or more RPC interfaces, objects or both in common.

Profiles

A profile is an entry that contains a prioritised set of profile elements. A profile element is a database record that corresponds to a single RPC interface and that refers to a server entry, group or profile. Each profile element contains the following information:

Additionally, a profile can contain at most one default profile element. A default profile element is the element that a name service search operation uses when a search using the other elements of a profile finds no compatible binding information. A default profile is a profile referenced by a default profile element. Default profiles are typically used as an administrative device to optimise clients' searches for compatible bindings.

Code Sets Arrays

The code sets attribute stores a server's code sets array, which is the list of the code sets that the server supports. This information is used by the internationalization support routines. The code sets array structure consists of a version number member (version), followed by a count member (count), followed by an array of code set data structures (rpc_cs_c_set_t). This array is declared to be a conformant array so that its size will be determined at runtime. The count member indicates the number of code sets contained in the array.

The first element in the code sets array represents the server process's local code set. The second through nth elements represent one or more intermediate code sets that the process can use to transmit character data over the network. The remaining elements represent other code sets supported by the server.

See Internationalisation Support Model and Internationalisation Support Operations for more information about code sets arrays.

Binding Searches

Routines to extract information from a name service are present in the API in suites of three. Each suite includes:

In general, applications use these suites as follows:

  1. The application obtains a name service handle by calling the begin routine. RPC Name Service routines use name service handles to refer to search state information maintained by the run-time system. The data type declaration for these handles is described in RPC Data Types .

  2. The application calls the next routine one or more times using the handle obtained in step 1. Each call returns another element, or set of elements, along the path being searched.

  3. The application calls the done routine using the handle obtained in step 1 to terminate the search.

The begin routine returns a handle used by a subsequent series of search operations. The handle refers to information maintained by the run-time system about the search, including search context information-such as matching criteria-and information about the current state of the search. Each call to the begin routine returns a handle that maintains the context for a distinct series of subsequent search operations.

The next routine returns elements, or sets of elements, one by one along the path being searched. The application calls this routine one or more times with a handle obtained from the begin routine. Each call returns another element or a status code that indicates that no more elements remain. Calls to the next routine using the same handle form part of one series of search operations along a search path. Calls to the next routine using different handles pertain to distinct and independent searches.

The done routine frees the search context referred to by the handle and invalidates the handle.

Search Algorithm

The name service search operations traverse a path through one or more entries in the name service database when searching for compatible binding information. The path taken by any name service search, beginning at a given entry, depends on the organisation of binding information using the various name service entry attributes. This section describes the algorithm used by name service searches to determine what steps to take at each traversed entry.

In each name service entry, searches ignore non-RPC attributes and process the name service entry attributes in the following order:

  1. the binding attribute (and object attribute, if present)

  2. the group attribute

  3. the profile attribute.

If a search path includes a group attribute, the search path can encompass every entry named as a group member. If a search path includes a profile attribute, the search path can encompass every entry named as the member of a profile element that contains the target interface identifier.

The following pseudocode presents the algorithm for retrieving bindings from a namespace. This describes the order in which bindings are returned by the routines rpc_ns_binding_import_done() and rpc_ns_binding_lookup_next().

In the pseudocode, each entryName, group member and profile element represent names that may be found in the namespace. Associated with each of these entries in the namespace may be any of the eight possible combinations of the binding, group and/or profile attributes.

The order in which bindings are returned is significant and is indicated in the algorithm. This algorithm only indicates the order of search. Local buffering constraints may cause the search to be interrupted and resumed.

Procedure GetBindings (someName) {
  /* "someName" represents the name of an entry in the namespace. */
  
  /* The following procedure recursively searches for bindings */
  Procedure Search(entryName)
    {
      Check entryName for binding attribute;
      If (binding attribute found)
        {
          Retrieve bindings from binding attribute;
          Randomise the bindings obtained from this attribute;
          Add these bindings to the bottom of the global list of bindings;
        }
      
      Check entryName for group attribute;
      If (group attribute found)
        {
          Retrieve members from group attribute and save in a list;
          Randomise the members in this list;
          Do
            {
              Select the first member and remove from the list;
              /* */
              /* Cycle checking requires knowledge of other   */
              /* names referenced within the scope of a call  */
              /* to GetBindings.                              */
              /* */
              Check for a cycle;
              If (not a cycle)
                {
                  If (member selected exists)
                    {
                      Search (member selected);
                    }
                }
            }
          Until (list of members is empty);
        }
      
      Check entryName for profile attribute;
      If (profile attribute found)
        {
          Retrieve elements from profile attribute and save in a list;
          Sort profile elements in list by priority, highest first;
          Randomise the profile elements within each priority;
          Do
            {
              Select the first profile element and remove from the list;
              /* */
              /* Cycle checking requires knowledge of other   */
              /* names referenced within the scope of a call  */
              /* to GetBindings.                              */
              /* */
              Check for a cycle;
              If (not a cycle)
                {
                  If (element selected exists)
                    {
                      Search (element selected);
                    }
                }
            }
          Until (list of profile elements is empty);
        }
    } 
  
  /* This is the body of the main routine starting the search */

  Initialize a global ordered list of bindings to empty; 
  Search (someName);
  return ordered list of bindings;
}

Name Service Caching

Name service interface operations may cache name service data to avoid unnecessary lookups in the name service database. Whether caching occurs is implementation-dependent, but it is expected that most implementations will use caching. For implementations that cache, this document specifies the semantics of caching to be governed by an expiration age as follows. Cached name service data is given an expiration age when it is cached. Name service interface operations use the cached copy when it has not outlived its expiration age. When a name service interface operation refers to cached data that has outlived its expiration age, the data is looked up in the name service database and the cache is updated.

The RPC run-time system sets the expiration age to a default value. Applications can specify another value either globally for the application or for a specific name service handle. The global value applies, by default, to all name service operations performed by the application. A handle-specific value applies only to operations performed using a specific name service handle.

When an application changes its global expiration age, or even the expiration age for a single handle, the effects may not be entirely confined to the application itself. Frequent updates of name service cache data may affect the performance of other clients of the name service and applications sharing the same cache. For this reason, operations that affect expiration age are considered to be management operations.

A non-caching implementation may be considered as a degenerate case of a caching implementation that behaves as if every cache item had outlived its expiration age.

Server Model

The RPC model is server-centred in the sense that RPC provides many facilities to support varied and powerful server implementations, often with relatively little programming effort. These include:

Server Concurrency and Request Buffering

The RPC design assumes that servers export resources that may be widely available and possibly in high demand. The RPC model therefore provides for automatic concurrent service and buffering of RPC requests.

RPC provides server concurrency without requiring application code to spawn additional threads or processes explicitly. When beginning to listen for a call, the server application requests a number of call threads, and the RPC run-time system automatically provides the requested threads, up to an implementation-defined limit. Applications that request more than one call thread must, however, implement manager routines in a thread-safe manner.

Implementations may also allow additional requests that cannot be executed concurrently to be queued for subsequent execution. Otherwise they are rejected. Applications may make buffer size requests when registering a protocol sequence, although the actual buffer size provided is implementation-dependent.

Management Interface

Servers automatically implement, in addition to the interfaces specified by the programmer, a set of remote management interfaces that can be used for such operations as making remote inquiries to and stopping servers. These are accessible, both locally and remotely, via management RPC routines.

Server Resource Models

The RPC API gives programs a high degree of control of the process by which bindings are constructed, component by component. This allows programs to specify the precise service required by any given instance of a remote procedure call. At the same time, the name service interface permits applications to structure binding information stored by a name service in a variety of ways. Together, these capabilities are the basis for a variety of strategies for organising server resources, based on the way the components of a binding are made available by a server.

The RPC API does not require server resources to be organised in any specific way; it simply provides facilities that permit a variety of forms of organisation. The resource models outlined here are only conventions. However, this document recommends following these conventions. Servers provide resources that may be widely available, and they make use of a common resource-the name services-to advertise their bindings. Organising server resources according to well-defined conventions makes it easier to construct clients that can find the resources they need.

This document recommends three basic server resource models:

These models are not mutually exclusive.

The Server-Oriented Model

In the server-oriented model, it is the server that is of interest to clients looking for bindings. In the simplest case, each server exports its bindings to one server entry and clients can go directly to a server entry to find bindings. Server instances may be interchangeable if they are running on the same host and offer the same interfaces and objects. Entries for interchangeable server instances may be organised as a group, and clients may begin their binding searches at the group entry.

The Service-Oriented Model

In the service-oriented model, clients are interested in some service, as defined by an interface (and its versions). The interface may be exported by more than one server, and server entries for servers that export a given interface may be organised in the same group. However, client applications seeking services normally do not have knowledge of the local namespace that will lead them directly to the required group entry. Typically, such clients use profiles to find the local instantiations of services they want.

The Object-Oriented Model

In the object-oriented model, a server associates some resource that it offers with an object UUID. Several servers may offer the same interface but different objects. Each server then exports the object UUIDs it offers to one or more separate server entries.

In order to make object UUIDs available to clients seeking a specific object, servers offering an object typically export object UUIDs to a group entry for that object. The group entry name is thus effectively associated with the object. Clients seeking a specific object can begin by importing an object UUID from the group entry for the object. The client then imports bindings for the object and interface it wants, beginning its search with the object entry.

Servers that export object UUIDs may or may not explicitly map these to type managers. In the simplest case, the server only registers an interface with a nil type UUID, causing all calls on the interface to be handled by the default manager. In this case, the association between object UUID and resource exists only in the namespace, and the server must assume that a client interested in a given object has, in fact, imported its binding correctly. On the other hand, servers may use object/type mappings to dispatch calls precisely according to object UUID. (See Binding Steps for the details of the mappings and selection algorithm.)

Security

The RPC API provides a small number of interfaces that applications can use to set the authentication and authorisation services and the protection levels used by remote procedure calls. Servers that want to use authenticated RPC register a set of server principal name/authentication service pairs with the run-time system. To make an authenticated call, a client associates security information with a binding on which it is going to call, including a server principal name and authentication, authorisation and protection-level information.

Once the required authentication state is set, authentication and protection are carried out transparently by the RPC run-time system, using the specified services. If the server principal name and authentication service specified by the client do not match a pair registered by the server, the call fails. A server can specify a non-default authentication key retrieval function, but is not otherwise required (or allowed) to implement any of the authentication mechanism.

If the authentication requested is successful, the server manager routine can retrieve the caller's authentication, authorisation and protection-level information from the run-time system. Since the server may have registered more than one principal name/authentication service pair, the application code may still want to make an authentication decision at this point.

The server manager code also makes authorisation decisions based on the authorisation information it retrieves from the run-time system. The server is free to use this authorisation information to make whatever authorisation decisions are appropriate for the application.

The RPC security-related API is designed to be independent of any specific authentication and authorisation services. Servers and clients specify the required services via parameters to the authentication-related calls. The run-time system carries out authentication using the requested authentication service, passes authorisation service-specific authorisation information with the call, and provides protection that corresponds (in a service specific way) to the requested protection level. Supported values for the authorisation, authentication and protection-level parameters are specified in Authentication, Authorisation and Protection-level Arguments .

Internationalisation Support Model

The RPC API provides a number of routines that support internationalized applications by enabling character and code set interoperability, which permits clients and servers to transfer international character data in a heterogeneous character set and code sets environment. Interoperability is achieved by the appropriate implementation of character and code set evaluation and conversion.

A locale defines the subset of a user's environment that depends upon language and cultural conventions and determines, among other things, the character sets and code sets used in that environment. (Locale definition functions are specific to operating systems.) A character set is a group of characters such as the American English alphabet or Japanese Kanji; a given locale generally defines one primary character set. A code set is a mapping of the members of a character set to specific numeric code values; examples include ASCII, JIS X0208 (Japanese Kanji), and ISO 8859-1 (Latin 1). The same character set can be encoded in different code sets; consequently, clients and servers may use the same character set but represent that character set in different numeric encodings.

Distributed applications running in a network of heterogeneous operating systems need to be able to identify the character sets and code sets in use by clients and servers in order to accurately transfer data between them. DCE RPC, through the NDR transfer syntax, supports automatic conversion of characters that are included in the Portable Character Set (PCS) and are encoded in the ASCII and EBCDIC code sets. RPC protocol requires all clients and servers to support the PCS; the IDL base type specifiers char and idl_char identify the included characters. The RPC run-time system transparently converts such characters, if necessary, when they are passed between client and server. (See Portable Character Set .)

International character data consist of characters that are not part of the PCS and the ASCII or EBCDIC code sets. Applications that must transfer international characters can use the provided IDL constructs and RPC routines to achieve accurate and reliable character and code set conversion. For example, such an application might handle European, Chinese, or Japanese characters mapped to ISO 8859-4 (Latin 4), Big5, or SJIS encodings.

The code set registry allows the internationalisation support routines to uniquely identify the code sets they encounter by assigning a unique identifier to each code set. Because the registry's code set identifiers are consistent across the network, applications need not rely on operating system-specific string names. The code set data structure contains a 32-bit hexadecimal value (c_set) that uniquely identifies the code set, followed by a 16-bit decimal value (c_max_bytes) that indicates the maximum number of bytes the code set uses to encode a single character.

A code sets array contains the list of the code sets that a client or server supports. The first element in the code sets array represents the code set in use in the client or server's local environment. The second element through nth elements represent one or more intermediate code sets that can be used to transmit international character data over the network. Applications can convert data into such an intermediate code set when their host does not provide a converter for the remote local code set but does provide a converter for the intermediate code set. All of the internationalisation support routines support one intermediate code set, the ISO 10646 Universal character/code set. Consequently, DCE requires host systems running applications that transfer international characters to provide converters for this code set. The csrc utility can be used to designate other intermediate code sets to be used in preference to ISO 10646. The remaining elements in the array represent other code sets that the application's host supports.

Client and server applications converting international character data must perform the following tasks in addition to those required for other RPC applications:

For a list of the RPC API routines supporting internationalisation, see Internationalisation Support Operations . For information about the ACS attributes on which internationalization support depends, see International Character Transfer .

Note:
Applications running under operating systems that do not provide POSIX-compliant iconv code set conversion routines must provide their own implementations of the required conversion and buffer sizing routines-that is, the equivalents to the _to_netcs, _from_netcs, _net_size and _local_size routines described in Internationalisation Support Operations .

Error Handling

The RPC API provides a consistent error handling mechanism for all routines. Each routine includes a status output argument, which is used to return error status codes. These codes may be passed to the dce_error_inq_text() routine to extract error message text from a message catalogue. (See tagmref_dce_error_inq_text .)

RPC calls return protocol and run-time error status codes through fault_status and comm_status parameters, as described in Interface Definition Language . These status codes are consistent with the status codes returned from the RPC API and may be passed to dce_error_inq_text() to obtain error message text.

The status codes documented in this document must be supported by all implementations. Implementations may support additional status codes, but these are not required.

Cancel Notification

RPC provides a remote cancel notification mechanism that can forward asynchronous cancel notifications to servers. When a client thread receives a cancel notification during an RPC, the run-time environment forwards the notification to the server. When the server run-time system receives the forwarded notification, it attempts to notify the server application thread that is handling the call. This can result in one of three outcomes for the RPC call on the client side:

  1. If the notification is delivered to and handled by the server application thread, the RPC returns normally to the client.

  2. If the server run-time system is unable to deliver the notification to the server application thread (for example, because the server application is blocking notifications), the notification is returned to the client run-time system. The RPC returns normally to the client, and the client run-time system attempts to deliver the notification to the client application thread. The client application code may then handle the notification.

  3. If the notification is delivered to the server application thread, but the server application code fails to handle it, the RPC returns to the client with a fault status.

Client applications may want to avoid waiting an indeterminate amount of time before a cancelled call returns. The RPC mechanism therefore allows client applications to specify a cancel time-out period. If a cancel occurs during an RPC, and the cancel time-out period expires before the call returns, the call returns to the client with a fault status. Such a call is said to be orphaned at the server. An orphaned call may continue to execute in the server, but it cannot return to the client.

Stubs

While stubs are generally transparent to the application code, applications may need to be aware of certain stub characteristics:

This version of this document specifies C-language stub bindings only.

IDL to Stub Data Type Mappings

Stubs generated from the IDL specification of an interface contain language-specific bindings for the interface operations. Client calls to remote procedures, and the server operations that implement these procedures, must conform to the bindings defined by the stubs. Therefore, applications must be aware of the mappings from the IDL data types that appear in an interface specification to the data types that appear in the stub declarations.

The C-language mappings are specified in IDL to C-language Mappings . As specified there, stubs use defined types rather than primitive C-language types in declarations. Applications should use these defined types to ensure that their type declarations are consistent with those of the stubs, even when the application is ported.

Manager EPVs

Stubs may contain a default manager EPV as described in RPC Data Types Applications that declare additional nondefault manager EPVs must avoid the default name.

Interface Handles

Each stub declares an interface handle, which is a reference to interface specific information that is required by certain RPC APIs. (See RPC Data Types for an explanation of how applications can access the declared interface handle.)

Stub Memory Management

RPC attempts to extend local procedure call parameter memory management semantics to a situation in which the calling and called procedure no longer share the same memory space. In effect, parameter memory has to be allocated twice, once on the client side, once on the server side. Stubs do as much of the extra allocation work as possible so that the complexities of parameter allocation are transparent to applications. In some cases, however, applications may have to manage parameter memory in a way that differs from the usual local procedure call semantics. This typically occurs in applications that pass pointer parameters that change value during the course of the call. Detailed rules for stub memory management by applications are given in Stubs and Parameter Memory Management .

RPC API Routine Taxonomy

The following sections summarise the RPC API routines, classifying them according to the kinds of functions they perform.

Note:
Implementations of the RPC API must be synchronous cancel-safe (in the context of POSIX threads). Implementations of the RPC API need not be asynchronous cancel-safe. Multi-threaded implementations must be thread-safe.

Binding Operations

The routines in this group manipulate binding information. Most of these routines use binding handle parameters to refer to the underlying binding information. The string binding routines provide a way to manipulate binding information directly in string format.

A number of routines from the Object Operations and the Authentication and Authorisation groups also manipulate the information referenced by binding handles.

rpc_binding_copy()
Returns a binding handle that references a new copy of binding information.

rpc_binding_free()
Releases a binding handle and referenced binding information resources.

rpc_binding_from_string_binding()
Returns a binding handle from a string representation of a binding handle.

rpc_binding_reset()
Resets a server binding so the host remains specified, but the server instance on that host is unspecified.

rpc_binding_server_from_client()
Converts a client binding handle to a server binding handle.

rpc_binding_to_string_binding()
Returns a string representation of a binding handle.

rpc_binding_vector_free()
Frees the memory used to store a vector of binding handles and the referenced binding information.

rpc_server_inq_bindings()
Returns binding handles for RPC communications.

rpc_string_binding_compose()
Combines the components of a string binding into a string binding.

rpc_string_binding_parse()
Returns, as separate strings, the components of a string binding.

Interface Operations

The routines in this group manipulate interface information. Many of these routines take interface handle arguments. These handles are declared by stubs to reference the stubs' interface specifications. The routine rpc_server_register_if() is used to establish a server's mapping of interface identifiers, type UUIDs and manager EPVs. The routine rpc_if_inq_id() can be used to return the interface identifier (interface UUID and version numbers) from an interface specification.

rpc_if_id_vector_free()
Frees the memory used to store a vector and the interface identifier structures it contains.

rpc_if_inq_id()
Returns the interface identifier for an interface specification.

rpc_server_inq_if()
Returns the manager entry point vector registered for an interface.

rpc_server_register_if()
Registers an interface with the RPC run-time system.

rpc_server_unregister_if()
Unregisters an interface from the RPC run-time system.

Protocol Sequence Operations

The routines in this group deal with protocol sequences. The various server_use* routines are used by servers to tell the run-time system which protocol sequences to use to receive remote procedure calls. After calling one of these routines, the server calls rpc_server_inq_bindings() to get binding handles for all the protocol sequences on which it is listening for calls.

rpc_network_inq_protseqs()
Returns all protocol sequences supported by both the RPC run-time system and the operating system.

rpc_network_is_protseq_valid()
Tells whether the specified protocol sequence is valid and supported by both the RPC run-time system and the operating system.

rpc_protseq_vector_free()
Frees the memory used by a vector and its protocol sequences.

rpc_server_use_all_protseqs()
Tells the RPC run-time system to use all supported protocol sequences for receiving remote procedure calls.

rpc_server_use_all_protseqs_if()
Tells the RPC run-time system to use all the protocol sequences and endpoints specified in the interface specification for receiving remote procedure calls.

rpc_server_use_protseq()
Tells the RPC run-time system to use the specified protocol sequence for receiving remote procedure calls.

rpc_server_use_protseq_ep()
Tells the RPC run-time system to use the specified protocol sequence combined with the specified endpoint for receiving remote procedure calls.

rpc_server_use_protseq_if()
Tells the RPC run-time system to use the specified protocol sequence combined with the endpoints in the specified interface specification for receiving remote procedure calls.

Local Endpoint Operations

The routines in this group manipulate information in an application host's local endpoint map. These include the routines that servers typically use to register and unregister their binding information in the local endpoint map. A set of endpoint management routines is also available for more general manipulation of local and remote endpoint maps.

rpc_ep_register()
Adds to, or replaces, server address information in the local endpoint map.

rpc_ep_register_no_replace()
Adds to server address information in the local endpoint map.

rpc_ep_resolve_binding()
Resolves a partially bound server binding handle into a fully bound server binding handle.

rpc_ep_unregister()
Removes server address information from the local endpoint map.

Object Operations

The routines in this group manipulate object related information. Servers use rpc_object_set_type() to establish their object UUID/type UUID mappings. Clients typically specify the object UUID they wish to associate with a binding when they import bindings from a name service. However, clients can use rpc_binding_set_object() to associate a different object UUID with a binding. Servers can use rpc_object_set_inq_fn() to establish private object UUID/type UUID mappings.

rpc_object_inq_type()
Returns the type of an object.

rpc_object_set_inq_fn()
Registers an object inquiry function.

rpc_object_set_type()
Assigns the type of an object.

rpc_binding_inq_object()
Returns the object UUID from a binding handle.

rpc_binding_set_object()
Sets the object UUID value into a server binding handle.

Name Service Interface Operations

The routines of this group constitute most of the RPC name service independent interface (NSI). A group of name service management routines is also available. The NSI routines are divided into several subcategories according to groups of functions.

NSI Binding Operations

Applications use the routines in this subgroup to the export and import bindings to and from name service server entries. These include two suites of begin/next/done routines that applications can use to import bindings, as well as three routines for manipulating protocol towers.

rpc_ns_binding_export()
Exports server binding information to a name service entry.

rpc_ns_binding_import_begin()
Creates an import context for importing bindings from a name service.

rpc_ns_binding_import_done()
Deletes a name service import context.

rpc_ns_binding_import_next()
Returns a binding handle for a compatible server from a name service.

rpc_ns_binding_inq_entry_name()
Returns the name of an entry in the name service database from which the binding information referenced by a server binding handle came.

rpc_ns_binding_lookup_begin()
Creates a lookup context for importing bindings from a name service.

rpc_ns_binding_lookup_done()
Deletes a name service lookup context.

rpc_ns_binding_lookup_next()
Returns a vector of binding handles for compatible bindings from a name service.

rpc_ns_binding_select()
Returns a binding handle from a vector of compatible server binding handles.

rpc_ns_binding_unexport()
Removes binding information from an entry in a name service database.

rpc_tower_to_binding()
Returns a binding handle from a protocol tower representation.

rpc_tower_vector_free()
Releases memory associated with a protocol tower vector.

rpc_tower_vector_from_binding()
Creates a protocol tower vector from a binding handle.

NSI Entry Operations

Applications use the routines in this group to return information about name service entries of various types.

rpc_ns_entry_expand_name()
Expands the name of a name service entry.

rpc_ns_entry_inq_resolution()
Resolves the cell namespace components of a name service entry and returns partial results.

rpc_ns_entry_object_inq_begin()
Creates an inquiry context for viewing the objects stored in an entry in a name service database.

rpc_ns_entry_object_inq_done()
Deletes a name service object inquiry context.

rpc_ns_entry_object_inq_next()
Returns an object stored in an entry in a name service database.

NSI Group Operations

Applications use the routines in this group to manipulate name service group entries.

rpc_ns_group_delete()
Deletes a group attribute.

rpc_ns_group_mbr_add()
Adds an entry name to a group; if necessary, creates the entry.

rpc_ns_group_mbr_inq_begin()
Creates an inquiry context for viewing group members.

rpc_ns_group_mbr_inq_done()
Deletes the inquiry context for a group.

rpc_ns_group_mbr_inq_next()
Returns a member name from a group.

rpc_ns_group_mbr_remove()
Removes an entry name from a group.

NSI Profile Operations

Applications use the routines in this group to manipulate name service profile entries.

rpc_ns_profile_delete()
Deletes a profile attribute.

rpc_ns_profile_elt_add()
Adds an element to a profile; if necessary, creates the entry.

rpc_ns_profile_elt_inq_begin()
Creates an inquiry context for viewing the elements in a profile.

rpc_ns_profile_elt_inq_done()
Deletes the inquiry context for a profile.

rpc_ns_profile_elt_inq_next()
Returns an element from a profile.

rpc_ns_profile_elt_remove()
Removes an element from a profile.

Authentication Operations

Applications use the routines in this group to manipulate the authentication, authorisation and protection-level information used by authenticated remote procedure calls.

rpc_binding_inq_auth_caller()
Returns authentication and authorisation information referenced by a client binding handle.

rpc_binding_inq_auth_info()
Returns authentication information referenced by a server binding handle.

rpc_binding_set_auth_info()
Sets authentication information referenced by a server binding handle.

rpc_server_register_auth_info()
Registers authentication information with the RPC run-time system.

rpc_ss_bind_authn_client()
Authenticates a client's identity to a server from a client stub.

Internationalisation Support Operations

Applications use the routines in this group to implement character and code set interoperability, which permits clients and servers to transfer international character data in a heterogeneous character set and code sets environment.

Note:
Rather than being alphabetical, the following list of routines is ordered to correspond to the discussion of the internationalisation support model in Internationalisation Support Model .

rpc_rgy_get_codesets()
Obtains supported code sets information from the local host.

rpc_ns_mgmt_set_attribute()
Adds an attribute to a server entry in the name service database.

rpc_ns_mgmt_remove_attribute()
Removes an attribute from a server entry in the name service database.

rpc_ns_import_ctx_add_eval()
Adds a code set evaluation routine to an import context.

rpc_ns_mgmt_read_codesets()
Reads the code sets attribute associated lith a server entry in the name service database.

rpc_ns_mgmt_free_codesets()
Frees a code sets array that has been allocated by the run-time system.

dce_cs_loc_to_rgy()
Maps a local code set name to a code set value in the code set registry.

dce_cs_rgy_to_loc()
Maps a code set value in the code set registry to the local code set name.

rpc_cs_eval_with_universal(), rpc_cs_eval_without_universal()

Evaluate a server's supported code sets during the server binding selection process.

rpc_cs_char_set_compat_check()
Evaluates character set compatibility between a client and a server.

rpc_cs_binding_set_tags()
Places code set tags into a server binding handle.

rpc_cs_get_tags()
Retrieves code set tags from a binding handle.

rpc_rgy_get_max_bytes()
Obtains the maximum number of encoding bytes used by a code set from the code set registry on a host.

cs_byte_local_size(), wchar_t_local_size()

Calculate the necessary buffer size for conversion of international character data from a network code set to a local code set.

cs_byte_from_netcs(), wchar_t_from_netcs()

Convert international character data from a network code set to a local code set.

cs_byte_net_size(), wchar_t_net_size()

Calculate the necessary buffer size for conversion of international character data from a local code set to a network code set.

cs_byte_to_netcs(), wchar_t_to_netcs()

Convert international character data from a local code set to a network code set.

The Server Listen Operation

This routine performs the final step in server initialisation, causing the server to begin to listen for remote procedure calls.

rpc_server_listen()
Tells the RPC run-time system to listen for remote procedure calls.

The String Free Operation

Applications use this routine to free the string memory allocated by RPC API routines that return strings.

rpc_string_free()
Frees a character string allocated by the run-time system.

UUID Operations

The routines in this group manipulate UUIDs.

uuid_compare()
Compares two UUIDs and determines their order.

uuid_create()
Creates a new UUID.

uuid_create_nil()
Creates a nil UUID.

uuid_equal()
Determines if two UUIDs are equal.

uuid_from_string()
Converts a string UUID to binary representation.

uuid_hash()
Creates a hash value for a UUID.

uuid_is_nil()
Determines if a UUID is nil.

uuid_to_string()
Converts a UUID from binary representation to a string representation.

Stub Memory Management

The routines in this group enable applications to participate in stub memory management.

rpc_sm_allocate()
Allocates memory within the RPC stub memory management scheme.

rpc_sm_client_free()
Frees memory allocated by the current memory allocation and freeing mechanism used by the client stubs.

rpc_sm_destroy_client_context()
Reclaims the client memory resources for a context handle, and sets the context handle to NULL.

rpc_sm_disable_allocate()
Releases resources and allocated memory within the RPC stub memory management scheme.

rpc_sm_enable_allocate()
Enables the stub memory management environment.

rpc_sm_free()
Frees memory allocated by the rpc_sm_allocate() routine.

rpc_sm_get_thread_handle()
Gets a thread handle for the stub memory management environment.

rpc_sm_set_client_alloc_free()
Sets the memory allocation and freeing mechanism used by the client stubs.

rpc_sm_set_thread_handle()
Sets a thread handle for the stub memory management environment.

rpc_sm_swap_client_alloc_free()
Exchanges the current memory allocation and freeing mechanism used by the client stubs with one supplied by the client.

Endpoint Management Operations

The routines in this group provide a more general interface for manipulating endpoint maps than the one provided by the Local Endpoint Operations group. Routines in this group allow the examination of endpoint map elements one at a time and permit operations both on the application host's local endpoint map and on remote endpoint maps. These are considered management operations because of their potential to affect applications other than the one making the management call.

rpc_mgmt_ep_elt_inq_begin()
Creates an inquiry context for viewing the elements in a local or remote endpoint map.

rpc_mgmt_ep_elt_inq_done()
Deletes the inquiry context for viewing the elements in a local or remote endpoint map.

rpc_mgmt_ep_elt_inq_next()
Returns one element at a time from a local or remote endpoint map.

rpc_mgmt_ep_unregister()
Removes server address information from a local or remote endpoint map.

Name Service Management Operations

The routines in this group carry out operations typically done by name service management applications or only infrequently done by most applications. These are considered management operations because of their potential to affect applications other than the one making the management call.

rpc_ns_mgmt_binding_unexport()
Removes multiple binding handles, or object UUIDs, from an entry in a name service database.

rpc_ns_mgmt_entry_create()
Creates an entry in a name service database.

rpc_ns_mgmt_entry_delete()
Deletes an entry from a name service database.

rpc_ns_mgmt_entry_inq_if_ids()
Returns the list of interfaces exported to an entry in a name service database.

rpc_ns_mgmt_handle_set_exp_age()
Sets a handle's expiration age for cached copies of name service data.

rpc_ns_mgmt_inq_exp_age()
Returns an application's global expiration age for cached copies of name service data.

rpc_ns_mgmt_set_exp_age()
Modifies the application's global expiration age for cached copies of name service data.

Local Management Services

The routines in this group provide a set of miscellaneous local operations that servers and clients can use to manage their RPC interactions.

rpc_mgmt_inq_com_timeout()
Returns the communications time-out value referenced by a binding handle.

rpc_mgmt_set_authorization_fn()
Establishes an authorisation function for processing remote calls to a server's management routines.

rpc_mgmt_set_cancel_timeout()
Sets the lower bound on the time to wait before timing out after forwarding a cancel.

rpc_mgmt_set_com_timeout()
Sets the communications time-out value referenced by a binding handle.

rpc_mgmt_set_server_stack_size()
Specifies the stack size for each server thread.

rpc_mgmt_stats_vector_free()
Frees a statistics vector.

rpc_mgmt_inq_dflt_protect_level()
Returns the default protection level for an authentication service.

Local/Remote Management Services

Applications can use the routines in this group to query and stop servers remotely. Servers can also use these operations to query and stop themselves.

rpc_mgmt_inq_if_ids()
Returns a vector of interface identifiers of the interfaces a server offers.

rpc_mgmt_inq_server_princ_name()
Returns a server's principal name.

rpc_mgmt_inq_stats()
Returns RPC run-time statistics.

rpc_mgmt_is_server_listening()
Tells whether a server is listening for remote procedure calls.

rpc_mgmt_stop_server_listening()
Tells a server to stop listening for remote procedure calls.

Error Messages

The dce_error_inq_text() routine provides a locale-independent way to get error message text for a status code returned by an RPC API routine. Because this routine is not RPC-specific, it is documented in The dce_error_inq_text Manual Page rather than being included with the RPC API manual pages.


Please note that the html version of this specification may contain formatting aberrations. The definitive version is available as an electronic publication on CD-ROM from The Open Group.

Contents Next section Index