IBM Person to Person: application programming interface overview This document provides an overview of the Person-to-Person application programming interface architecture. There is no implication that all of the features described in this architecture will be implemented in a future release. Introduction ____________ Personal computers are now widespread throughout the business community and many are able to intercommunicate, either through fixed connections e.g. local area networks, or through dynamically established links e.g. ISDN or async lines over the public switched telephone network. Increasingly, these connected personal computers can be used to enhance collaborative working between remote individuals; a typical example being the use of desk top conferencing software. Successful collaborative work generally requires more than a simple data link between the participants; voice capabilities are normally essential and video links are frequently required. Thus remote collaborative working can often be regarded as an extension to the traditional telephone call - it being enhanced with the data and programs available at the desktop via the personal computer - and, on occasions, enriched with video services. A broad spectrum of collaborative applications can be written, ranging from utilities taking advantage of the data and applications on a workstations, e.g. sharing of application windows, through to new collaborative applications designed to meet the needs of specific classes of remote user e.g. help desk. The common requirements behind these examples are: * support of a wide variety of personal computer platforms - both hardware and software. * operation over the existing communication networks. * group communications and multi-media data services. Five important interfaces exist in the Person-to-Person (P2P) architecture: * The application programming interface allows applications to request P2P services. * The device driver interface allows P2P to support an extensible range of software and hardware communications sub-systems. * The resources interface through which P2P requests details of the communications network, such as node addresses and directory data. * The P2P data stream, which is the information transmitted over the physical network, as a consequence of application calls through the API. * The command level interface, which gives access to call manager and application functions. The P2P architecture offers these capabilities: * applications can start the execution of other local and remote applications, and then share their combined resources. * applications can define logical communications channels between themselves, suitable for a broad range of multi-media traffic, independently of the underlying physical communications network. * communications traffic may be: * serialised so that the same data sequence is received by all applications. * synchronised with other communications traffic. * merged so that multiple sources of data can be combined. * copied to multiple destinations. * a range of attached workstation devices are supported to allow the interception and redirection of data, both from devices and from other applications. Major elements of the Person-to-Person API model ________________________________________________ Network, nodes and applications =============================== At the highest level, the architectural model is a communicating set of nodes. A node is a computer, typically a workstation capable of communicating with its peers. A P2P node is one where the P2P software support is being executed. A collection of inter- communicating P2P nodes is a P2P network. It is fundamental to the architecture that a node can dynamically join or leave the network. Nodes can have associated devices. A device is a piece of equipment, a computer or a program that is communicating with a P2P node but is not running the P2P software. Devices are normally controlled by their P2P node and frequently supply or receive data to/from that node. There is an extensive range of possible P2P devices including: printers, disk drives, modems, codecs, multi-point control units and application programs. Multiple applications can be executed at a P2P node, subject to the constraints imposed there by the operating system and windowing system. Applications are either aware or unaware; an aware application uses the services of the P2P API. When P2P is active at a node one particular aware application must be running there. This application plays a unique role at that node and is known as the call manager. Many call managers may be available for execution at a particular node but only one can execute at a time. The distinguishing feature of the call manager is that it handles resource management for the node and resolves any requests that are not directed specifically at an instance of an application. Call manager responsibility can be passed from one call manager to another; also the role can be subsumed into an arbitrary P2P application if that is appropriate. Aware applications can share data and resources with other aware applications at the same or different nodes. The application initiates a share request, which is processed at the destination node. The call manager there can accept, reject or transfer the request; accept means that the call manager will handle the sharing itself, eitheter directly or by launching an application, or by sharing with an existing instance of an application; transfer means that it will transfer the request to a remote call manager. This sharing mechanism can be cascaded, such that if two applications are already sharing, one of them can initiate a share with a third application. The consequence of this is that all three applications are then sharing with each other. Applications may make share requests on behalf of other applications. A named collection of applications sharing is called a sharing set. Applications can cease sharing at any time. Communications, channels and ports ================================== Applications in a sharing set can establish data communication links with each other known as channels. Channels are logically dedicated and uni-directional. A channel is always defined by the sending application and it goes from the sending application to one or more receiving applications. The ends of channels are known as ports. A sending port sends data down the channel; a receiving port receives data from the channel. There is no direct mapping between the logical channel structure seen by the aware applications and the physical communication network in existence between the nodes. An application may establish many channels to another application as a convenient way to communicate different kinds of data. P2P may map some or all of the logical channels on to a single physical link but this will be invisible to the application. Channels have a number of quality of service characteristics which are negotiated during the creation process to allow data transmission capabilities to be tailored to the expected traffic; these include throughput, latency, jitter and other parameter. These mechanisms allow suitable video channels, voice channels and other specialised data channels to be established. Four types of channel are supported: standard, merged, synchronous and serialised. Standard channels are the default case; the other types describe the properties of collections of channels known as channel sets. Through a merged channel set data is combined from multiple channels and delivered to an application through a single port at each destination. Through a serialising channel set data is combined from different channels, serialised, and delivered to each application such that each receiving port sees the same sequence of data. Through a synchronising channel set data is synchronised, so that data on separate channels is tied together in time (as is required for the synchronisation of voice and video), but delivered through the individual ports belonging to the channels. Ports can be connected together to establish extended communication links, so that an application may route its inputs through to another application for processing. When ports are connected in this way no further application involvement is required after the routing has been established. This allows the streaming of data between applications and devices. Connected ports can also be welded, so that the connection is permanent and persists even when the local application has terminated. Event, command and null ports are provided; event ports generate an event when data is either available or is required; command ports read or write data to/from a buffer, and the application has the responsibility of filling or emptying this buffer; null ports are a special case reserved for ports that are unable to supply data. Ports can be controlled through commands sent to the port event handler, for example, rewind or pause to a tape drive. An alternative method of application inter-communication, avoiding the use of ports and channels, is provided for application control data. One characteristic of ports is that they are associated with a data class and compression hints. The data class describes the kind of data, e.g. voice, video, file, interactive, that is sent by a sending port down the channel, or to be received via a receiving port. Compression hints allow data compression during transmission, without impacting applications. Devices ======= Devices are supported by the P2P architecture; these include: disk drive, system clipboard, telephone, audio, video, printer and window; further devices may be defined. Devices can be opened by an application; the process of opening a device creates a port to or from that device. A device may be opened more than once to have multiple ports if appropriate; thus a disk drive device can have both a sending and a receiving port. Resource management =================== Collaborative working frequently requires that resources owned by a node, for example a printer device, can be shared with other nodes. Such resources are considered to be global resources and access is controlled through global tokens. Other resources are owned by application, for example a shared pointer, and access to these is managed through application tokens. Applications are expected to know the location of a globally available resource that they require, and therefore facilities for the broadcasting of availability information are not provided. Instead, the call manager at the node with the global resource is responsible for resource management. Global tokens may be held by an application instance on an exclusive or shared basis; token ownership may not be transferred. Requests for a global token may be queued, with the queue being held above the API and managed by the node call manager. Access to global tokens is not restricted to a sharing application set. Management of application resources may be performed by any application in the sharing set. Application tokens may be held on an exclusive or shared basis and requests for tokens queued, with the queue being held above the API, and managed by the current application token owner. Other networks ============== Private analogue networks ------------------------- The P2P architecture supports analogue communications in a very similar way to digital communications, in those situations where: * analogue links exist between P2P nodes. * connectivity and routing at each node can be controlled by P2P at that node. * a digital control channel exists between the nodes. Analogue channels are logically dedicated uni-directional communication links established by the sending application, and they may terminate in more than one receiving application. They may be distinguished from digital channels by their data class. Only standard or merged channels may be established; serialising and synchronising channel sets are not permitted. Devices can present analogue ports when opened; thus a video player device can be used as a source of analogue video and may be connected to an analogue channel through a P2P command. The direct connection of analogue and digital channels is not permitted; however certain devices e.g. a codec device provide both analogue and digital ports when opened and can be used to effect such a coupling. Switched digital networks ------------------------- Switched digital networks can be used by P2P for inter-node communication without exposing the switched nature of the connection. Equipment, such as digital telephones, attached to a switched network, are accessed by applications as P2P devices. Thus an ISDN phone device may be opened to present receiving and sending ports, with an associated event or command connect type; dialling, and other control functions, are implemented through port commands. Third party connection between digital telephone equipment is similarly affected through commands to an appropriate device; this may be physically implented through commands to the local switch. Public switched analogue networks --------------------------------- Analogue telephones and other equipment, attached to the public switched network, are controlled by applications through P2P devices. A PSTN telephone can be opened to present a P2P port, with a null connect type i.e. it cannot supply or receive data from a P2P application. Port commands are used to control the device. First party connection can be implemented through a modem injecting dialling tones into the local line; third party connection, and multi-way calls through commands to the local switch. The functionality of the IBM CallPath services architecture will be made available, where appropriate, through P2P, for call centre and related applications Interfacing to P2P-unaware applications ======================================= The P2P architecture provides facilities which allow unaware applications to be used for collaborative working. A P2P-aware application supplies the user interface dialogue and interacts with the particular unaware application via Lakes devices. This same aware application then communicates with a related aware application at the remote node to pass the information to the remote user. Other facilities ================ User exits and function hooks are provided to ease programming and debugging. All ports can be associated with a user exit to monitor data traffic or process data. All functions, including calls and events, can be hooked and passed to an application supplied event handler. Additionally, a full set of queries are provided, so that applications need not keep track of status at their node, nor of the applications being shared. Application program debugging is assisted through allowing collaborative applications to be shared at a single node; thus avoiding physical networks being involved during initial program development. Application development ======================= The architecture helps collaborative application development and encourages inter- working through: * an application programming interface providing group communications, data transmission and streaming, and application sharing; independently of the underlying system platforms or communication network. * pre-defined devices to allow easy access to data sources and destinations; these also simplify interfacing to existing unaware applications. * data stream support: * self-identifying, industry standard data streams. * new architected data streams for keystrokes, pointers, window updates, DDE and clipboard. Standards ========= The P2P architecture is designed to: * maximise inter-working between different computer platforms. * operate over varied communications networks. * support relevant communication and data standards. The separation of data traffic into logical uni-directional flows of homogeneous data, simplifies the mapping on to a mixed network and allows the use of multiple physical links, of different capabilities, between the nodes. Data multiplexing is handled below the application and can be implemented in different ways depending upon the underlying transport mechanism. The separate logical data paths, with their associated data types, ease inter-application operation because the data components are presented individually, with their nature and format independently available. Through this mechanism, a wide range of existing standards for voice, video, image, file transfer, and coded data can be supported, with the potential for data conversions in the network. P2P also provides a separate data class for the interactive objects commonly used in collaborative applications, such as remote pointers, cursors and gestures. These are architected so that shared chalkboards, editors and similar applications can inter-operate, even though provided by different manufacturers. Further Information =================== For further information on the P2P architecture, please post to the Person to Person section of IBM PSP Products A Forum (GO IBMP2P).