https://source.android.com/ 
/*
 * Copyright (C) 2016 The Android Open Source Project
 *
 * 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
 *
 *      http://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.
 */

package android.net.wifi.aware;

import android.annotation.NonNull;

import java.util.List;


Base class for Aware session events callbacks. Should be extended by applications wanting notifications. The callbacks are set when a publish or subscribe session is created using WifiAwareSession.publish(PublishConfig, DiscoverySessionCallback, Handler) or WifiAwareSession.subscribe(SubscribeConfig, DiscoverySessionCallback, Handler). 

A single callback is set at session creation - it cannot be replaced.

/**
 * Base class for Aware session events callbacks. Should be extended by
 * applications wanting notifications. The callbacks are set when a
 * publish or subscribe session is created using
 * {@link WifiAwareSession#publish(PublishConfig, DiscoverySessionCallback,
 * android.os.Handler)} or
 * {@link WifiAwareSession#subscribe(SubscribeConfig, DiscoverySessionCallback,
 * android.os.Handler)}.
 * <p>
 * A single callback is set at session creation - it cannot be replaced.
 */
public class DiscoverySessionCallback {
    
Called when a publish operation is started successfully in response to a WifiAwareSession.publish(PublishConfig, DiscoverySessionCallback, Handler) operation. 
Params:
/**
     * Called when a publish operation is started successfully in response to a
     * {@link WifiAwareSession#publish(PublishConfig, DiscoverySessionCallback,
     * android.os.Handler)} operation.
     *
     * @param session The {@link PublishDiscoverySession} used to control the
     *            discovery session.
     */
    public void onPublishStarted(@NonNull PublishDiscoverySession session) {
        /* empty */
    }

    
Called when a subscribe operation is started successfully in response to a WifiAwareSession.subscribe(SubscribeConfig, DiscoverySessionCallback, Handler) operation. 
Params:
/**
     * Called when a subscribe operation is started successfully in response to a
     * {@link WifiAwareSession#subscribe(SubscribeConfig, DiscoverySessionCallback,
     * android.os.Handler)} operation.
     *
     * @param session The {@link SubscribeDiscoverySession} used to control the
     *            discovery session.
     */
    public void onSubscribeStarted(@NonNull SubscribeDiscoverySession session) {
        /* empty */
    }

    
Called when a publish or subscribe discovery session configuration update request succeeds. Called in response to PublishDiscoverySession.updatePublish(PublishConfig) or SubscribeDiscoverySession.updateSubscribe(SubscribeConfig). 
/**
     * Called when a publish or subscribe discovery session configuration update request
     * succeeds. Called in response to
     * {@link PublishDiscoverySession#updatePublish(PublishConfig)} or
     * {@link SubscribeDiscoverySession#updateSubscribe(SubscribeConfig)}.
     */
    public void onSessionConfigUpdated() {
        /* empty */
    }

    
Called when a publish or subscribe discovery session cannot be created: WifiAwareSession.publish(PublishConfig, DiscoverySessionCallback, Handler) or WifiAwareSession.subscribe(SubscribeConfig, DiscoverySessionCallback, Handler), or when a configuration update fails: PublishDiscoverySession.updatePublish(PublishConfig) or SubscribeDiscoverySession.updateSubscribe(SubscribeConfig). 

    For discovery session updates failure leaves the session running with its previous
    configuration - the discovery session is not terminated.

/**
     * Called when a publish or subscribe discovery session cannot be created:
     * {@link WifiAwareSession#publish(PublishConfig, DiscoverySessionCallback,
     * android.os.Handler)} or
     * {@link WifiAwareSession#subscribe(SubscribeConfig, DiscoverySessionCallback,
     * android.os.Handler)}, or when a configuration update fails:
     * {@link PublishDiscoverySession#updatePublish(PublishConfig)} or
     * {@link SubscribeDiscoverySession#updateSubscribe(SubscribeConfig)}.
     * <p>
     *     For discovery session updates failure leaves the session running with its previous
     *     configuration - the discovery session is not terminated.
     */
    public void onSessionConfigFailed() {
        /* empty */
    }

    
Called when a discovery session (publish or subscribe) terminates. Termination may be due to user-request (either directly through DiscoverySession.close() or application-specified expiration, e.g. Builder.setTtlSec(int) or Builder.setTtlSec(int)). 
/**
     * Called when a discovery session (publish or subscribe) terminates. Termination may be due
     * to user-request (either directly through {@link DiscoverySession#close()} or
     * application-specified expiration, e.g. {@link PublishConfig.Builder#setTtlSec(int)}
     * or {@link SubscribeConfig.Builder#setTtlSec(int)}).
     */
    public void onSessionTerminated() {
        /* empty */
    }

    
Called when a discovery (publish or subscribe) operation results in a
service discovery.

