Sobald die Verbindungen zwischen Geräten hergestellt sind, können Sie Daten austauschen, indem Sie Payload-Objekte senden und empfangen. Ein Payload kann ein einfaches Byte-Array wie eine kurze SMS, eine Datei wie ein Foto oder Video oder ein Stream, z. B. ein Audiostream vom Mikrofon des Geräts, sein.
Nutzlasten werden mit der Methode sendPayload() gesendet und in einer Implementierung von PayloadCallback empfangen, die an acceptConnection() übergeben wird, wie unter Verbindungen verwalten beschrieben.
Arten von Nutzlasten
Byte
Bytenutzlasten sind die einfachste Nutzlast. Sie sind für das Senden einfacher Daten wie Nachrichten oder Metadaten bis zu einer maximalen Größe von Connections.MAX_BYTES_DATA_SIZE geeignet. Hier ein Beispiel für das Senden einer BYTES-Nutzlast:
Payload bytesPayload = Payload.fromBytes(new byte[] {0xa, 0xb, 0xc, 0xd});
Nearby.getConnectionsClient(context).sendPayload(toEndpointId, bytesPayload);
Sie erhalten eine BYTES-Nutzlast, indem Sie die onPayloadReceived()-Methode der PayloadCallback implementieren, die Sie an acceptConnection() übergeben haben.
static class ReceiveBytesPayloadListener extends PayloadCallback {
@Override
public void onPayloadReceived(String endpointId, Payload payload) {
// This always gets the full data of the payload. Is null if it's not a BYTES payload.
if (payload.getType() == Payload.Type.BYTES) {
byte[] receivedBytes = payload.asBytes();
}
}
@Override
public void onPayloadTransferUpdate(String endpointId, PayloadTransferUpdate update) {
// Bytes payloads are sent as a single chunk, so you'll receive a SUCCESS update immediately
// after the call to onPayloadReceived().
}
}
Im Gegensatz zu den Nutzlasten FILE und STREAM werden Nutzlasten des Typs BYTES als einzelner Block gesendet. Es gibt also keine Notwendigkeit, auf das SUCCESS-Update zu warten (obwohl es dennoch direkt nach dem Aufruf von onPayloadReceived() bereitgestellt wird). Stattdessen können Sie payload.asBytes() aufrufen, um die vollständigen Daten der Nutzlast abzurufen, sobald onPayloadReceived() aufgerufen wird.
Datei
Nutzlasten werden aus einer Datei erstellt, die auf dem lokalen Gerät gespeichert ist, z. B. einer Foto- oder Videodatei. Hier ein einfaches Beispiel für das Senden einer FILE-Nutzlast:
File fileToSend = new File(context.getFilesDir(), "hello.txt");
try {
Payload filePayload = Payload.fromFile(fileToSend);
Nearby.getConnectionsClient(context).sendPayload(toEndpointId, filePayload);
} catch (FileNotFoundException e) {
Log.e("MyApp", "File not found", e);
}
Es kann effizienter sein, eine ParcelFileDescriptor zu verwenden, um die FILES-Nutzlast zu erstellen, wenn eine verfügbar ist, z. B. aus einer ContentResolver. Dadurch wird das Kopieren der Dateibyte minimiert:
ParcelFileDescriptor pfd = getContentResolver().openFileDescriptor(uri, "r"); filePayload = Payload.fromFile(pfd);
Wenn eine Datei empfangen wird, wird sie auf dem Gerät des Empfängers im Ordner „Downloads“ (DIRECTORY_DOWNLOADS) mit einem generischen Namen und ohne Erweiterung gespeichert. Sobald die Übertragung abgeschlossen ist, was durch einen Aufruf von onPayloadTransferUpdate() mit PayloadTransferUpdate.Status.SUCCESS angezeigt wird, können Sie das File-Objekt so abrufen, wenn Ihre App auf < Q-Geräte ausgerichtet ist:
File payloadFile = filePayload.asFile().asJavaFile(); // Rename the file. payloadFile.renameTo(new File(payloadFile.getParentFile(), filename));
Wenn Ihre App auf Q-Geräte ausgerichtet ist, können Sie im Anwendungselement Ihres Manifests android:requestLegacyExternalStorage="true" hinzufügen, um den vorherigen Code weiter zu verwenden.
Andernfalls müssen Sie für Q+ die Scoped Storage-Regeln befolgen und mit dem URI des Dienstes auf die empfangene Datei zugreifen.
// Because of https://developer.android.com/preview/privacy/scoped-storage, we are not
// allowed to access filepaths from another process directly. Instead, we must open the
// uri using our ContentResolver.
Uri uri = filePayload.asFile().asUri();
try {
// Copy the file to a new location.
InputStream in = context.getContentResolver().openInputStream(uri);
copyStream(in, new FileOutputStream(new File(context.getCacheDir(), filename)));
} catch (IOException e) {
// Log the error.
} finally {
// Delete the original file.
context.getContentResolver().delete(uri, null, null);
}
Im folgenden komplexeren Beispiel fordert der Nutzer ACTION_OPEN_DOCUMENT auf, eine Datei auszuwählen. Die Datei wird dann als Nutzlast ParcelFileDescriptor gesendet. Der Dateiname wird auch als BYTES-Nutzlast gesendet.
private static final int READ_REQUEST_CODE = 42;
private static final String ENDPOINT_ID_EXTRA = "com.foo.myapp.EndpointId";
/**
* Fires an intent to spin up the file chooser UI and select an image for sending to endpointId.
*/
private void showImageChooser(String endpointId) {
Intent intent = new Intent(Intent.ACTION_OPEN_DOCUMENT);
intent.addCategory(Intent.CATEGORY_OPENABLE);
intent.setType("image/*");
intent.putExtra(ENDPOINT_ID_EXTRA, endpointId);
startActivityForResult(intent, READ_REQUEST_CODE);
}
@Override
public void onActivityResult(int requestCode, int resultCode, Intent resultData) {
super.onActivityResult(requestCode, resultCode, resultData);
if (requestCode == READ_REQUEST_CODE
&& resultCode == Activity.RESULT_OK
&& resultData != null) {
String endpointId = resultData.getStringExtra(ENDPOINT_ID_EXTRA);
// The URI of the file selected by the user.
Uri uri = resultData.getData();
Payload filePayload;
try {
// Open the ParcelFileDescriptor for this URI with read access.
ParcelFileDescriptor pfd = getContentResolver().openFileDescriptor(uri, "r");
filePayload = Payload.fromFile(pfd);
} catch (FileNotFoundException e) {
Log.e("MyApp", "File not found", e);
return;
}
// Construct a simple message mapping the ID of the file payload to the desired filename.
String filenameMessage = filePayload.getId() + ":" + uri.getLastPathSegment();
// Send the filename message as a bytes payload.
Payload filenameBytesPayload =
Payload.fromBytes(filenameMessage.getBytes(StandardCharsets.UTF_8));
Nearby.getConnectionsClient(context).sendPayload(endpointId, filenameBytesPayload);
// Finally, send the file payload.
Nearby.getConnectionsClient(context).sendPayload(endpointId, filePayload);
}
}
Da der Dateiname als Nutzlast gesendet wurde, kann unser Empfänger die Datei verschieben oder umbenennen, sodass sie die entsprechende Endung hat:
static class ReceiveFilePayloadCallback extends PayloadCallback {
private final Context context;
private final SimpleArrayMap<Long, Payload> incomingFilePayloads = new SimpleArrayMap<>();
private final SimpleArrayMap<Long, Payload> completedFilePayloads = new SimpleArrayMap<>();
private final SimpleArrayMap<Long, String> filePayloadFilenames = new SimpleArrayMap<>();
public ReceiveFilePayloadCallback(Context context) {
this.context = context;
}
@Override
public void onPayloadReceived(String endpointId, Payload payload) {
if (payload.getType() == Payload.Type.BYTES) {
String payloadFilenameMessage = new String(payload.asBytes(), StandardCharsets.UTF_8);
long payloadId = addPayloadFilename(payloadFilenameMessage);
processFilePayload(payloadId);
} else if (payload.getType() == Payload.Type.FILE) {
// Add this to our tracking map, so that we can retrieve the payload later.
incomingFilePayloads.put(payload.getId(), payload);
}
}
/**
* Extracts the payloadId and filename from the message and stores it in the
* filePayloadFilenames map. The format is payloadId:filename.
*/
private long addPayloadFilename(String payloadFilenameMessage) {
String[] parts = payloadFilenameMessage.split(":");
long payloadId = Long.parseLong(parts[0]);
String filename = parts[1];
filePayloadFilenames.put(payloadId, filename);
return payloadId;
}
private void processFilePayload(long payloadId) {
// BYTES and FILE could be received in any order, so we call when either the BYTES or the FILE
// payload is completely received. The file payload is considered complete only when both have
// been received.
Payload filePayload = completedFilePayloads.get(payloadId);
String filename = filePayloadFilenames.get(payloadId);
if (filePayload != null && filename != null) {
completedFilePayloads.remove(payloadId);
filePayloadFilenames.remove(payloadId);
// Get the received file (which will be in the Downloads folder)
// Because of https://developer.android.com/preview/privacy/scoped-storage, we are not
// allowed to access filepaths from another process directly. Instead, we must open the
// uri using our ContentResolver.
Uri uri = filePayload.asFile().asUri();
try {
// Copy the file to a new location.
InputStream in = context.getContentResolver().openInputStream(uri);
copyStream(in, new FileOutputStream(new File(context.getCacheDir(), filename)));
} catch (IOException e) {
// Log the error.
} finally {
// Delete the original file.
context.getContentResolver().delete(uri, null, null);
}
}
}
// add removed tag back to fix b/183037922
private void processFilePayload2(long payloadId) {
// BYTES and FILE could be received in any order, so we call when either the BYTES or the FILE
// payload is completely received. The file payload is considered complete only when both have
// been received.
Payload filePayload = completedFilePayloads.get(payloadId);
String filename = filePayloadFilenames.get(payloadId);
if (filePayload != null && filename != null) {
completedFilePayloads.remove(payloadId);
filePayloadFilenames.remove(payloadId);
// Get the received file (which will be in the Downloads folder)
if (VERSION.SDK_INT >= VERSION_CODES.Q) {
// Because of https://developer.android.com/preview/privacy/scoped-storage, we are not
// allowed to access filepaths from another process directly. Instead, we must open the
// uri using our ContentResolver.
Uri uri = filePayload.asFile().asUri();
try {
// Copy the file to a new location.
InputStream in = context.getContentResolver().openInputStream(uri);
copyStream(in, new FileOutputStream(new File(context.getCacheDir(), filename)));
} catch (IOException e) {
// Log the error.
} finally {
// Delete the original file.
context.getContentResolver().delete(uri, null, null);
}
} else {
File payloadFile = filePayload.asFile().asJavaFile();
// Rename the file.
payloadFile.renameTo(new File(payloadFile.getParentFile(), filename));
}
}
}
@Override
public void onPayloadTransferUpdate(String endpointId, PayloadTransferUpdate update) {
if (update.getStatus() == PayloadTransferUpdate.Status.SUCCESS) {
long payloadId = update.getPayloadId();
Payload payload = incomingFilePayloads.remove(payloadId);
completedFilePayloads.put(payloadId, payload);
if (payload.getType() == Payload.Type.FILE) {
processFilePayload(payloadId);
}
}
}
/** Copies a stream from one location to another. */
private static void copyStream(InputStream in, OutputStream out) throws IOException {
try {
byte[] buffer = new byte[1024];
int read;
while ((read = in.read(buffer)) != -1) {
out.write(buffer, 0, read);
}
out.flush();
} finally {
in.close();
out.close();
}
}
}
Stream
Streamnutzlasten sind geeignet, wenn Sie große Datenmengen, die in Echtzeit generiert werden, senden möchten, z. B. einen Audiostream. Erstellen Sie eine STREAM-Nutzlast durch Aufrufen von Payload.fromStream() und übergeben Sie entweder InputStream oder ParcelFileDescriptor. Beispiel:
URL url = new URL("https://developers.google.com/nearby/connections/android/exchange-data");
Payload streamPayload = Payload.fromStream(url.openStream());
Nearby.getConnectionsClient(context).sendPayload(toEndpointId, streamPayload);
Rufen Sie beim Empfänger payload.asStream().asInputStream() oder payload.asStream().asParcelFileDescriptor() in einem erfolgreichen onPayloadTransferUpdate-Callback auf:
static class ReceiveStreamPayloadCallback extends PayloadCallback {
private final SimpleArrayMap<Long, Thread> backgroundThreads = new SimpleArrayMap<>();
private static final long READ_STREAM_IN_BG_TIMEOUT = 5000;
@Override
public void onPayloadTransferUpdate(String endpointId, PayloadTransferUpdate update) {
if (backgroundThreads.containsKey(update.getPayloadId())
&& update.getStatus() != PayloadTransferUpdate.Status.IN_PROGRESS) {
backgroundThreads.get(update.getPayloadId()).interrupt();
}
}
@Override
public void onPayloadReceived(String endpointId, Payload payload) {
if (payload.getType() == Payload.Type.STREAM) {
// Read the available bytes in a while loop to free the stream pipe in time. Otherwise, the
// bytes will block the pipe and slow down the throughput.
Thread backgroundThread =
new Thread() {
@Override
public void run() {
InputStream inputStream = payload.asStream().asInputStream();
long lastRead = SystemClock.elapsedRealtime();
while (!Thread.interrupted()) {
if ((SystemClock.elapsedRealtime() - lastRead) >= READ_STREAM_IN_BG_TIMEOUT) {
Log.e("MyApp", "Read data from stream but timed out.");
break;
}
try {
int availableBytes = inputStream.available();
if (availableBytes > 0) {
byte[] bytes = new byte[availableBytes];
if (inputStream.read(bytes) == availableBytes) {
lastRead = SystemClock.elapsedRealtime();
// Do something with is here...
}
} else {
// Sleep or just continue.
}
} catch (IOException e) {
Log.e("MyApp", "Failed to read bytes from InputStream.", e);
break;
} // try-catch
} // while
}
};
backgroundThread.start();
backgroundThreads.put(payload.getId(), backgroundThread);
}
}
}
Bestellung mit mehreren Nutzlasten
Nutzlasten desselben Typs werden garantiert in der Reihenfolge zugestellt, in der sie gesendet wurden. Es gibt jedoch keine Garantie dafür, dass die Reihenfolge zwischen verschiedenen Nutzlasten beibehalten wird. Wenn ein Absender beispielsweise eine FILE-Nutzlast gefolgt von einer BYTE-Nutzlast sendet, könnte der Empfänger zuerst die BYTE-Nutzlast gefolgt von der FILE-Nutzlast abrufen.
Fortschrittsaktualisierungen
Die Methode onPayloadTransferUpdate() liefert Aktualisierungen zum Status eingehender und ausgehender Nutzlasten. In beiden Fällen ist dies eine Gelegenheit, den Fortschritt der Übertragung an den Nutzer anzuzeigen, z. B. mit einer Fortschrittsanzeige. Bei eingehenden Nutzlasten geben Aktualisierungen auch an, wenn neue Daten empfangen wurden.
Der folgende Beispielcode zeigt eine Möglichkeit, den Fortschritt des Eingangs und der ausgehenden Nutzlast von Benachrichtigungen anzuzeigen:
class ReceiveWithProgressCallback extends PayloadCallback {
private final SimpleArrayMap<Long, NotificationCompat.Builder> incomingPayloads =
new SimpleArrayMap<>();
private final SimpleArrayMap<Long, NotificationCompat.Builder> outgoingPayloads =
new SimpleArrayMap<>();
NotificationManager notificationManager =
(NotificationManager) context.getSystemService(Context.NOTIFICATION_SERVICE);
private void sendPayload(String endpointId, Payload payload) {
if (payload.getType() == Payload.Type.BYTES) {
// No need to track progress for bytes.
return;
}
// Build and start showing the notification.
NotificationCompat.Builder notification = buildNotification(payload, /*isIncoming=*/ false);
notificationManager.notify((int) payload.getId(), notification.build());
// Add it to the tracking list so we can update it.
outgoingPayloads.put(payload.getId(), notification);
}
private NotificationCompat.Builder buildNotification(Payload payload, boolean isIncoming) {
NotificationCompat.Builder notification =
new NotificationCompat.Builder(context)
.setContentTitle(isIncoming ? "Receiving..." : "Sending...");
boolean indeterminate = false;
if (payload.getType() == Payload.Type.STREAM) {
// We can only show indeterminate progress for stream payloads.
indeterminate = true;
}
notification.setProgress(100, 0, indeterminate);
return notification;
}
@Override
public void onPayloadReceived(String endpointId, Payload payload) {
if (payload.getType() == Payload.Type.BYTES) {
// No need to track progress for bytes.
return;
}
// Build and start showing the notification.
NotificationCompat.Builder notification = buildNotification(payload, true /*isIncoming*/);
notificationManager.notify((int) payload.getId(), notification.build());
// Add it to the tracking list so we can update it.
incomingPayloads.put(payload.getId(), notification);
}
@Override
public void onPayloadTransferUpdate(String endpointId, PayloadTransferUpdate update) {
long payloadId = update.getPayloadId();
NotificationCompat.Builder notification = null;
if (incomingPayloads.containsKey(payloadId)) {
notification = incomingPayloads.get(payloadId);
if (update.getStatus() != PayloadTransferUpdate.Status.IN_PROGRESS) {
// This is the last update, so we no longer need to keep track of this notification.
incomingPayloads.remove(payloadId);
}
} else if (outgoingPayloads.containsKey(payloadId)) {
notification = outgoingPayloads.get(payloadId);
if (update.getStatus() != PayloadTransferUpdate.Status.IN_PROGRESS) {
// This is the last update, so we no longer need to keep track of this notification.
outgoingPayloads.remove(payloadId);
}
}
if (notification == null) {
return;
}
switch (update.getStatus()) {
case PayloadTransferUpdate.Status.IN_PROGRESS:
long size = update.getTotalBytes();
if (size == -1) {
// This is a stream payload, so we don't need to update anything at this point.
return;
}
int percentTransferred =
(int) (100.0 * (update.getBytesTransferred() / (double) update.getTotalBytes()));
notification.setProgress(100, percentTransferred, /* indeterminate= */ false);
break;
case PayloadTransferUpdate.Status.SUCCESS:
// SUCCESS always means that we transferred 100%.
notification
.setProgress(100, 100, /* indeterminate= */ false)
.setContentText("Transfer complete!");
break;
case PayloadTransferUpdate.Status.FAILURE:
case PayloadTransferUpdate.Status.CANCELED:
notification.setProgress(0, 0, false).setContentText("Transfer failed");
break;
default:
// Unknown status.
}
notificationManager.notify((int) payloadId, notification.build());
}
}