adb

package module
v0.0.0-...-efd54db Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jun 23, 2023 License: Apache-2.0 Imports: 19 Imported by: 3

README

#goadb

Build Status GoDoc

A Golang library for interacting with the Android Debug Bridge (adb).

See demo.go for usage.

Documentation

Overview

package adb is a Go interface to the Android Debug Bridge (adb).

See cmd/demo/demo.go for an example of how to use this library.

The client/server spec is defined at https://android.googlesource.com/platform/system/core/+/master/adb/OVERVIEW.TXT.

WARNING This library is under heavy development, and its API is likely to change without notice.

Index

Constants

View Source
const (
	// host:transport-any and host:<request>
	DeviceAny deviceDescriptorType = iota
	// host:transport:<serial> and host-serial:<serial>:<request>
	DeviceSerial
	// host:transport-usb and host-usb:<request>
	DeviceUsb
	// host:transport-local and host-local:<request>
	DeviceLocal
)
View Source
const (
	AssertionError = ErrCode(errors.AssertionError)
	ParseError     = ErrCode(errors.ParseError)
	// The server was not available on the requested port.
	ServerNotAvailable = ErrCode(errors.ServerNotAvailable)
	// General network error communicating with the server.
	NetworkError = ErrCode(errors.NetworkError)
	// The connection to the server was reset in the middle of an operation. Server probably died.
	ConnectionResetError = ErrCode(errors.ConnectionResetError)
	// The server returned an error message, but we couldn't parse it.
	AdbError = ErrCode(errors.AdbError)
	// The server returned a "device not found" error.
	DeviceNotFound = ErrCode(errors.DeviceNotFound)
	// Tried to perform an operation on a path that doesn't exist on the device.
	FileNoExistError = ErrCode(errors.FileNoExistError)
)
View Source
const (
	AdbExecutableName = "adb"

	// Default port the adb server listens on.
	AdbPort = 5037
)

Variables

View Source
var MtimeOfClose = time.Time{}

MtimeOfClose should be passed to OpenWrite to set the file modification time to the time the Close method is called.

Functions

func ErrorWithCauseChain

func ErrorWithCauseChain(err error) string

ErrorWithCauseChain formats err and all its causes if it's an *errors.Err, else returns err.Error().

func Errorf

func Errorf(code ErrCode, format string, args ...interface{}) error

func HasErrCode

func HasErrCode(err error, code ErrCode) bool

HasErrCode returns true if err is an *errors.Err and err.Code == code.

func WrapErrf

func WrapErrf(cause error, format string, args ...interface{}) error

WrapErrf returns an *Err that wraps another *Err and has the same ErrCode. Panics if cause is not an *Err.

To wrap generic errors, use WrapErrorf.

Types

type Adb

type Adb struct {
	// contains filtered or unexported fields
}

Adb communicates with host services on the adb server.

Eg.

client := adb.New()
client.ListDevices()

See list of services at https://android.googlesource.com/platform/system/core/+/master/adb/SERVICES.TXT.

TODO(z): Finish implementing host services.

func New

func New() (*Adb, error)

New creates a new Adb client that uses the default ServerConfig.

func NewWithConfig

func NewWithConfig(config ServerConfig) (*Adb, error)

func (*Adb) Connect

func (c *Adb) Connect(host string, port int) error

Connect connect to a device via TCP/IP

Corresponds to the command:

adb connect

func (*Adb) Device

func (c *Adb) Device(descriptor DeviceDescriptor) *Device

func (*Adb) Dial

func (c *Adb) Dial() (*wire.Conn, error)

Dial establishes a connection with the adb server.

func (*Adb) KillServer

func (c *Adb) KillServer() error

KillServer tells the server to quit immediately.

Corresponds to the command:

adb kill-server

func (*Adb) ListDeviceSerials

func (c *Adb) ListDeviceSerials() ([]string, error)

ListDeviceSerials returns the serial numbers of all attached devices.

Corresponds to the command:

adb devices

func (*Adb) ListDevices

func (c *Adb) ListDevices() ([]*DeviceInfo, error)

ListDevices returns the list of connected devices.

Corresponds to the command:

adb devices -l

func (*Adb) NewDeviceWatcher

func (c *Adb) NewDeviceWatcher() *DeviceWatcher

func (*Adb) ServerVersion

func (c *Adb) ServerVersion() (int, error)

ServerVersion asks the ADB server for its internal version number.

func (*Adb) StartServer

func (c *Adb) StartServer() error

Starts the adb server if it’s not running.

type Device

type Device struct {
	// contains filtered or unexported fields
}

Device communicates with a specific Android device. To get an instance, call Device() on an Adb.

func (*Device) DeviceInfo

func (c *Device) DeviceInfo() (*DeviceInfo, error)

func (*Device) DevicePath

func (c *Device) DevicePath() (string, error)

func (*Device) ListDirEntries

func (c *Device) ListDirEntries(path string) (*DirEntries, error)

func (*Device) OpenRead

func (c *Device) OpenRead(path string) (io.ReadCloser, error)

func (*Device) OpenWrite

func (c *Device) OpenWrite(path string, perms os.FileMode, mtime time.Time) (io.WriteCloser, error)

OpenWrite opens the file at path on the device, creating it with the permissions specified by perms if necessary, and returns a writer that writes to the file. The files modification time will be set to mtime when the WriterCloser is closed. The zero value is TimeOfClose, which will use the time the Close method is called as the modification time.

func (*Device) Remount

func (c *Device) Remount() (string, error)

Remount, from the official adb command’s docs:

Ask adbd to remount the device's filesystem in read-write mode,
instead of read-only. This is usually necessary before performing
an "adb sync" or "adb push" request.
This request may not succeed on certain builds which do not allow
that.

