wire

Documentation

Overview

Package wire implements the low-level part of the client/server wire protocol. It also implements the "sync" wire format for file transfers.

This package is not intended to be used directly. adb.Adb and adb.Device use it to abstract away the bit-twiddling details of the protocol. You should only ever need to work with the goadb package. Also, this package's API may change more frequently than goadb's.

The protocol spec can be found at https://android.googlesource.com/platform/system/core/+/master/adb/OVERVIEW.TXT.

Index

• Constants
• func IsAdbServerErrorMatching(err error, predicate func(string) bool) bool
• func MultiCloseable(c io.ReadWriteCloser) io.ReadWriteCloser
• func ParseFileModeFromAdb(modeFromSync uint32) (filemode os.FileMode)
• func ReadMessageString(s Scanner) (string, error)
• func SendMessageString(s Sender, msg string) error
• type Conn
  • func NewConn(scanner Scanner, sender Sender) *Conn
  • func (conn *Conn) Close() error
  • func (c *Conn) NewSyncConn() *SyncConn
  • func (conn *Conn) RoundTripSingleResponse(req []byte) (resp []byte, err error)
• type ErrorResponseDetails
• type Scanner
  • func NewScanner(r io.ReadCloser) Scanner
• type Sender
  • func NewSender(w io.WriteCloser) Sender
• type StatusReader
• type SyncConn
  • func (c SyncConn) Close() error
• type SyncScanner
  • func NewSyncScanner(r io.Reader) SyncScanner
• type SyncSender
  • func NewSyncSender(w io.Writer) SyncSender

Constants

const (
	ModeDir        uint32 = 0040000
	ModeSymlink           = 0120000
	ModeSocket            = 0140000
	ModeFifo              = 0010000
	ModeCharDevice        = 0020000
)

ADB file modes seem to only be 16 bits. Values are taken from http://linux.die.net/include/bits/stat.h.

const (
	StatusSuccess  string = "OKAY"
	StatusFailure         = "FAIL"
	StatusSyncData        = "DATA"
	StatusSyncDone        = "DONE"
	StatusNone            = ""
)

StatusCodes are returned by the server. If the code indicates failure, the next message will be the error.

const (
	// The official implementation of adb imposes an undocumented 1-megabyte limit
	// on payload size.
	MaxPayloadSize = 1024 * 1024
)

const (
	// Chunks cannot be longer than 64k.
	SyncMaxChunkSize = 64 * 1024
)

Functions

func IsAdbServerErrorMatching

func IsAdbServerErrorMatching(err error, predicate func(string) bool) bool

IsAdbServerErrorMatching returns true if err is an *Err with code AdbError and for which predicate returns true when passed Details.ServerMsg.

func MultiCloseable

func MultiCloseable(c io.ReadWriteCloser) io.ReadWriteCloser

MultiCloseable wraps c in a ReadWriteCloser that can be safely closed multiple times.

func ParseFileModeFromAdb

func ParseFileModeFromAdb(modeFromSync uint32) (filemode os.FileMode)

func ReadMessageString

func ReadMessageString(s Scanner) (string, error)

func SendMessageString

func SendMessageString(s Sender, msg string) error

Types

type Conn

type Conn struct {
	Scanner
	Sender
}

Conn is a normal connection to an adb server.

For most cases, usage looks something like:

conn := wire.Dial()
conn.SendMessage(data)
conn.ReadStatus() == StatusSuccess || StatusFailure
conn.ReadMessage()
conn.Close()

For some messages, the server will return more than one message (but still a single status). Generally, after calling ReadStatus once, you should call ReadMessage until it returns an io.EOF error. Note: the protocol docs seem to suggest that connections will be kept open for multiple commands, but this is not the case. The official client closes a connection immediately after its read the response, in most cases. The docs might be referring to the connection between the adb server and the device, but I haven't confirmed that.

For most commands, the server will close the connection after sending the response. You should still always call Close() when you're done with the connection.

func NewConn

func NewConn(scanner Scanner, sender Sender) *Conn

func (*Conn) Close

func (conn *Conn) Close() error

func (*Conn) NewSyncConn

func (c *Conn) NewSyncConn() *SyncConn

NewSyncConn returns connection that can operate in sync mode. The connection must already have been switched (by sending the sync command to a specific device), or the return connection will return an error.

func (*Conn) RoundTripSingleResponse

func (conn *Conn) RoundTripSingleResponse(req []byte) (resp []byte, err error)

RoundTripSingleResponse sends a message to the server, and reads a single message response. If the reponse has a failure status code, returns it as an error.

type ErrorResponseDetails

type ErrorResponseDetails struct {
	Request   string
	ServerMsg string
}

ErrorResponseDetails is an error message returned by the server for a particular request.

type Scanner

type Scanner interface {
	io.Closer
	StatusReader
	ReadMessage() ([]byte, error)
	ReadUntilEof() ([]byte, error)

	NewSyncScanner() SyncScanner
}

Scanner reads tokens from a server. See Conn for more details.

func NewScanner

func NewScanner(r io.ReadCloser) Scanner

type Sender

type Sender interface {
	SendMessage(msg []byte) error

	NewSyncSender() SyncSender

	Close() error
}

Sender sends messages to the server.

func NewSender

func NewSender(w io.WriteCloser) Sender

type StatusReader

type StatusReader interface {
	// Reads a 4-byte status string and returns it.
	// If the status string is StatusFailure, reads the error message from the server
	// and returns it as an AdbError.
	ReadStatus(req string) (string, error)
}

type SyncConn

type SyncConn struct {
	SyncScanner
	SyncSender
}

SyncConn is a connection to the adb server in sync mode. Assumes the connection has been put into sync mode (by sending "sync" in transport mode).

The adb sync protocol is defined at https://android.googlesource.com/platform/system/core/+/master/adb/SYNC.TXT.

Unlike the normal adb protocol (implemented in Conn), the sync protocol is binary. Lengths are binary-encoded (little-endian) instead of hex.

Notes on Encoding

Length headers and other integers are encoded in little-endian, with 32 bits.

File mode seems to be encoded as POSIX file mode.

Modification time seems to be the Unix timestamp format, i.e. seconds since Epoch UTC.

func (SyncConn) Close

func (c SyncConn) Close() error

Close closes both the sender and the scanner, and returns any errors.

type SyncScanner

type SyncScanner interface {
	io.Closer
	StatusReader
	ReadInt32() (int32, error)
	ReadFileMode() (os.FileMode, error)
	ReadTime() (time.Time, error)

	// Reads an octet length, followed by length bytes.
	ReadString() (string, error)

	// Reads an octet length, and returns a reader that will read length
	// bytes (see io.LimitReader). The returned reader should be fully
	// read before reading anything off the Scanner again.
	ReadBytes() (io.Reader, error)
}

func NewSyncScanner

func NewSyncScanner(r io.Reader) SyncScanner

type SyncSender

type SyncSender interface {
	io.Closer

	// SendOctetString sends a 4-byte string.
	SendOctetString(string) error
	SendInt32(int32) error
	SendFileMode(os.FileMode) error
	SendTime(time.Time) error

	// Sends len(data) as an octet, followed by the bytes.
	// If data is bigger than SyncMaxChunkSize, it returns an assertion error.
	SendBytes(data []byte) error
}

func NewSyncSender

func NewSyncSender(w io.Writer) SyncSender