Developing with P2P Technologies
Windows Vista® provides support for developing P2P applications at every layer.
Multi-Party Communication (Mesh)
Technology / API
P2P Graphing API
Win32® API for creating and managing sets of peer nodes (a graph) and passing data between them
P2P Grouping API
Win32 API that builds upon the Graphing API to add security and multiplexing capabilities
A part of Windows Communication Foundation, this managed API implements the infrastructure for multi-party, peer communications that depend upon the .NET Framework, CLR, TCP/IP, and PNRP
Presence and Session Initiation
Technology / API
A subset of the P2P Collaboration API (Win32) that enables a peer application to create, publish, and subscribe to rich presence information.
A subset of the P2P Collaboration API that enables an application to invite contacts to join a communication session or a multiplayer application, and for that peer to reciprocate.
People Near Me
A subset of the P2P Collaboration API that enables publication and discovery of peers currently on the local network. This information can then be directly used to initiate collaboration activities.
Naming and Discovery
Technology / API
People Near Me
A subset of the P2P Collaboration API that enables publication and discovery of peers currently on the local network. This contact information can then be directly used to initiate collaboration activities.
PNRP Namespace Provider API
A WinSock layered service provider of the PNRP protocol, enabling publication and resolution of peer node information (computer names, user names, and application endpoints) over both local networks and the Internet. This low-level information can be used to initiate contact- or endpoint-based communications.
Simple PNRP API
Win32 API for the publication and resolution of peer node information. This API represents a simplified alternative to using the PNRP Namespace Provider API.
Collaboration Contact API
A subset of the P2P Collaboration API that enables discovery and enumeration of peer contacts.
Identity and Contact Management
Technology / API
Identity Manager API
Win32 API used to create, enumerate, and manipulate peer identities.
Windows Address Book (WAB) API
Win32 API for storing and managing contact information in the Windows Address Book (WAB).
Collaboration Contact APIs for WAB Integration
A subset of the P2P Collaboration API that encapsulates common operations on the WAB.
People Near Me spans the Naming and Discovery, and the Presence and Session Initiation layers.
The following interfaces use different code access technologies, largely reflecting when they were produced within Microsoft:
Peer Channel is a part of the Windows Communication Foundation, which is a .NET Framework 3.0 managed code technology.
The P2P Collaboration API, P2P Graphing, Grouping, Identity Manager APIs, PNRP Namespace Provider, and the Windows Address Book (WAB) API are all standard Win32 APIs. Some of these APIs share concepts with COM, such as the use of HRESULT return values and reference counts.
With the exception of the Windows Address Book and base networking services, you typically will use one set of these P2P technologies in a solution but not both.
P2P Architecture and Concepts
The following diagram depicts the core P2P infrastructure of Windows Vista:
Note several important features of this diagram:
Microsoft TCP/IP using IPv6 acts as the underlying transport. IPv6 is required for some of the multi-homing and network transversal mechanisms that robust P2P communications depend upon.
The Winsock API is used as an API that most of the other core elements are built upon, specifically, the P2P Graphing, Grouping, and PNRP protocol.
Following the WOSA model, the PNRP Namespace Provider API is built upon the PNRP protocol.
The Identity Manger can optionally encrypt identity information to support authentication and authorization requirements.
The PNRP Protocol
PNRP is used primarily to register a service identifier and provide address information for that service. It is used instead of DNS for two primary reasons. First, P2P topologies are typically server-less, so hosting DNS is problematic. Secondly, mesh membership is inherently dynamic, a situation only handled by dynamic DNS, whose population is relatively small.
Winsock 2.0 provides a facility for converting names to addresses via the use of namespace providers. Various namespaces can be supported, and different providers can exist, each of which can resolve names either for the same namespace or different namespaces. The PNRP Namespace Provider enables PNRP to be used in the same way as other name resolution protocols. This provider runs as a user-mode service that uses RPC to pass information between the service and the calling application. If the application process terminates unexpectedly, the PNRP service detects the RPC session shutdown, and cleans up any state it has on behalf of the application.
PNRP divides networks into multiple clouds, which is an area of the network over which IP addresses are unique (generally called an IP scope). The following clouds are defined:
Global Cloud — corresponds to the global IPv6 address scope and represents all the computers on the entire IPv6 Internet. There is only a single global cloud.
Site-specific Cloud — a site is a portion of an organization network that has defined geographical or topological boundaries. There can be multiple site-specific clouds.
Link-local Cloud — corresponds to a specific link, typically the same as the locally attached subnet. There can be multiple link-local clouds.
For PNRP, an endpoint is defined to be an IPv6 address and port that can be used for communication. It is assumed that computers will have an IPv6 TCP/IP stack running and configured. A computer may be part of an IPv4 network. In this case PNRP will use the tunneling support provided by the IPv6 stack. Some attempt is made to encapsulate the IPv6 address structure to allow for other address types in the future.
Each application that wants to register a name with PNRP must have a peer identity. An identity is created using the Identity Manager. The Identity Manager will safely maintain a public and private key pair for an identity, and may also store certificates for an identity.
When an identity is created, a peer name for the identity is returned to the application. Part of the peer name is a hash of the public key as a hexadecimal string. This hash is called the authority. The application may generate additional peer names based on the identity by specifying additional classifier strings. The classifier strings are appended to the authority to generate additional peer names that are associated with the identity and its keys.
Peer Names and PNRP IDs
A peer name is a string used to identify a peer resource. PNRP provides a mechanism for making a peer resource discoverable by registering a peer name, and it provides a mechanism for resolving a peer name to a set of IP addresses and a port.
There are two types of peer names:
A secure peer name has a verifiable relationship to a public key. This provides a proof of ownership of the name. In order to prove ownership, a node must have access to the private key associated with the public key used to create the secure peer name.
An unsecured peer name does not have a relationship to a public key. Any node can claim ownership to any unsecured peer name.
PNRP IDs (also called peer IDs) are used to quickly identify nodes, endpoints, and other resources on the peer network. These IDs are 32 bytes long. The upper 16 bytes contain a hash of the peer name. The lower 16 bytes are used for the service location, a generated number that uniquely identifies different instances of the same P2P ID in the same cloud. IDs and their associated peer names are stored in a distributed hash table that resides among the peer nodes in a cloud.
In a peer environment, there are no centralized servers with security databases that can provide typical security services such as authentication and authorization. In a server-less peer environment, the peers must provide their own authentication. For Windows P2P networking, authentication is provided using self-signed certificates, some of which are formatted as X.509 certificates. Peer networking allows any node to act as a Certification Authority (CA) and removes the requirement for a root CA. Each peer generates the public key/private key pair and the certificate that is signed using the private key. The self-signed certificate is used for authentication and to provide information about the peer entity. Like X.509 authentication, peer networking authentication relies upon a chain of certificates tracing back to a public key that is trusted.
For more information about P2P architecture and concepts, see Introduction to Windows Peer-to-Peer Networking on Microsoft TechNet online.
Windows Address Book (WAB) API
Windows Address Book (WAB) API has been slightly updated in Windows Vista to support the addressbook: protocol. For more information, see Windows Address Book in the Windows SDK. The WAB API has methods to create, retrieve, and display vCard objects. For more information, see the IWABObject Interface in the Windows SDK.
Windows Vista supports the vCards v3.0 specification, which uses an XML storage schema as documented in the Internet RFC 2426.
GetAddrInfo and the Simple PNRP API
Before Windows Vista, PNRP was directly accessible via two mechanisms, the Winsock GetAddrInfo (and related) functions and the PNRP Namespace Provider API (discussed in the next section). While the former is easy to use, it only supports basic peer name discovery and resolution through the following Win32 functions:
Provides protocol-independent translation from host name to address.
Retrieves host information corresponding to a host name from a host database.
Retrieves the standard host name for the local computer.
Provides name resolution from an address to the host name.
Releases address information that the getaddrinfo function dynamically allocates for its addrinfo structures.
In contrast, the PNRP Namespace Provider API provides access to the full capabilities of the PNRP protocol, but is much more complicated and error prone to use. To fill the need for a more powerful intermediate API, Windows Vista introduces the new Simple PNRP API, which is composed of fifteen new functions.
The Simple PNRP API is composed of the following:
The main DLL that contains the Simple PNRP API.
Creates a PeerName based on the existing name of the specified PeerIdentity and Classifier.
Deallocates a block of data and returns it to the memory pool. Used to release data that the Peer-to-Peer Identity Manager, Peer Name Resolution Protocol, Peer Grouping, and Peer Collaboration APIs return.
Converts a PeerName from PeerHostName format to CanonicalFormat according to the rules of PeerHostName encoding.
Converts a PeerName from CanonicalFormat to HostNameFormat.
Retrieve all cloud names.
Used to retrieve endpoints from a previous call to PeerPnrpStartResolve.
Used to register a PNRP endpoint. The infrastructure will dynamically re-register endpoints if their addresses change.
An extended version of PeerPnrpRegister used to handle special cases such as specifying a custom address or payload to register.
Performs a synchronous (blocking) resolve.
Performs a cleanup for PNRP, removing all names that the application registered.
Performs an asynchronous (non-blocking) resolve.
Performs PNRP initialization operations. Also allows applications to determine if PNRP is enabled.
Cancels an in-progress resolve created through a call to PeerPnrpStartResolve.
Removes a PNRP endpoint registration.
Updates a registration of a PNRP endpoint.
The main data structure used to contain a PNRP Endpoint.
It is expected that the Simple PNRP API will make PNRP and IPv6 accessible to a wider audience of P2P application developers by decreasing the complexity of code using PNRP.
P2P Identity Manager, PNRP Namespace Provider, Graphing, and Grouping APIs
These COM-based APIs were first introduced with Windows XP SP2 (actually Windows XP1 with the Advanced Networking Pack for Windows XP). They provide the interface into the core P2P capability of Windows Vista.
The Identity Manager API enables the developer to create, enumerate, and manipulate peer identities. Peer identities are commonly used as input for the Peer-to-Peer Grouping and PNRP Namespace Provider API. Each user can have multiple identities tailored for different P2P activities. For more information, see Identity Manager API in the Windows SDK.
The PNRP Namespace Provider API provides peer-to-peer name discovery and resolution through the PNRP protocol. This API functions as a Winsock 2 Namespace Provider (NSP) and is commonly used to register and deregister a peer name, resolve a peer name, and enumerate clouds. For more information, see PNRP Namespace Provider API in the Windows SDK.
The P2P Graphing API is responsible for creating, opening, closing, deleting, and managing the membership of graphs, which are a set of connected nodes on a network that are used by a single application. Nodes within a graph can share information in the form of records, whose body holds data that is application-specific. In addition, an event infrastructure that allows an application to register and send and receive notice of events that occur within the graph. For more information, see Graphing API in the Windows SDK.
The P2P Grouping API combines the capabilities of the PNRP Namespace Provider API and the Graphing API and extends these with a standard security mechanism and the ability for multiple applications to use the same group concurrently (multiplex). The creator of a group also becomes its administrator, and invites other peers to join the group and maintains the group. The security layer defines the security model behind group creation, invitation, and connection to a group. For more information, see Grouping API in the Windows SDK.
Peer-to-Peer Collaboration API
New to Windows Vista, the P2P Collaboration infrastructure simplifies and enhances the existing P2P infrastructure (Graphing, Grouping, and Identity Manager). Using the Collaboration API, developers can more easily code common P2P capabilities such as: discovering peers on the same network, tracking peer presence, sending invitations to participants, registering and receiving events, and managing contacts. Before Windows Vista introduced the Collaboration API, much of this high-level functionality was only available through the Microsoft Windows Messenger Client API.
When developing with the peer to peer collaboration APIs you may see a tray icon appear when you first use the APIs. This is the user-mode collaboration host process (p2phost.exe). This process is responsible for listening for incoming invitations, and for displaying UI asking the user to authorize the launch of a P2P application. In addition, it allows the user to opt in and out of People Near Me publication.
Architecture and Operation
The P2P collaboration infrastructure is depicted in the following diagram:
In addition to PNRP and TCP/IP, this infrastructure depends on two networking protocols:
Simple Service Discovery Protocol (SSDP) — in Beta 1, SSDP enables network clients to discover and query for network services through multicasting. This protocol may be replaced by a more modern protocol in future versions of Windows Vista.
The Session Initiation Protocol (SIP) — for initiating, modifying, and terminating an interactive user session. SIP supports multimedia content, and on Windows Vista it has been updated to support IPv6.
The following steps are typical in the lifetime of a collaborative application. Some of these steps are event-driven (for example, the issuance of an invitation and the use of peer objects to convey data). Also note that no centralized services are used in this process:
An application, perhaps during setup, registers itself to be launched. For each capability (a set of publicly available software features), a Windows registry entry is created that contains a GUID for the capability, friendly name, description, scope, path to the application, and any application specific data.
The application publishes its presence, including information about its capabilities. The application specifies whether this information should be published to the set of trusted contacts (the default) or to the list of People Near Me.
When the application is run, it creates a list of contacts or endpoints to communicate with. This list can be populated from an internal store, like the WAB, or dynamically discovered using technologies such as People Near Me. For each contact, its presence and capabilities are examined to determine whether it is an appropriate match for the current P2P activity. The current user's Me contact information is stored in the WAB and can be edited only by that person.
The application sends synchronous or asynchronous invitations to the perspective contacts (and/or endpoints). This invitation includes information on the activity that is being requested on the remote user (including an identifying GUID, a message for the receiver, and activity data). When an invite is sent to a contact, invitations are sent to all the associated endpoints.
The invitee receives notification of the invitation through a standard App Invite UI. Assuming the user has the capability installed, after the user accepts or declines the invitation, a response is sent back to the inviter. If the user ignores or dismisses the invitation, then no message is sent back, and, after a period of inactivity on the connection (typically 5-10 minutes), the connection is torn down, and the invitation expires as well.
If not already running, the application is launched and the application and the user exchange information. This can be accomplished through the use of peer objects (run-time data items associated with a particular application) and events, or by using core P2P messaging offered by functions in the P2P Graphing or Grouping APIs.
Using its own internal logic, perhaps with input from the user, the application adds, updates or deletes contacts from the WAB. Because this is a user-wide operation, care must be taken that such actions are generally acceptable.
Using internal logic, such as the absence of users for a certain period of time, the application shuts itself down. If the application is disabled or uninstalled, it also deregisters itself.
The new functionality of the Collaboration API can be logically divided into five functional areas: Common Functions, Collaboration Contact API, Server-less Presence, People Near Me, and Application Invite.
These Win32 functions and Peer Collaboration events are used to manage the Peer Collaboration infrastructure, sign on and off it, and work with events. The functions listed in the next table are in addition to the common core P2P functions for working with enumerations: PeerEndEnumeration, PeerFreeData, PeerGetItemCount, and PeerGetNextItem.
Initializes the Peer Collaboration infrastructure, if not already started, and increments the associated usage count.
Decrements the Peer Collaboration infrastructure usage count to zero, whereupon it shuts down the infrastructure and releases any resources associated with it.
Signs the peer into a hosted server-less presence or subnet peer collaboration network presence provider.
Signs a peer out of a specific type of peer collaboration network presence provider.
Registers an application with the Peer Collaboration infrastructure to receive callback functions for specific Peer Collaboration events.
Obtains the data associated with a Peer Collaboration event raised on the peer.
Deregisters an application from notification about specific Peer Collaboration events.
Collaboration Contact API
A Peer Collaboration contact contains an X.509 security certificate, a peer name, a nickname and some other optional information (for example, email address, display name, and a bitmap). Peer Collaboration contacts are fully integrated with the Windows Address Book (WAB). These contacts are grouped as a subset of general WAB contacts, and are also available to other applications through the WAB My Contacts UI and API. However, security certificates associated with Peer Collaboration contacts are stored separately in Peer Collaboration infrastructure or in the "Trusted People" certificate store of Windows Vista.
There is a special peer contact that represents the local user called the Me contact. This contact is treated slightly different from a regular contact. A Me contact:
Is created through a special function, PeerCollabCreateMeContact.
Is denoted in other function calls by setting the pwzPeerName parameter to null. Any attempt to access the Me contact through its actual peer name will be interpreted as an attempt to access a regular contact created as a copy of the Me contact.
Will automatically be created by the PeerCollabUpdateContact function, if one doesn't already exist.
The certificate portion is stored in the My Store certificate store.
Cannot be deleted.
The Peer Collaboration Contact API is available immediately after the infrastructure is started by a call to the PeerCollabStartup function. When a contract is created or retrieved from the store, a peer identity is automatically associated with it:
Adds a peer contact to the current peer's contact list by using data obtained from a peer contact XML string.
Deletes a peer contact from the current peer.
Updates a peer participating in a peer collaboration network with new information on a peer contact.
Obtains the information for a specific peer contact given the name of the contact.
Used to create the Me contact and an associated peer identity.
Returns a handle to an enumerated set that contains all of the peer collaboration network contacts currently available on the calling peer.
Returns an XML string representation of the contract. This string can potentially be used on other computers to add this contact to their contact store.
Parses an XML string representation of a contract into a PEER_CONTACT data structure.
The peer's list of watched contacts has changed.
In addition, the following NetShell commands have been added to enable command-line and scripting access to the list of contacts. These commands are available in the p2p → collab → contact command context:
Imports a contact, stored in a file as an XML string, into the contact store.
Deletes a contact from the contact store.
Exports the Me contact to a file, which can be moved to another computer for import purposes.
Changes the properties of the Me contact or other contacts in the store.
Either shows a list of contacts in the contact store or displays the contents of an exported contact XML file.
Server-less presence is a feature of the P2P Collaboration infrastructure available to all Windows Vista applications. Any application that uses the server-less presence component of the collaboration infrastructure will be able to display the user's presence, capabilities, and current status to any application watching it. In addition, P2P applications can use this API to publish and subscribe to peer capabilities and peer objects. Presence information is per user and not per application:
Registers an application with the local computer so that it can be launched in a peer collaboration activity.
Deregisters the specific capabilities of a peer from the local computer.
Sets the name of the current endpoint used by the peer application.
Retrieves the name of the current endpoint of the calling peer.
Obtains the peer's current signed-in peer collaboration network presence options.
Obtains the peer application launch information, including the contact name, the peer endpoint, and the invitation request.
Retrieves the presence information for the endpoint associated with a specific contact.
Updates the caller's presence information to any contacts watching it.
Obtains the enumeration handle used to retrieve peer capability information.
Obtains the specified capability registration information.
Returns the handle to an enumeration that contains the capabilities registered to a specific peer's endpoint(s).
Returns the handle to an enumeration that contains the endpoints associated with a specific peer contact.
Retrieves the published items associated with an endpoint. The list of items retrieved is based on the publication scope of the endpoints associated with the contact. No data is returned using this API; instead, the application should call the various get/enum APIs to retrieve data sent back.
Creates or updates a peer data object used in a peer collaboration network.
Deletes a peer data object from the calling endpoint.
The endpoint associated with a peer contact has changed.
The presence status of an endpoint associated with a peer contact has changed.
The registered capability of the endpoint associated with a peer contact has changed.
A peer object registered to the endpoint associated with a peer contact has changed.
The local peer's endpoint has changed.
The local peer's presence status has changed.
The local peer's registered capability has changed.
A peer object registered with the local peer has changed.
People Near Me
This component is responsible for discovering people located on the same local cloud. For Windows Vista, it uses SSDP to discover neighboring contacts. The Application Invite Infrastructure can use the endpoints returned by People Near Me to establish a connection and send invites. For more information about Me contacts, see the Collaboration Contact API.
Creates a contact for the current user. Required for signing onto the system.
Gets a peer enumeration handle to a collection of local endpoints.
An endpoint in the same cloud as the local peer's endpoint has changed.
This component provides APIs for an application to send an invitation either directly to a contact or to a network endpoint. When the invitation is sent to a contact, the Endpoint Manager is used to locate endpoints of the contact using PNRP, a connection is subsequently established with each of the endpoints, and invites are sent across all connections. When an invitation is sent to a network endpoint, then a SIP session is directly created with that endpoint.
Before sending invitations, an application must first use the capability registration function PeerCollabRegisterCapability (in the Server-less Presence component) to register and publish its capabilities. Capabilities can be registered either for the current user or all users (the latter requires administrative privileges).
Obtains the list of addresses on which the peer hosting the Peer Collaboration infrastructure is listening for application invitations.
Sends an asynchronous invitation to a trusted peer contact to join the sender's P2P activity over a secured connection.
Sends a synchronous invitation to a trusted peer contact to join the sender's P2P activity over a secured connection.
Cancels an invitation previously sent by the caller to a contact.
Obtains the response from a peer previously invited to join a P2P activity.
For more information, see Peer-to-Peer Collaboration Infrastructure in the Windows SDK.
Peer Channel API
Peer Channel is a P2P technology built into the Windows Communication Foundation. Like Windows Communication Foundation overall, Peer Channel was designed for reliability, scalability, and ease-of-use. Peer Channel, as the name implies, is a specific Windows Communication Foundation channel implementation for P2P message passing. It internally implements an infrastructure Windows Communication Foundation service that represents a node in the mesh. Each node has connections to a few other nodes in the mesh.
The use of Peer Channel to build a P2P solution has several advantages over the alternative APIs discussed in this section, including:
Windows Communication Foundation — provides a high-level, straightforward SOA approach to P2P solution development. Windows Communication Foundation automatically supplies much of the detailed infrastructure, although this can be customized when necessary.
Standard runtime services — relies on the .NET Framework for services like memory management, serialization, GUI display capability, COM+ integration, and so on. For example, data-binding can be used to connect UI controls directly to portions of a P2P message.
Language independence — because it is a .NET Framework 3.0 technology, Peer Channel supports development in any CLR-compliant language.
WS-* interoperability — the Windows Communication Foundation infrastructure also provides support for many of the current WS-* message protocols.
Mixed messaging solutions — in addition to P2P, Windows Communication Foundation projects can readily include different communication patterns and easily integrate supporting technologies such as Message Queuing and InfoCard.
For more information about Windows Communication Foundation, see Developer Story Windows Communication Foundation.