Source: https://android.googlesource.com/platform/system/core/+/master/adb/SERVICES.TXT

func (*Device) RunCommand

func (c *Device) RunCommand(cmd string, args ...string) (string, error)

RunCommand runs the specified commands on a shell on the device.

From the Android docs:

Run 'command arg1 arg2 ...' in a shell on the device, and return
its output and error streams. Note that arguments must be separated
by spaces. If an argument contains a space, it must be quoted with
double-quotes. Arguments cannot contain double quotes or things
will go very wrong.

Note that this is the non-interactive version of "adb shell"

Source: https://android.googlesource.com/platform/system/core/+/master/adb/SERVICES.TXT

This method quotes the arguments for you, and will return an error if any of them contain double quotes.

func (*Device) Serial

func (c *Device) Serial() (string, error)

func (*Device) Stat

func (c *Device) Stat(path string) (*DirEntry, error)

func (*Device) State

func (c *Device) State() (DeviceState, error)

func (*Device) String

func (c *Device) String() string

type DeviceDescriptor

type DeviceDescriptor struct {
	// contains filtered or unexported fields
}

func AnyDevice

func AnyDevice() DeviceDescriptor

func AnyLocalDevice

func AnyLocalDevice() DeviceDescriptor

func AnyUsbDevice

func AnyUsbDevice() DeviceDescriptor

func DeviceWithSerial

func DeviceWithSerial(serial string) DeviceDescriptor

func (DeviceDescriptor) String

func (d DeviceDescriptor) String() string

type DeviceInfo

type DeviceInfo struct {
	// Always set.
	Serial string

	// Product, device, and model are not set in the short form.
	Product    string
	Model      string
	DeviceInfo string

	// Only set for devices connected via USB.
	Usb string
}

func (*DeviceInfo) IsUsb

func (d *DeviceInfo) IsUsb() bool

IsUsb returns true if the device is connected via USB.

type DeviceState

type DeviceState int8

DeviceState represents one of the 3 possible states adb will report devices. A device can be communicated with when it's in StateOnline. A USB device will make the following state transitions:

Plugged in: StateDisconnected->StateOffline->StateOnline
Unplugged:  StateOnline->StateDisconnected
const (
	StateInvalid DeviceState = iota
	StateUnauthorized
	StateDisconnected
	StateOffline
	StateOnline
)

func (DeviceState) String

func (i DeviceState) String() string

type DeviceStateChangedEvent

type DeviceStateChangedEvent struct {
	Serial   string
	OldState DeviceState
	NewState DeviceState
}

DeviceStateChangedEvent represents a device state transition. Contains the device’s old and new states, but also provides methods to query the type of state transition.

func (DeviceStateChangedEvent) CameOnline

func (s DeviceStateChangedEvent) CameOnline() bool

CameOnline returns true if this event represents a device coming online.

func (DeviceStateChangedEvent) WentOffline

func (s DeviceStateChangedEvent) WentOffline() bool

WentOffline returns true if this event represents a device going offline.

type DeviceWatcher

type DeviceWatcher struct {
	// contains filtered or unexported fields
}

DeviceWatcher publishes device status change events. If the server dies while listening for events, it restarts the server.

func (*DeviceWatcher) C

func (w *DeviceWatcher) C() <-chan DeviceStateChangedEvent

C returns a channel than can be received on to get events. If an unrecoverable error occurs, or Shutdown is called, the channel will be closed.

func (*DeviceWatcher) Err

func (w *DeviceWatcher) Err() error

Err returns the error that caused the channel returned by C to be closed, if C is closed. If C is not closed, its return value is undefined.

func (*DeviceWatcher) Shutdown

func (w *DeviceWatcher) Shutdown()

Shutdown stops the watcher from listening for events and closes the channel returned from C.

type Dialer

type Dialer interface {
	Dial(address string) (*wire.Conn, error)
}

Dialer knows how to create connections to an adb server.

type DirEntries

type DirEntries struct {
	// contains filtered or unexported fields
}

DirEntries iterates over directory entries.

func (*DirEntries) Close

func (entries *DirEntries) Close() error

Close closes the connection to the adb. Next() will call Close() before returning false.

func (*DirEntries) Entry

func (entries *DirEntries) Entry() *DirEntry

func (*DirEntries) Err

func (entries *DirEntries) Err() error

func (*DirEntries) Next

func (entries *DirEntries) Next() bool

func (*DirEntries) ReadAll

func (entries *DirEntries) ReadAll() (result []*DirEntry, err error)

ReadAllDirEntries reads all the remaining directory entries into a slice, closes self, and returns any error. If err is non-nil, result will contain any entries read until the error occurred.

type DirEntry

type DirEntry struct {
	Name       string
	Mode       os.FileMode
	Size       int32
	ModifiedAt time.Time
}

DirEntry holds information about a directory entry on a device.

type ErrCode

type ErrCode errors.ErrCode

type ServerConfig

type ServerConfig struct {
	// Path to the adb executable. If empty, the PATH environment variable will be searched.
	PathToAdb string

	// Host and port the adb server is listening on.
	// If not specified, will use the default port on localhost.
	Host string
	Port int

	// Dialer used to connect to the adb server.
	Dialer
	// contains filtered or unexported fields
}

Directories

Path Synopsis
cmd
adb
demo
An app demonstrating most of the library's features.
An app demonstrating most of the library's features.
raw-adb
A simple tool for sending raw messages to an adb server.
A simple tool for sending raw messages to an adb server.
internal
Package wire implements the low-level part of the client/server wire protocol.
Package wire implements the low-level part of the client/server wire protocol.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL