blob: 81d7036a5e815566815bd87a70d9e81818156855 [file] [log] [blame]
David Pursell4f344bb2015-08-28 15:08:49 -07001/*
2 * Copyright (C) 2015 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
David Purselld0df2dd2015-08-31 15:36:18 -070017// This file contains classes and functionality to launch shell subprocesses
18// in adbd and communicate between those subprocesses and the adb client.
19//
20// The main features exposed here are:
21// 1. A ShellPacket class to wrap data in a simple protocol. Both adbd and
22// the adb client use this class to transmit data between them.
23// 2. Functions to launch a subprocess on the adbd side.
24
David Pursell4f344bb2015-08-28 15:08:49 -070025#ifndef SHELL_SERVICE_H_
26#define SHELL_SERVICE_H_
27
David Purselld0df2dd2015-08-31 15:36:18 -070028#include <stdint.h>
29
30#include <base/macros.h>
31
32#include "adb.h"
33
34// Class to send and receive shell protocol packets.
35//
36// To keep things simple and predictable, reads and writes block until an entire
37// packet is complete.
38//
39// Example: read raw data from |fd| and send it in a packet.
40// ShellProtocol* p = new ShellProtocol(protocol_fd);
41// int len = adb_read(stdout_fd, p->data(), p->data_capacity());
42// packet->WritePacket(ShellProtocol::kIdStdout, len);
43//
44// Example: read a packet and print it to |stdout|.
45// ShellProtocol* p = new ShellProtocol(protocol_fd);
46// if (p->ReadPacket() && p->id() == kIdStdout) {
47// fwrite(p->data(), 1, p->data_length(), stdout);
48// }
49class ShellProtocol {
50 public:
51 // This is an unscoped enum to make it easier to compare against raw bytes.
52 enum Id : uint8_t {
53 kIdStdin = 0,
54 kIdStdout = 1,
55 kIdStderr = 2,
56 kIdExit = 3,
57 kIdInvalid = 255, // Indicates an invalid or unknown packet.
58 };
59
60 // ShellPackets will probably be too large to allocate on the stack so they
61 // should be dynamically allocated on the heap instead.
62 //
63 // |fd| is an open file descriptor to be used to send or receive packets.
64 explicit ShellProtocol(int fd);
65 virtual ~ShellProtocol();
66
67 // Returns a pointer to the data buffer.
68 const char* data() const { return buffer_ + kHeaderSize; }
69 char* data() { return buffer_ + kHeaderSize; }
70
71 // Returns the total capacity of the data buffer.
72 size_t data_capacity() const { return buffer_end_ - data(); }
73
74 // Reads a packet from the FD.
75 //
76 // If a packet is too big to fit in the buffer then Read() will split the
77 // packet across multiple calls. For example, reading a 50-byte packet into
78 // a 20-byte buffer would read 20 bytes, 20 bytes, then 10 bytes.
79 //
80 // Returns false if the FD closed or errored.
81 bool Read();
82
83 // Returns the ID of the packet in the buffer.
84 int id() const { return buffer_[0]; }
85
86 // Returns the number of bytes that have been read into the data buffer.
87 size_t data_length() const { return data_length_; }
88
89 // Writes the packet currently in the buffer to the FD.
90 //
91 // Returns false if the FD closed or errored.
92 bool Write(Id id, size_t length);
93
94 private:
95 // Packets support 4-byte lengths.
96 typedef uint32_t length_t;
97
98 enum {
99 // It's OK if MAX_PAYLOAD doesn't match on the sending and receiving
100 // end, reading will split larger packets into multiple smaller ones.
101 kBufferSize = MAX_PAYLOAD,
102
103 // Header is 1 byte ID + 4 bytes length.
104 kHeaderSize = sizeof(Id) + sizeof(length_t)
105 };
106
107 int fd_;
108 char buffer_[kBufferSize];
109 size_t data_length_ = 0, bytes_left_ = 0;
110
111 // We need to be able to modify this value for testing purposes, but it
112 // will stay constant during actual program use.
113 char* buffer_end_ = buffer_ + sizeof(buffer_);
114
115 friend class ShellProtocolTest;
116
117 DISALLOW_COPY_AND_ASSIGN(ShellProtocol);
118};
119
David Pursell4f344bb2015-08-28 15:08:49 -0700120#if !ADB_HOST
121
122enum class SubprocessType {
123 kPty,
124 kRaw,
125};
126
127// Forks and starts a new shell subprocess. If |name| is empty an interactive
128// shell is started, otherwise |name| is executed non-interactively.
129//
130// Returns an open FD connected to the subprocess or -1 on failure.
131int StartSubprocess(const char* name, SubprocessType type);
132
133#endif // !ADB_HOST
134
135#endif // SHELL_SERVICE_H_