adb

package module
v0.0.0-...-0d621e4 Latest Latest
Warning

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

 Go to latest Published: Dec 10, 2023 License: Apache-2.0 Imports: 20 Imported by: 0

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 HasErrCode 

func HasErrCode(err error, code ErrCode) bool

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

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) Forward 

func (c *Device) Forward(hostPort string, devicePort string) (string, error)

Forward Use the forward command to set up arbitrary port forwarding, which forwards requests on a specific host port to a different port on a device.

func (*Device) GetDebuggablePids 

func (c *Device) GetDebuggablePids(timeout time.Duration) ([]string, error)

Using the 'jdwp' command, return a list of PIDs that have an available JDWP endpoint.

Note, the 'jdwp' command is odd in that rather than just finding PIDs and then immediately returning, it just sits there returning new IDs as they become available. That's nice if you run this command before a debuggable app has started, but it means it doesn't actually, you know, stop.

So this call includes a timeout where it'll wait for the indicated time and then terminate the command and return the set of found PIDs.

func (*Device) ListDirEntries 

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

func (*Device) ListForwards 

func (c *Device) ListForwards(hostPort string) (string, error)

ListForwards Used to list all the curretly forwarded ports

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) RemoveForward 

func (c *Device) RemoveForward(hostPort string) (string, error)

RemoveForward Used to remove a specific forward socket connection.

func (*Device) Root 

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

Root restart adbd with root permissions

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
	StateAuthorizing
	StateUnauthorized
	StateDisconnected
	StateOffline
	StateOnline
	StateRecovery
)

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
}

Source Files

View all Source files

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.
utils
errors
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
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.