在设备之间建立连接后，您可以通过发送和接收 Payload 对象来交换数据。Payload 可以表示简单的字节型数组（如短信）、文件（如照片或视频）或流（如来自设备麦克风的音频流）。
载荷使用 sendPayload() 方法发送，并且会在传递到 acceptConnection() 的实现中接收并传递给 acceptConnection()（如管理连接中所述）。
载荷类型
字节
字节载荷是最简单的载荷类型。适合发送不超过 Connections.MAX_BYTES_DATA_SIZE 大小的消息或元数据等简单数据。以下是发送 BYTES 载荷的示例：
Payload bytesPayload = Payload.fromBytes(new byte[] {0xa, 0xb, 0xc, 0xd});
Nearby.getConnectionsClient(context).sendPayload(toEndpointId, bytesPayload);
实现您传递给 acceptConnection() 的 PayloadCallback 的 onPayloadReceived() 方法，以接收 BYTES 载荷。
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().
}
}
与 FILE 和 STREAM 载荷不同，BYTES 载荷会作为单个分块发送，因此无需等待 SUCCESS 更新（但仍会在调用 onPayloadReceived() 后立即传送）。相反，您可以在调用 onPayloadReceived() 后，安全地调用 payload.asBytes() 以获取载荷的完整数据。
文件
文件载荷是根据本地设备上存储的文件（例如照片或视频文件）创建的。以下是发送 FILE 载荷的简单示例：
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);
}
使用 ParcelFileDescriptor 创建 FILES 载荷（例如，如果来自 ContentResolver 的载荷）效率更高。这样可以最大限度地减少复制文件的字节：
ParcelFileDescriptor pfd = getContentResolver().openFileDescriptor(uri, "r"); filePayload = Payload.fromFile(pfd);
我们收到文件后，系统会将其保存到接收者设备上的“下载”文件夹 (DIRECTORY_DOWNLOADS) 中，该文件采用通用名称且无扩展名。转移完成后（通过调用 onPayloadTransferUpdate() 使用 PayloadTransferUpdate.Status.SUCCESS 指示），您可以检索 File 对象，如果您的应用以低于 Q 的设备为目标：
File payloadFile = filePayload.asFile().asJavaFile(); // Rename the file. payloadFile.renameTo(new File(payloadFile.getParentFile(), filename));
如果您的应用以 Android Q 设备为目标平台，则可以在清单的应用元素中添加 android:requestLegacyExternalStorage="true"，以便继续使用先前的代码。
否则，对于 Q+，您需要遵守 Scoped Storage 规则并使用从服务传递的 URI 访问收到的文件。
// 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);
}
在下面这个更复杂的示例中，ACTION_OPEN_DOCUMENT intent 会提示用户选择文件，并使用 ParcelFileDescriptor 高效地将该文件作为载荷发送。文件名还会以 BYTES 载荷的形式发送。
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);
}
}
由于文件名作为载荷发送，我们的接收方可以移动或重命名文件，以便使用相应的扩展名：
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();
}
}
}
视频流
当您想要发送大量实时生成的数据（例如音频流）时，流载荷非常适用。通过调用 Payload.fromStream() 并传入 InputStream 或 ParcelFileDescriptor，创建 STREAM 载荷。例如：
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);
在收件人上，在成功的 onPayloadTransferUpdate 回调中调用 payload.asStream().asInputStream() 或 payload.asStream().asParcelFileDescriptor()：
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);
}
}
}
使用多个载荷排序
同一类型的载荷一定会按照其发送顺序到达，但无法保证在不同类型的载荷之间保持排序。例如，如果发送者先发送 FILE 载荷，然后发送 BYTE 载荷，则接收器可以先获取 BYTE 载荷，然后再获取 FILE 载荷。
进度更新
onPayloadTransferUpdate() 方法可提供有关传入和传出载荷进度的更新。在这两种情况下，都有机会向用户显示转移进度，例如，通过进度条向用户显示。对于传入的载荷，更新还会指示何时收到新数据。
以下示例代码演示了通过通知显示传入和传出载荷进度的方法：
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());
}
}