OLD | NEW |
---|---|
(Empty) | |
1 // Copyright 2017 The Chromium Authors. All rights reserved. | |
2 // Use of this source code is governed by a BSD-style license that can be | |
3 // found in the LICENSE file. | |
4 | |
5 #ifndef MOJO_EDK_EMBEDDER_PENDING_PROCESS_CONNECTION_H_ | |
6 #define MOJO_EDK_EMBEDDER_PENDING_PROCESS_CONNECTION_H_ | |
7 | |
8 #include <string> | |
9 | |
10 #include "base/callback.h" | |
11 #include "base/macros.h" | |
12 #include "base/process/process_handle.h" | |
13 #include "mojo/edk/embedder/scoped_platform_handle.h" | |
14 #include "mojo/edk/system/system_impl_export.h" | |
15 #include "mojo/public/cpp/system/message_pipe.h" | |
16 | |
17 namespace mojo { | |
18 namespace edk { | |
19 | |
20 using ProcessErrorCallback = base::Callback<void(const std::string& error)>; | |
21 | |
22 // Represents a potential connection to an external process. Use this object | |
23 // to make other processes reachable from this one via Mojo IPC. Typical usage | |
24 // might look something like: | |
25 // | |
26 // PendingProcessConnection connection; | |
27 // | |
28 // std::string pipe_token; | |
29 // ScopedMessagePipeHandle pipe = connection.CreateMessagePipe(&pipe_token); | |
30 // | |
31 // // New pipes to the process are fully functional and can be used right | |
32 // // away, even if the process doesn't exist yet. | |
33 // GoDoSomethingInteresting(std::move(pipe)); | |
34 // | |
35 // ScopedPlatformChannelPair channel; | |
36 // | |
37 // // Give the pipe token to the child process via command-line. | |
38 // child_command_line.AppendSwitchASCII("yer-pipe", pipe_token); | |
39 // | |
40 // // Magic child process launcher which gives one end of the pipe to the | |
41 // // new process. | |
42 // LaunchProcess(child_command_line, channel.PassClientHandle()); | |
43 // | |
44 // // Some time later... | |
45 // connection.Connect(new_process, channel.PassServerHandle()); | |
46 // | |
47 // If at any point during the above process, |connection| is destroyed before | |
48 // Connect() can be called, |pipe| will imminently behave as if its peer has | |
49 // been closed. | |
50 // | |
51 // Otherwise, if the remote process in this example eventually calls: | |
52 // | |
53 // mojo::edk::InitChild(std::move(client_channel_handle)); | |
Sam McNally
2017/02/09 05:38:47
Still mojo::edk::SetParentPipeHandle()?
Ken Rockot(use gerrit already)
2017/02/09 06:01:58
Oops, done
| |
54 // | |
55 // std::string token = command_line.GetSwitchValueASCII("yer-pipe"); | |
56 // ScopedMessagePipeHandle pipe = mojo::edk::CreateChildMessagePipe(token); | |
57 // | |
58 // it will be connected to this process, and its |pipe| will be connected to | |
59 // this process's |pipe|. | |
60 // | |
61 // If the remote process exits or otherwise closes its client channel handle | |
62 // before calling CreateChildMessagePipe for a given message pipe token, | |
63 // this process's end of the corresponding message pipe will imminently behave | |
64 // as if its peer has been closed. | |
65 // | |
66 class MOJO_SYSTEM_IMPL_EXPORT PendingProcessConnection { | |
67 public: | |
68 PendingProcessConnection(); | |
69 ~PendingProcessConnection(); | |
70 | |
71 // Creates a message pipe associated with a new globally unique string value | |
72 // which will be placed in |*token|. | |
73 // | |
74 // The other end of the new pipe is obtainable in the remote process (or in | |
75 // this process, to facilitate "single-process mode" in some applications) by | |
76 // passing the new |*token| value to mojo::edk::CreateChildMessagePipe. It's | |
77 // the caller's responsibility to communicate the value of |*token| to the | |
78 // remote process by any means available, e.g. a command-line argument on | |
79 // process launch, or some other out-of-band communication channel for an | |
80 // existing process. | |
81 // | |
82 // NOTES: This may be called any number of times to create multiple message | |
83 // pipes to the same remote process. This call ALWAYS succeeds, returning | |
84 // a valid message pipe handle and populating |*token| with a new unique | |
85 // string value. | |
86 ScopedMessagePipeHandle CreateMessagePipe(std::string* token) const; | |
87 | |
88 // Connects to the process. This must be called at most once, with the process | |
89 // handle in |process|. | |
90 // | |
91 // |channel| is the platform handle of an OS pipe which can be used to | |
92 // communicate with the connected process. The other end of that pipe must | |
93 // ultimately be passed to mojo::edk::SetParentPipeHandle in the remote | |
94 // process, and getting that end of the pipe into the other process is the | |
95 // embedder's responsibility. | |
96 // | |
97 // If this method is not called by the time the PendingProcessConnection is | |
98 // destroyed, it's assumed that the process is unavailable (e.g. process | |
99 // launch failed or the process has otherwise been terminated early), and | |
100 // any associated resources, such as remote endpoints of messages pipes | |
101 // created by CreateMessagePipe above) will be cleaned up at that time. | |
102 void Connect( | |
103 base::ProcessHandle process, | |
104 ScopedPlatformHandle channel, | |
105 const ProcessErrorCallback& error_callback = ProcessErrorCallback()); | |
106 | |
107 private: | |
108 // A GUID representing a potential new process to be connected to this one. | |
109 const std::string process_token_; | |
110 | |
111 bool connected_ = false; | |
112 | |
113 DISALLOW_COPY_AND_ASSIGN(PendingProcessConnection); | |
114 }; | |
115 | |
116 } // namespace edk | |
117 } // namespace mojo | |
118 | |
119 #endif // MOJO_EDK_EMBEDDER_PENDING_PROCESS_CONNECTION_H_ | |
OLD | NEW |