github.com/haraldrudell/parl@v0.4.176/if-adbette.go (about) 1 /* 2 © 2022–present Harald Rudell <harald.rudell@gmail.com> (https://haraldrudell.github.io/haraldrudell/) 3 ISC License 4 */ 5 6 package parl 7 8 import ( 9 "context" 10 "io" 11 ) 12 13 // Adbette is a minimal implementation of the adb Android debug bridge protocol. 14 // Adbette include both adb server and Android device functions. 15 // Adbette is extensible in that additional protocol features are easily 16 // implemented without concern for protocol details. 17 // to shutdown an Adbette and release its resouces, invoke the Closer method 18 type Adbette interface { 19 // SendReadOkay sends a request to a remote adb endpoint. 20 // if anything else than OKAY is received back from the 21 // remote endpoint, err is non-nil. 22 SendReadOkay(request AdbRequest) (err error) 23 // ReadString reads utf-8 text up to 64 KiB-1 in length 24 ReadString() (s string, err error) 25 // ConnectToDevice sends a forwarding request to an adb 26 // server to connect to one of its devices 27 ConnectToDevice(serial AndroidSerial) (err error) 28 // Shell executes a shell command on a device connected to the adb server. 29 // - out is a combination of stderr and stdout. 30 // - The status code from an on-device command cannot be obtained 31 Shell(command string) (out []byte, err error) 32 // ShellStream executes a shell command on the device returning a readable socket 33 ShellStream(command string) (conn io.ReadWriteCloser, err error) 34 // TrackDevices orders a server to emit serial number as they become available 35 TrackDevices() (err error) 36 // Devices lists the currently online serials 37 Devices() (serials []AndroidSerial, err error) 38 // DeviceStati returns all available serials and their status 39 // The two slices correspond and are of the same length 40 DeviceStati() (serials []AndroidSerial, stati []AndroidStatus, err error) 41 // Closer closes an adb connection, meant to be a deferred function 42 Closer(errp *error) 43 // SetSync sets the protocol mode of an adb device connection to sync 44 SetSync() (err error) 45 // LIST is a sync request that lists file system entries in a directory of an adb device 46 LIST(remoteDir string, dentReceiver func(mode uint32, size uint32, time uint32, byts []byte) (err error)) (err error) 47 // RECV fetches the contents of a file on an adb device 48 RECV(remotePath string, blobReceiver func(data []byte) (err error)) (err error) 49 // CancelError is a value that a LIST or RECV callback routines can return to 50 // cancel further invocations 51 CancelError() (cancelError error) 52 53 // below are convenience methods for extending Adbetter 54 55 SendBlob(syncRequest AdbSyncRequest, data []byte) (err error) 56 ReadBlob() (byts []byte, err error) 57 ReadResponseID() (responseID AdbResponseID, err error) 58 ReadBytes(byts []byte) (err error) 59 SendBytes(byts []byte) (err error) 60 } 61 62 /* 63 AdbSocketAddress is a tcp socket address accessible to the 64 local host. 65 The format is two parts separated by a colon. 66 The first part is an IP address or hostname. 67 The second part is a numeric port number. 68 The empty string "" represents "localhost:5037". 69 If the port part is missing, such as "localhost" it implies port 5037. 70 If the host part is missing, it implies "localhost". 71 Note that locahost is valid both for IPv4 and IPv6. 72 */ 73 type AdbSocketAddress string 74 75 // AndroidSerial uniquely identities an Android device. 76 // - has .String and .IsValid, is Ordered 77 // - typically a string of a dozen or so 8-bit chanacters consisting of 78 // lower and upper case a-zA-Z0-9 79 type AndroidSerial string 80 81 // Adbetter is a factory instance for connections featuring Adbette 82 // context is used for terminating a connection attempt. 83 // context is not retained in the connection. 84 type Adbetter interface { 85 NewConnection(address AdbSocketAddress, ctx context.Context) (conn Adbette, err error) 86 } 87 88 // AdbRequest is a string formatted as an adb request. 89 // AdbRequest is only required for implementations using the Adbette protocol 90 // impementation 91 type AdbRequest string 92 93 type AdbSyncRequest string 94 95 type AdbResponseID string 96 97 // AdressProvider retrieves the address from an adb server or device so that 98 // custom devices can be created 99 type AdbAdressProvider interface { 100 // AdbSocketAddress retrievs the tcp socket address used 101 // by a near Adbette implementation 102 AdbSocketAddress() (socketAddress AdbSocketAddress) 103 }