| // Copyright 2021 Google LLC |
| // |
| // Licensed under the Apache License, Version 2.0 (the "License"); |
| // you may not use this file except in compliance with the License. |
| // You may obtain a copy of the License at |
| // |
| // https://www.apache.org/licenses/LICENSE-2.0 |
| // |
| // Unless required by applicable law or agreed to in writing, software |
| // distributed under the License is distributed on an "AS IS" BASIS, |
| // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| // See the License for the specific language governing permissions and |
| // limitations under the License. |
| |
| #ifndef CORE_LISTENERS_H_ |
| #define CORE_LISTENERS_H_ |
| |
| #include <cstdint> |
| #include <functional> |
| #include <memory> |
| #include <string> |
| |
| // This file defines all the protocol listeners and their parameter structures. |
| // Listeners are defined as collections of std::function<T> instances, which is |
| // more flexible than a virtual function: |
| // - a subset of listener callbacks may be overridden, while others may remain |
| // default-initialized. |
| // - callbacks may be initialized with lambdas; lambda definitions are concize. |
| |
| #include "connections/connection_options.h" |
| #include "connections/payload.h" |
| #include "connections/status.h" |
| #include "internal/platform/byte_array.h" |
| #include "internal/platform/byte_utils.h" |
| #include "internal/platform/listeners.h" |
| #include "internal/platform/core_config.h" |
| |
| namespace location { |
| namespace nearby { |
| namespace connections { |
| |
| // Common callback for asynchronously invoked methods. |
| // Called after a job scheduled for execution is completed. |
| // This is not the same as completion of the associated process, |
| // which may have many states, and multiple async jobs, and be still ongoing. |
| // Progress on the overall process is reported by the associated listener. |
| struct DLL_API ResultCallback { |
| // Callback to access the status of the operation when available. |
| // status - result of job execution; |
| // Status::kSuccess, if successful; anything else indicates failure. |
| std::function<void(Status)> result_cb = DefaultCallback<Status>(); |
| }; |
| |
| struct DLL_API ConnectionResponseInfo { |
| std::string GetAuthenticationDigits() { |
| return ByteUtils::ToFourDigitString(raw_authentication_token); |
| } |
| |
| ByteArray remote_endpoint_info; |
| std::string authentication_token; |
| ByteArray raw_authentication_token; |
| bool is_incoming_connection = false; |
| bool is_connection_verified = false; |
| }; |
| |
| struct DLL_API PayloadProgressInfo { |
| std::int64_t payload_id = 0; |
| enum class Status { |
| kSuccess, |
| kFailure, |
| kInProgress, |
| kCanceled, |
| } status = Status::kSuccess; |
| std::int64_t total_bytes = 0; |
| std::int64_t bytes_transferred = 0; |
| }; |
| |
| enum class DLL_API DistanceInfo { |
| kUnknown = 1, |
| kVeryClose = 2, |
| kClose = 3, |
| kFar = 4, |
| }; |
| |
| struct DLL_API ConnectionListener { |
| // A basic encrypted channel has been created between you and the endpoint. |
| // Both sides are now asked if they wish to accept or reject the connection |
| // before any data can be sent over this channel. |
| // |
| // This is your chance, before you accept the connection, to confirm that you |
| // connected to the correct device. Both devices are given an identical token; |
| // it's up to you to decide how to verify it before proceeding. Typically this |
| // involves showing the token on both devices and having the users manually |
| // compare and confirm; however, this is only required if you desire a secure |
| // connection between the devices. |
| // |
| // Whichever route you decide to take (including not authenticating the other |
| // device), call Core::AcceptConnection() when you're ready to talk, or |
| // Core::RejectConnection() to close the connection. |
| // |
| // endpoint_id - The identifier for the remote endpoint. |
| // info - Other relevant information about the connection. |
| std::function<void(const std::string& endpoint_id, |
| const ConnectionResponseInfo& info)> |
| initiated_cb = |
| DefaultCallback<const std::string&, const ConnectionResponseInfo&>(); |
| |
| // Called after both sides have accepted the connection. |
| // Both sides may now send Payloads to each other. |
| // Call Core::SendPayload() or wait for incoming PayloadListener::OnPayload(). |
| // |
| // endpoint_id - The identifier for the remote endpoint. |
| std::function<void(const std::string& endpoint_id)> accepted_cb = |
| DefaultCallback<const std::string&>(); |
| |
| // Called when either side rejected the connection. |
| // Payloads can not be exchaged. Call Core::DisconnectFromEndpoint() |
| // to terminate connection. |
| // |
| // endpoint_id - The identifier for the remote endpoint. |
| std::function<void(const std::string& endpoint_id, Status status)> |
| rejected_cb = DefaultCallback<const std::string&, Status>(); |
| |
| // Called when a remote endpoint is disconnected or has become unreachable. |
| // At this point service (re-)discovery may start again. |
| // |
| // endpoint_id - The identifier for the remote endpoint. |
| std::function<void(const std::string& endpoint_id)> disconnected_cb = |
| DefaultCallback<const std::string&>(); |
| |
| // Called when the connection's available bandwidth has changed. |
| // |
| // endpoint_id - The identifier for the remote endpoint. |
| // medium - Medium we upgraded to. |
| std::function<void(const std::string& endpoint_id, Medium medium)> |
| bandwidth_changed_cb = DefaultCallback<const std::string&, Medium>(); |
| }; |
| |
| struct DLL_API DiscoveryListener { |
| // Called when a remote endpoint is discovered. |
| // |
| // endpoint_id - The ID of the remote endpoint that was discovered. |
| // endpoint_info - The info of the remote endpoint representd by ByteArray. |
| // service_id - The ID of the service advertised by the remote endpoint. |
| std::function<void(const std::string& endpoint_id, |
| const ByteArray& endpoint_info, |
| const std::string& service_id)> |
| endpoint_found_cb = DefaultCallback<const std::string&, const ByteArray&, |
| const std::string&>(); |
| |
| // Called when a remote endpoint is no longer discoverable; only called for |
| // endpoints that previously had been passed to {@link |
| // #onEndpointFound(String, DiscoveredEndpointInfo)}. |
| // |
| // endpoint_id - The ID of the remote endpoint that was lost. |
| std::function<void(const std::string& endpoint_id)> endpoint_lost_cb = |
| DefaultCallback<const std::string&>(); |
| |
| // Called when a remote endpoint is found with an updated distance. |
| // |
| // arguments: |
| // endpoint_id - The ID of the remote endpoint that was lost. |
| // info - The distance info, encoded as enum value. |
| std::function<void(const std::string& endpoint_id, DistanceInfo info)> |
| endpoint_distance_changed_cb = |
| DefaultCallback<const std::string&, DistanceInfo>(); |
| }; |
| |
| struct DLL_API PayloadListener { |
| // Called when a Payload is received from a remote endpoint. Depending |
| // on the type of the Payload, all of the data may or may not have been |
| // received at the time of this call. Use OnPayloadProgress() to |
| // get updates on the status of the data received. |
| // |
| // endpoint_id - The identifier for the remote endpoint that sent the |
| // payload. |
| // payload - The Payload object received. |
| std::function<void(const std::string& endpoint_id, Payload payload)> |
| payload_cb = DefaultCallback<const std::string&, Payload>(); |
| |
| // Called with progress information about an active Payload transfer, either |
| // incoming or outgoing. |
| // |
| // endpoint_id - The identifier for the remote endpoint that is sending or |
| // receiving this payload. |
| // info - The PayloadProgressInfo structure describing the status of |
| // the transfer. |
| std::function<void(const std::string& endpoint_id, |
| const PayloadProgressInfo& info)> |
| payload_progress_cb = |
| DefaultCallback<const std::string&, const PayloadProgressInfo&>(); |
| }; |
| |
| } // namespace connections |
| } // namespace nearby |
| } // namespace location |
| |
| #endif // CORE_LISTENERS_H_ |