| /* |
| * 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.IntDef; |
| import android.annotation.NonNull; |
| import android.annotation.Nullable; |
| import android.os.Parcel; |
| import android.os.Parcelable; |
| |
| import libcore.util.HexEncoding; |
| |
| import java.lang.annotation.Retention; |
| import java.lang.annotation.RetentionPolicy; |
| import java.nio.charset.StandardCharsets; |
| import java.util.Arrays; |
| import java.util.List; |
| |
| /** |
| * Defines the configuration of a Aware subscribe session. Built using |
| * {@link SubscribeConfig.Builder}. Subscribe is done using |
| * {@link WifiAwareSession#subscribe(SubscribeConfig, DiscoverySessionCallback, |
| * android.os.Handler)} or |
| * {@link SubscribeDiscoverySession#updateSubscribe(SubscribeConfig)}. |
| */ |
| public final class SubscribeConfig implements Parcelable { |
| /** @hide */ |
| @IntDef({ |
| SUBSCRIBE_TYPE_PASSIVE, SUBSCRIBE_TYPE_ACTIVE }) |
| @Retention(RetentionPolicy.SOURCE) |
| public @interface SubscribeTypes { |
| } |
| |
| /** |
| * Defines a passive subscribe session - a subscribe session where |
| * subscribe packets are not transmitted over-the-air and the device listens |
| * and matches to transmitted publish packets. Configuration is done using |
| * {@link SubscribeConfig.Builder#setSubscribeType(int)}. |
| */ |
| public static final int SUBSCRIBE_TYPE_PASSIVE = 0; |
| |
| /** |
| * Defines an active subscribe session - a subscribe session where |
| * subscribe packets are transmitted over-the-air. Configuration is done |
| * using {@link SubscribeConfig.Builder#setSubscribeType(int)}. |
| */ |
| public static final int SUBSCRIBE_TYPE_ACTIVE = 1; |
| |
| /** @hide */ |
| @IntDef({ |
| MATCH_STYLE_FIRST_ONLY, MATCH_STYLE_ALL }) |
| @Retention(RetentionPolicy.SOURCE) |
| public @interface MatchStyles { |
| } |
| |
| /** |
| * Specifies that only the first match of a set of identical matches (same |
| * publish) will be reported to the subscriber. Configuration is done using |
| * {@link SubscribeConfig.Builder#setMatchStyle(int)}. |
| */ |
| public static final int MATCH_STYLE_FIRST_ONLY = 0; |
| |
| /** |
| * Specifies that all matches of a set of identical matches (same publish) |
| * will be reported to the subscriber. Configuration is done using |
| * {@link SubscribeConfig.Builder#setMatchStyle(int)}. |
| */ |
| public static final int MATCH_STYLE_ALL = 1; |
| |
| /** @hide */ |
| public final byte[] mServiceName; |
| |
| /** @hide */ |
| public final byte[] mServiceSpecificInfo; |
| |
| /** @hide */ |
| public final byte[] mMatchFilter; |
| |
| /** @hide */ |
| public final int mSubscribeType; |
| |
| /** @hide */ |
| public final int mTtlSec; |
| |
| /** @hide */ |
| public final int mMatchStyle; |
| |
| /** @hide */ |
| public final boolean mEnableTerminateNotification; |
| |
| /** @hide */ |
| public SubscribeConfig(byte[] serviceName, byte[] serviceSpecificInfo, byte[] matchFilter, |
| int subscribeType, int ttlSec, int matchStyle, |
| boolean enableTerminateNotification) { |
| mServiceName = serviceName; |
| mServiceSpecificInfo = serviceSpecificInfo; |
| mMatchFilter = matchFilter; |
| mSubscribeType = subscribeType; |
| mTtlSec = ttlSec; |
| mMatchStyle = matchStyle; |
| mEnableTerminateNotification = enableTerminateNotification; |
| } |
| |
| @Override |
| public String toString() { |
| return "SubscribeConfig [mServiceName='" + mServiceName + ", mServiceSpecificInfo='" + ( |
| (mServiceSpecificInfo == null) ? "null" : HexEncoding.encode(mServiceSpecificInfo)) |
| + ", mMatchFilter=" + (new TlvBufferUtils.TlvIterable(0, 1, |
| mMatchFilter)).toString() + ", mSubscribeType=" + mSubscribeType |
| + ", mTtlSec=" + mTtlSec + ", mMatchType=" |
| + mMatchStyle + ", mEnableTerminateNotification=" + mEnableTerminateNotification |
| + "]"; |
| } |
| |
| @Override |
| public int describeContents() { |
| return 0; |
| } |
| |
| @Override |
| public void writeToParcel(Parcel dest, int flags) { |
| dest.writeByteArray(mServiceName); |
| dest.writeByteArray(mServiceSpecificInfo); |
| dest.writeByteArray(mMatchFilter); |
| dest.writeInt(mSubscribeType); |
| dest.writeInt(mTtlSec); |
| dest.writeInt(mMatchStyle); |
| dest.writeInt(mEnableTerminateNotification ? 1 : 0); |
| } |
| |
| public static final Creator<SubscribeConfig> CREATOR = new Creator<SubscribeConfig>() { |
| @Override |
| public SubscribeConfig[] newArray(int size) { |
| return new SubscribeConfig[size]; |
| } |
| |
| @Override |
| public SubscribeConfig createFromParcel(Parcel in) { |
| byte[] serviceName = in.createByteArray(); |
| byte[] ssi = in.createByteArray(); |
| byte[] matchFilter = in.createByteArray(); |
| int subscribeType = in.readInt(); |
| int ttlSec = in.readInt(); |
| int matchStyle = in.readInt(); |
| boolean enableTerminateNotification = in.readInt() != 0; |
| |
| return new SubscribeConfig(serviceName, ssi, matchFilter, subscribeType, |
| ttlSec, matchStyle, enableTerminateNotification); |
| } |
| }; |
| |
| @Override |
| public boolean equals(Object o) { |
| if (this == o) { |
| return true; |
| } |
| |
| if (!(o instanceof SubscribeConfig)) { |
| return false; |
| } |
| |
| SubscribeConfig lhs = (SubscribeConfig) o; |
| |
| return Arrays.equals(mServiceName, lhs.mServiceName) && Arrays.equals(mServiceSpecificInfo, |
| lhs.mServiceSpecificInfo) && Arrays.equals(mMatchFilter, lhs.mMatchFilter) |
| && mSubscribeType == lhs.mSubscribeType |
| && mTtlSec == lhs.mTtlSec && mMatchStyle == lhs.mMatchStyle |
| && mEnableTerminateNotification == lhs.mEnableTerminateNotification; |
| } |
| |
| @Override |
| public int hashCode() { |
| int result = 17; |
| |
| result = 31 * result + Arrays.hashCode(mServiceName); |
| result = 31 * result + Arrays.hashCode(mServiceSpecificInfo); |
| result = 31 * result + Arrays.hashCode(mMatchFilter); |
| result = 31 * result + mSubscribeType; |
| result = 31 * result + mTtlSec; |
| result = 31 * result + mMatchStyle; |
| result = 31 * result + (mEnableTerminateNotification ? 1 : 0); |
| |
| return result; |
| } |
| |
| /** |
| * Verifies that the contents of the SubscribeConfig are valid. Otherwise |
| * throws an IllegalArgumentException. |
| * |
| * @hide |
| */ |
| public void assertValid(Characteristics characteristics) |
| throws IllegalArgumentException { |
| WifiAwareUtils.validateServiceName(mServiceName); |
| |
| if (!TlvBufferUtils.isValid(mMatchFilter, 0, 1)) { |
| throw new IllegalArgumentException( |
| "Invalid matchFilter configuration - LV fields do not match up to length"); |
| } |
| if (mSubscribeType < SUBSCRIBE_TYPE_PASSIVE || mSubscribeType > SUBSCRIBE_TYPE_ACTIVE) { |
| throw new IllegalArgumentException("Invalid subscribeType - " + mSubscribeType); |
| } |
| if (mTtlSec < 0) { |
| throw new IllegalArgumentException("Invalid ttlSec - must be non-negative"); |
| } |
| if (mMatchStyle != MATCH_STYLE_FIRST_ONLY && mMatchStyle != MATCH_STYLE_ALL) { |
| throw new IllegalArgumentException( |
| "Invalid matchType - must be MATCH_FIRST_ONLY or MATCH_ALL"); |
| } |
| |
| if (characteristics != null) { |
| int maxServiceNameLength = characteristics.getMaxServiceNameLength(); |
| if (maxServiceNameLength != 0 && mServiceName.length > maxServiceNameLength) { |
| throw new IllegalArgumentException( |
| "Service name longer than supported by device characteristics"); |
| } |
| int maxServiceSpecificInfoLength = characteristics.getMaxServiceSpecificInfoLength(); |
| if (maxServiceSpecificInfoLength != 0 && mServiceSpecificInfo != null |
| && mServiceSpecificInfo.length > maxServiceSpecificInfoLength) { |
| throw new IllegalArgumentException( |
| "Service specific info longer than supported by device characteristics"); |
| } |
| int maxMatchFilterLength = characteristics.getMaxMatchFilterLength(); |
| if (maxMatchFilterLength != 0 && mMatchFilter != null |
| && mMatchFilter.length > maxMatchFilterLength) { |
| throw new IllegalArgumentException( |
| "Match filter longer than supported by device characteristics"); |
| } |
| } |
| } |
| |
| /** |
| * Builder used to build {@link SubscribeConfig} objects. |
| */ |
| public static final class Builder { |
| private byte[] mServiceName; |
| private byte[] mServiceSpecificInfo; |
| private byte[] mMatchFilter; |
| private int mSubscribeType = SUBSCRIBE_TYPE_PASSIVE; |
| private int mTtlSec = 0; |
| private int mMatchStyle = MATCH_STYLE_ALL; |
| private boolean mEnableTerminateNotification = true; |
| |
| /** |
| * Specify the service name of the subscribe session. The actual on-air |
| * value is a 6 byte hashed representation of this string. |
| * <p> |
| * The Service Name is a UTF-8 encoded string from 1 to 255 bytes in length. |
| * The only acceptable single-byte UTF-8 symbols for a Service Name are alphanumeric |
| * values (A-Z, a-z, 0-9), the hyphen ('-'), and the period ('.'). All valid multi-byte |
| * UTF-8 characters are acceptable in a Service Name. |
| * <p> |
| * Must be called - an empty ServiceName is not valid. |
| * |
| * @param serviceName The service name for the subscribe session. |
| * |
| * @return The builder to facilitate chaining |
| * {@code builder.setXXX(..).setXXX(..)}. |
| */ |
| public Builder setServiceName(@NonNull String serviceName) { |
| if (serviceName == null) { |
| throw new IllegalArgumentException("Invalid service name - must be non-null"); |
| } |
| mServiceName = serviceName.getBytes(StandardCharsets.UTF_8); |
| return this; |
| } |
| |
| /** |
| * Specify service specific information for the subscribe session. This is |
| * a free-form byte array available to the application to send |
| * additional information as part of the discovery operation - i.e. it |
| * will not be used to determine whether a publish/subscribe match |
| * occurs. |
| * <p> |
| * Optional. Empty by default. |
| * |
| * @param serviceSpecificInfo A byte-array for the service-specific |
| * information field. |
| * |
| * @return The builder to facilitate chaining |
| * {@code builder.setXXX(..).setXXX(..)}. |
| */ |
| public Builder setServiceSpecificInfo(@Nullable byte[] serviceSpecificInfo) { |
| mServiceSpecificInfo = serviceSpecificInfo; |
| return this; |
| } |
| |
| /** |
| * The match filter for a subscribe session. Used to determine whether a service |
| * discovery occurred - in addition to relying on the service name. |
| * <p> |
| * Optional. Empty by default. |
| * |
| * @param matchFilter A list of match filter entries (each of which is an arbitrary byte |
| * array). |
| * |
| * @return The builder to facilitate chaining |
| * {@code builder.setXXX(..).setXXX(..)}. |
| */ |
| public Builder setMatchFilter(@Nullable List<byte[]> matchFilter) { |
| mMatchFilter = new TlvBufferUtils.TlvConstructor(0, 1).allocateAndPut( |
| matchFilter).getArray(); |
| return this; |
| } |
| |
| /** |
| * Sets the type of the subscribe session: active (subscribe packets are |
| * transmitted over-the-air), or passive (no subscribe packets are |
| * transmitted, a match is made against a solicited/active publish |
| * session whose packets are transmitted over-the-air). |
| * |
| * @param subscribeType Subscribe session type: |
| * {@link SubscribeConfig#SUBSCRIBE_TYPE_ACTIVE} or |
| * {@link SubscribeConfig#SUBSCRIBE_TYPE_PASSIVE}. |
| * |
| * @return The builder to facilitate chaining |
| * {@code builder.setXXX(..).setXXX(..)}. |
| */ |
| public Builder setSubscribeType(@SubscribeTypes int subscribeType) { |
| if (subscribeType < SUBSCRIBE_TYPE_PASSIVE || subscribeType > SUBSCRIBE_TYPE_ACTIVE) { |
| throw new IllegalArgumentException("Invalid subscribeType - " + subscribeType); |
| } |
| mSubscribeType = subscribeType; |
| return this; |
| } |
| |
| /** |
| * Sets the time interval (in seconds) an active ( |
| * {@link SubscribeConfig.Builder#setSubscribeType(int)}) subscribe session |
| * will be alive - i.e. broadcasting a packet. When the TTL is reached |
| * an event will be generated for |
| * {@link DiscoverySessionCallback#onSessionTerminated()}. |
| * <p> |
| * Optional. 0 by default - indicating the session doesn't terminate on its own. |
| * Session will be terminated when {@link DiscoverySession#destroy()} is |
| * called. |
| * |
| * @param ttlSec Lifetime of a subscribe session in seconds. |
| * |
| * @return The builder to facilitate chaining |
| * {@code builder.setXXX(..).setXXX(..)}. |
| */ |
| public Builder setTtlSec(int ttlSec) { |
| if (ttlSec < 0) { |
| throw new IllegalArgumentException("Invalid ttlSec - must be non-negative"); |
| } |
| mTtlSec = ttlSec; |
| return this; |
| } |
| |
| /** |
| * Sets the match style of the subscription - how are matches from a |
| * single match session (corresponding to the same publish action on the |
| * peer) reported to the host (using the |
| * {@link DiscoverySessionCallback#onServiceDiscovered(PeerHandle, byte[], |
| * java.util.List)}). The options are: only report the first match and ignore the rest |
| * {@link SubscribeConfig#MATCH_STYLE_FIRST_ONLY} or report every single |
| * match {@link SubscribeConfig#MATCH_STYLE_ALL} (the default). |
| * |
| * @param matchStyle The reporting style for the discovery match. |
| * @return The builder to facilitate chaining |
| * {@code builder.setXXX(..).setXXX(..)}. |
| */ |
| public Builder setMatchStyle(@MatchStyles int matchStyle) { |
| if (matchStyle != MATCH_STYLE_FIRST_ONLY && matchStyle != MATCH_STYLE_ALL) { |
| throw new IllegalArgumentException( |
| "Invalid matchType - must be MATCH_FIRST_ONLY or MATCH_ALL"); |
| } |
| mMatchStyle = matchStyle; |
| return this; |
| } |
| |
| /** |
| * Configure whether a subscribe terminate notification |
| * {@link DiscoverySessionCallback#onSessionTerminated()} is reported |
| * back to the callback. |
| * |
| * @param enable If true the terminate callback will be called when the |
| * subscribe is terminated. Otherwise it will not be called. |
| * |
| * @return The builder to facilitate chaining |
| * {@code builder.setXXX(..).setXXX(..)}. |
| */ |
| public Builder setTerminateNotificationEnabled(boolean enable) { |
| mEnableTerminateNotification = enable; |
| return this; |
| } |
| |
| /** |
| * Build {@link SubscribeConfig} given the current requests made on the |
| * builder. |
| */ |
| public SubscribeConfig build() { |
| return new SubscribeConfig(mServiceName, mServiceSpecificInfo, mMatchFilter, |
| mSubscribeType, mTtlSec, mMatchStyle, |
| mEnableTerminateNotification); |
| } |
| } |
| } |