bind

Documentation

Overview

Package bind contains code for binding to and controlling devices.

Index

• func PutRegistry(ctx context.Context, m *Registry) context.Context
• type Desktop
  • func Host(ctx context.Context) Desktop
• type Device
• type DeviceListener
  • func NewDeviceListener(onDeviceAdded, onDeviceRemoved func(context.Context, Device)) DeviceListener
• type DeviceWithShell
• type Registry
  • func GetRegistry(ctx context.Context) *Registry
  • func NewRegistry() *Registry
  • func (r *Registry) AddDevice(ctx context.Context, d Device)
  • func (r *Registry) DefaultDevice() Device
  • func (r *Registry) Device(id id.ID) Device
  • func (r *Registry) DeviceProperty(ctx context.Context, d Device, k interface{}) interface{}
  • func (r *Registry) Devices() []Device
  • func (r *Registry) Listen(l DeviceListener) (unregister func())
  • func (r *Registry) RemoveDevice(ctx context.Context, d Device)
  • func (r *Registry) SetDeviceProperty(ctx context.Context, d Device, k, v interface{})
• type Simple
  • func (b *Simple) ABI() *device.ABI
  • func (b *Simple) CanTrace() bool
  • func (b *Simple) ConnectPerfetto(ctx context.Context) (*perfetto.Client, error)
  • func (b *Simple) InstallApp(ctx context.Context, app string) error
  • func (b *Simple) Instance() *device.Instance
  • func (b *Simple) Status(ctx context.Context) Status
  • func (b *Simple) String() string
  • func (b *Simple) SupportsPerfetto(ctx context.Context) bool
• type Status

Functions

func PutRegistry

func PutRegistry(ctx context.Context, m *Registry) context.Context

PutRegistry attaches a registry to a Context.

Types

type Desktop

type Desktop interface {
	DeviceWithShell
	// SetupLocalPort makes sure that the given port can be accessed on localhost
	// It returns a new port number to connect to on localhost
	SetupLocalPort(ctx context.Context, port int) (int, error)
	// TempFile creates a temporary file on the given Device. It returns the
	// path to the file, and a function that can be called to clean it up.
	TempFile(ctx context.Context) (string, func(ctx context.Context), error)
	// TempDir makes a temporary directory, and returns the
	// path, as well as a function to call to clean it up.
	TempDir(ctx context.Context) (string, app.Cleanup, error)
	// FileContents returns the contents of a given file on the Device.
	FileContents(ctx context.Context, path string) (string, error)
	// RemoveFile removes the given file from the device
	RemoveFile(ctx context.Context, path string) error
	// GetEnv returns the default environment for the Device.
	GetEnv(ctx context.Context) (*shell.Env, error)
	// ListExecutables returns the executables in a particular directory as given by path
	ListExecutables(ctx context.Context, path string) ([]string, error)
	// ListDirectories returns a list of directories rooted at a particular path
	ListDirectories(ctx context.Context, path string) ([]string, error)
	// GetURIRoot returns the root URI for the entire system
	GetURIRoot() string
	// IsFile returns true if the given path is a file
	IsFile(ctx context.Context, path string) (bool, error)
	// IsDirectory returns true if the given path is a directory
	IsDirectory(ctx context.Context, path string) (bool, error)
	// GetWorkingDirectory returns the directory that this device considers CWD
	GetWorkingDirectory(ctx context.Context) (string, error)
	// IsLocal returns true if this tracer is local
	IsLocal(ctx context.Context) (bool, error)
	// PushFile will transfer the local file at sourcePath to the remote
	// machine at destPath
	PushFile(ctx context.Context, sourcePath, destPath string) error
	// WriteFile writes the given file into the given location on the remote device
	WriteFile(ctx context.Context, contents io.Reader, mode os.FileMode, destPath string) error
}

Desktop represents a desktop-like device, either the local host, or remote.

func Host

func Host(ctx context.Context) Desktop

Host returns the Device to the host.

type Device

type Device interface {
	// Instance returns the instance information for this device.
	Instance() *device.Instance
	// State returns the last known connected status of the device.
	Status(ctx context.Context) Status
	// CanTrace returns true if this device can be used to take a trace
	CanTrace() bool
	// SupportsPerfetto returns true if this device will work with perfetto
	SupportsPerfetto(ctx context.Context) bool
	// ConnectPerfetto connects to a Perfetto service running on this device
	// and returns an open socket connection to the service.
	ConnectPerfetto(ctx context.Context) (*perfetto.Client, error)
	// InstallApp installs the given application to this device
	InstallApp(ctx context.Context, app string) error
}