 Note that this method and onServiceDiscoveredWithinRange(PeerHandle, byte[], List<byte[]>, int) may be called multiple times per service discovery. 
Params:
/**
     * Called when a discovery (publish or subscribe) operation results in a
     * service discovery.
     * <p>
     * Note that this method and
     * {@link #onServiceDiscoveredWithinRange(PeerHandle, byte[], List, int)} may be called
     * multiple times per service discovery.
     *
     * @param peerHandle An opaque handle to the peer matching our discovery operation.
     * @param serviceSpecificInfo The service specific information (arbitrary
     *            byte array) provided by the peer as part of its discovery
     *            configuration.
     * @param matchFilter The filter which resulted in this service discovery. For
     * {@link PublishConfig#PUBLISH_TYPE_UNSOLICITED},
     * {@link SubscribeConfig#SUBSCRIBE_TYPE_PASSIVE} discovery sessions this is the publisher's
     *                    match filter. For {@link PublishConfig#PUBLISH_TYPE_SOLICITED},
     *                    {@link SubscribeConfig#SUBSCRIBE_TYPE_ACTIVE} discovery sessions this
     *                    is the subscriber's match filter.
     */
    public void onServiceDiscovered(PeerHandle peerHandle,
            byte[] serviceSpecificInfo, List<byte[]> matchFilter) {
        /* empty */
    }

    
Called when a discovery (publish or subscribe) operation results in a service discovery. Called when a Subscribe service was configured with a range requirement Builder.setMinDistanceMm(int) and/or Builder.setMaxDistanceMm(int) and the Publish service was configured with Builder.setRangingEnabled(boolean). 
 If either Publisher or Subscriber does not enable Ranging, or if Ranging is temporarily disabled by the underlying device, service discovery proceeds without ranging and the onServiceDiscovered(PeerHandle, byte[], List<byte[]>) is called. 
 Note that this method and onServiceDiscovered(PeerHandle, byte[], List<byte[]>) may be called multiple times per service discovery. 
Params:
/**
     * Called when a discovery (publish or subscribe) operation results in a
     * service discovery. Called when a Subscribe service was configured with a range requirement
     * {@link SubscribeConfig.Builder#setMinDistanceMm(int)} and/or
     * {@link SubscribeConfig.Builder#setMaxDistanceMm(int)} and the Publish service was configured
     * with {@link PublishConfig.Builder#setRangingEnabled(boolean)}.
     * <p>
     * If either Publisher or Subscriber does not enable Ranging, or if Ranging is temporarily
     * disabled by the underlying device, service discovery proceeds without ranging and the
     * {@link #onServiceDiscovered(PeerHandle, byte[], List)} is called.
     * <p>
     * Note that this method and {@link #onServiceDiscovered(PeerHandle, byte[], List)} may be
     * called multiple times per service discovery.
     *
     * @param peerHandle An opaque handle to the peer matching our discovery operation.
     * @param serviceSpecificInfo The service specific information (arbitrary
     *            byte array) provided by the peer as part of its discovery
     *            configuration.
     * @param matchFilter The filter which resulted in this service discovery. For
     * {@link PublishConfig#PUBLISH_TYPE_UNSOLICITED},
     * {@link SubscribeConfig#SUBSCRIBE_TYPE_PASSIVE} discovery sessions this is the publisher's
     *                    match filter. For {@link PublishConfig#PUBLISH_TYPE_SOLICITED},
     *                    {@link SubscribeConfig#SUBSCRIBE_TYPE_ACTIVE} discovery sessions this
     *                    is the subscriber's match filter.
     * @param distanceMm The measured distance to the Publisher in mm. Note: the measured distance
     *                   may be negative for very close devices.
     */
    public void onServiceDiscoveredWithinRange(PeerHandle peerHandle,
        byte[] serviceSpecificInfo, List<byte[]> matchFilter, int distanceMm) {
        /* empty */
    }

    
Called in response to DiscoverySession.sendMessage(PeerHandle, int, byte[]) when a message is transmitted successfully - i.e. when it was received successfully by the peer (corresponds to an ACK being received). 
 Note that either this callback or onMessageSendFailed(int) will be received - never both. 
Params:
  • messageId – The arbitrary message ID specified when sending the message.
/**
     * Called in response to
     * {@link DiscoverySession#sendMessage(PeerHandle, int, byte[])}
     * when a message is transmitted successfully - i.e. when it was received successfully by the
     * peer (corresponds to an ACK being received).
     * <p>
     * Note that either this callback or
     * {@link DiscoverySessionCallback#onMessageSendFailed(int)} will be
     * received - never both.
     *
     * @param messageId The arbitrary message ID specified when sending the message.
     */
    public void onMessageSendSucceeded(@SuppressWarnings("unused") int messageId) {
        /* empty */
    }

    
Called when message transmission initiated with DiscoverySession.sendMessage(PeerHandle, int, byte[]) fails. E.g. when no ACK is received from the peer. 
 Note that either this callback or onMessageSendSucceeded(int) will be received - never both. 
Params:
  • messageId – The arbitrary message ID specified when sending the message.
/**
     * Called when message transmission initiated with
     * {@link DiscoverySession#sendMessage(PeerHandle, int, byte[])} fails. E.g. when no ACK is
     * received from the peer.
     * <p>
     * Note that either this callback or
     * {@link DiscoverySessionCallback#onMessageSendSucceeded(int)} will be received
     * - never both.
     *
     * @param messageId The arbitrary message ID specified when sending the message.
     */
    public void onMessageSendFailed(@SuppressWarnings("unused") int messageId) {
        /* empty */
    }

    
Called when a message is received from a discovery session peer - in response to the peer's DiscoverySession.sendMessage(PeerHandle, int, byte[]). 
Params:
  • peerHandle – An opaque handle to the peer matching our discovery operation.
  • message – A byte array containing the message.
/**
     * Called when a message is received from a discovery session peer - in response to the
     * peer's {@link DiscoverySession#sendMessage(PeerHandle, int, byte[])}.
     *
     * @param peerHandle An opaque handle to the peer matching our discovery operation.
     * @param message A byte array containing the message.
     */
    public void onMessageReceived(PeerHandle peerHandle, byte[] message) {
        /* empty */
    }
}