1# Mojo C++ Platform API 2This document is a subset of the [Mojo documentation](/mojo/README.md). 3 4[TOC] 5 6## Overview 7The Mojo C++ Platform API provides a lightweight set of abstractions around 8stable platform primitive APIs like UNIX domain sockets and Windows named pipes. 9This API is primarily useful in conjunction with Mojo 10[Invitations](/mojo/public/cpp/system/README.md#Invitations) to bootstrap Mojo 11IPC between two processes. 12 13## Platform Handles 14The `PlatformHandle` type provides a move-only wrapper around an owned, 15platform-specific primitive handle types. The type of primitive it holds can be 16any of the following: 17 18 * Windows HANDLE (Windows only) 19 * Fuchsia zx_handle_t (Fuchsia only) 20 * Mach send right (OSX only) 21 * POSIX file descriptor (POSIX systems only) 22 23See the 24[header](https://cs.chromium.org/src/mojo/public/cpp/platform/platform_handle.h) 25for more details. 26 27## Platform Channels 28The `PlatformChannel` type abstracts a platform-specific IPC FIFO primitive 29primarily for use with the Mojo 30[Invitations](/mojo/public/cpp/system/README.md#Invitations) API. Constructing 31a `PlatformChannel` instance creates the underlying system primitive with two 32transferrable `PlatformHandle` instances, each thinly wrapped as a 33`PlatformChannelEndpoint` for additional type-safety. One endpoint is designated 34as **local** and the other **remote**, the intention being that the remote 35endpoint will be transferred to another process in the system. 36 37See the 38[header](https://cs.chromium.org/src/mojo/public/cpp/platform/platform_channel.h) 39for more details. See the 40[Invitations](/mojo/public/cpp/system/README.md#Invitations) documentation for 41an example of using `PlatformChannel` with an invitation to bootstrap IPC 42between a process and one of its newly launched child processes. 43 44## Named Platform Channels 45For cases where it is not feasible to transfer a `PlatformHandle` from one 46running process to another, the Platform API also provides 47`NamedPlatformChannel`, which abstracts a named system resource that can 48facilitate communication similarly to `PlatformChannel`. 49 50A `NamedPlatformChannel` upon construction will begin listening on 51platform-specific primitive (a named pipe server on Windows, a domain socket 52server on POSIX, *etc.*). The globally reachable name of the server (*e.g.* the 53socket path) can be specified at construction time via 54`NamedPlatformChannel::Options::server_name`, but if no name is given, a 55suitably random one is generated and used. 56 57``` cpp 58// In one process 59mojo::NamedPlatformChannel::Options options; 60mojo::NamedPlatformChannel named_channel(options); 61OutgoingInvitation::Send(std::move(invitation), 62 named_channel.TakeServerEndpoint()); 63SendServerNameToRemoteProcessSomehow(named_channel.GetServerName()); 64 65// In the other process 66void OnGotServerName(const mojo::NamedPlatformChannel::ServerName& name) { 67 // Connect to the server. 68 mojo::PlatformChannelEndpoint endpoint = 69 mojo::NamedPlatformChannel::ConnectToServer(name); 70 71 // Proceed normally with invitation acceptance. 72 auto invitation = mojo::IncomingInvitation::Accept(std::move(endpoint)); 73 // ... 74} 75``` 76