Device represents a connection to an attached device.

type DeviceListener

type DeviceListener interface {
	OnDeviceAdded(context.Context, Device)
	OnDeviceRemoved(context.Context, Device)
}

DeviceListener is the interface implemented by types that respond to devices being added to and removed from the registry.

func NewDeviceListener

func NewDeviceListener(onDeviceAdded, onDeviceRemoved func(context.Context, Device)) DeviceListener

NewDeviceListener returns a DeviceListener that delegates calls on to onDeviceAdded and onDeviceRemoved.

type DeviceWithShell

type DeviceWithShell interface {
	Device
	// Shell is a helper that builds a shell.Cmd with d.ShellTarget() as its target
	Shell(name string, args ...string) shell.Cmd
}

type Registry

type Registry struct {
	sync.Mutex
	// contains filtered or unexported fields
}

Registry is holds a list of registered devices. It provides methods for listening for devices that are added to and removed from the device.

func GetRegistry

func GetRegistry(ctx context.Context) *Registry

GetRegistry retrieves the registry from a context previously annotated by PutRegistry.

func NewRegistry

func NewRegistry() *Registry

NewRegistry returns a newly constructed Registry.

func (*Registry) AddDevice

func (r *Registry) AddDevice(ctx context.Context, d Device)

AddDevice registers the device dev with the Registry.

func (*Registry) DefaultDevice

func (r *Registry) DefaultDevice() Device

DefaultDevice returns the first device registered with the Registry.

func (*Registry) Device

func (r *Registry) Device(id id.ID) Device

Device looks up the device with the specified identifier. If no device with the specified identifier was registered with the Registry then nil is returner.

func (*Registry) DeviceProperty

func (r *Registry) DeviceProperty(ctx context.Context, d Device, k interface{}) interface{}

DeviceProperty returns the property with the key k for the device d, previously set with SetDeviceProperty. If the property for the device does not exist then nil is returned.

func (*Registry) Devices

func (r *Registry) Devices() []Device

Devices returns the list of devices registered with the Registry.

func (*Registry) Listen

func (r *Registry) Listen(l DeviceListener) (unregister func())

Listen registers l to be called whenever a device is added to or removed from the registry. l will be unregistered when the returned function is called.

func (*Registry) RemoveDevice

func (r *Registry) RemoveDevice(ctx context.Context, d Device)

RemoveDevice unregisters the device d with the Registry.

func (*Registry) SetDeviceProperty

func (r *Registry) SetDeviceProperty(ctx context.Context, d Device, k, v interface{})

SetDeviceProperty sets the property with the key k to the value v for the device d. This property can be retrieved with DeviceProperty. Properties will persist in the registry even when the device has not been added or has been removed.

type Simple

type Simple struct {
	To         *device.Instance
	LastStatus Status
}

Simple is a very short implementation of the Device interface. It directly holds the devices Information struct, and its last known Status, but provides no other active functionality. It can be used for fake devices, or as a building block to create a more complete device.

func (*Simple) ABI

func (b *Simple) ABI() *device.ABI

ABI implements the Device interface returning the first ABI from the Information, or UnknownABI if it has none.

func (*Simple) CanTrace

func (b *Simple) CanTrace() bool

CanTrace returns true if this device can be used to take a trace

func (*Simple) ConnectPerfetto

func (b *Simple) ConnectPerfetto(ctx context.Context) (*perfetto.Client, error)

ConnectPerfetto connects to a Perfetto service running on this device and returns an open socket connection to the service.

func (*Simple) InstallApp

func (b *Simple) InstallApp(ctx context.Context, app string) error

InstallApp implements the Device interface, always returning an error.

func (*Simple) Instance

func (b *Simple) Instance() *device.Instance

Instance implements the Device interface returning the Information in the To field.

func (*Simple) Status

func (b *Simple) Status(ctx context.Context) Status

Status implements the Device interface returning the Status from the LastStatus field.

func (*Simple) String

func (b *Simple) String() string

func (*Simple) SupportsPerfetto

func (b *Simple) SupportsPerfetto(ctx context.Context) bool

SupportsPerfetto returns true if this device will work with perfetto.

type Status

type Status int

const (
	UnknownStatus Status = iota
	Offline
	Online
	Unauthorized
)