Payload

AI-generated Key Takeaways

• Payload represents data sent between devices, with the type of data determining how it is received on the other end.

• Payloads can represent files, streams of data, or byte arrays.

• Methods are available to retrieve the data based on the payload type, such as asBytes(), asFile(), and asStream().

• Payloads have a unique ID, can be closed to release resources, and support setting an offset for resuming transfers, file name, parent folder, and sensitivity for file types.

public class Payload extends Object

A Payload sent between devices. Payloads sent as a particular type will be received as that same type on the other device, e.g. the data for a Payload of type Payload.Type.STREAM must be received by reading from the InputStream returned by asStream().

Nested Class Summary

class	Payload.File		Represents a file in local storage on the device.
class	Payload.Stream		Represents a stream of data.
@interface	Payload.Type		The type of this payload.

Public Method Summary

byte[]	asBytes() Non-null for payloads of type Payload.Type.BYTES.
Payload.File	asFile() Non-null for payloads of type Payload.Type.FILE.
Payload.Stream	asStream() Non-null for payloads of type Payload.Type.STREAM.
void	close() Closes to release any ParcelFileDescriptor and InputStream resources for Payload.File or Payload.Stream when the transferring stopped.
static Payload	fromBytes(byte[] bytes) Creates a Payload of type Payload.Type.BYTES for sending to another device.
static Payload	fromFile(ParcelFileDescriptor pfd) Creates a Payload of type Payload.Type.FILE (backed by a ParcelFileDescriptor) for sending to another device; for example, the ParcelFileDescriptor obtained from a call to ContentResolver.openFileDescriptor(Uri, String) for a URI.
static Payload	fromFile(File javaFile) Creates a Payload of type Payload.Type.FILE (backed by a File) for sending to another device.
static Payload	fromStream(ParcelFileDescriptor pfd) Creates a Payload of type Payload.Type.STREAM (backed by a ParcelFileDescriptor) for sending to another device; for example, the read side of a ParcelFileDescriptor pipe to which data is being written by the MediaRecorder API.
static Payload	fromStream(InputStream inputStream) Creates a Payload of type Payload.Type.STREAM (backed by an InputStream) for sending to another device; for example, a PipedInputStream connected to a PipedOutputStream to which data is being written.
long	getId() A unique identifier for this payload.
long	getOffset() Returns the offset of this payload for resume sending or receiving.
int	getType() The type of this payload, one of Payload.Type.
void	setFileName(String name) Sets the file name of this Payload.Type.FILE payload.
void	setOffset(long offset) Sets the offset from getOffset() when resuming a transfer.
void	setParentFolder(String parentFolder) Sets the parent folder of this Payload.Type.FILE payload.
void	setSensitive(boolean isSensitive) Sets whether or not the payload is sensitive.

Inherited Method Summary

From class java.lang.Object

Object	clone()
boolean	equals(Object arg0)
void	finalize()
final Class<?>	getClass()
int	hashCode()
final void	notify()
final void	notifyAll()
String	toString()
final void	wait(long arg0, int arg1)
final void	wait(long arg0)
final void	wait()

Public Methods

public byte[] asBytes ()

Non-null for payloads of type Payload.Type.BYTES.

public Payload.File asFile ()

Non-null for payloads of type Payload.Type.FILE.

public Payload.Stream asStream ()

Non-null for payloads of type Payload.Type.STREAM.

public void close ()

Closes to release any ParcelFileDescriptor and InputStream resources for Payload.File or Payload.Stream when the transferring stopped.

public static Payload fromBytes (byte[] bytes)

Creates a Payload of type Payload.Type.BYTES for sending to another device.

public static Payload fromFile (ParcelFileDescriptor pfd)

Creates a Payload of type Payload.Type.FILE (backed by a ParcelFileDescriptor) for sending to another device; for example, the ParcelFileDescriptor obtained from a call to ContentResolver.openFileDescriptor(Uri, String) for a URI.

public static Payload fromFile (File javaFile)

Creates a Payload of type Payload.Type.FILE (backed by a File) for sending to another device. Note: The file will be saved in the remote device's Downloads folder under a generic name with no extension. The client app on the remote device is responsible for renaming this File and adding an appropriate extension, if necessary, and all this (and possibly additional) metadata should be transmitted by the local device out-of-band (likely using a Payload of type Payload.Type.BYTES).

The client app must have any necessary permissions to read the Java file.

Throws

FileNotFoundException

public static Payload fromStream (ParcelFileDescriptor pfd)

Creates a Payload of type Payload.Type.STREAM (backed by a ParcelFileDescriptor) for sending to another device; for example, the read side of a ParcelFileDescriptor pipe to which data is being written by the MediaRecorder API.

Nearby Connections will read continuously from the ParcelFileDescriptor (for data to send) until it is closed.

public static Payload fromStream (InputStream inputStream)

Creates a Payload of type Payload.Type.STREAM (backed by an InputStream) for sending to another device; for example, a PipedInputStream connected to a PipedOutputStream to which data is being written.

Nearby Connections will read continuously from the InputStream (for data to send) until it is closed.

public long getId ()

A unique identifier for this payload.

public long getOffset ()

Returns the offset of this payload for resume sending or receiving.

public int getType ()

The type of this payload, one of Payload.Type.

public void setFileName (String name)

Sets the file name of this Payload.Type.FILE payload. Nearby Connections will pass the file name to the remote device and then the remote device will attempt to save the payload file with the specified file name under the device's download folder.

public void setOffset (long offset)

Sets the offset from getOffset() when resuming a transfer. The payload will be started to send from the offset. Only supports type Payload.Type.FILE or Payload.Type.STREAM.

public void setParentFolder (String parentFolder)

Sets the parent folder of this Payload.Type.FILE payload. Nearby Connections will pass the parent folder's name to the remote device and then the remote device will create a folder with the specified name under the download folder to save the incoming payload.

public void setSensitive (boolean isSensitive)

Sets whether or not the payload is sensitive. This setting is only supported for Payload.Type.FILE. Sensitive Payload.Type.FILE payloads will be stored in private storage and cannot be read by apps other than the caller. By default, this option is false.