<commit_before>package com.polidea.rxandroidble;

import android.bluetooth.BluetoothDevice;
import android.bluetooth.BluetoothGattCallback;
import android.content.Context;
import android.support.annotation.NonNull;
import android.support.annotation.Nullable;

import com.polidea.rxandroidble.exceptions.BleDisconnectedException;
import com.polidea.rxandroidble.exceptions.BleGattCallbackTimeoutException;
import com.polidea.rxandroidble.exceptions.BleGattException;

import rx.Observable;

public interface RxBleDevice {

    /**
     * Observe changes to connection state of the device's {@link android.bluetooth.BluetoothGatt}.
     * This Observable will never emit errors.
     *
     * If you would like to have the initial state as well you can use observeConnectionStateChanges().startWith(getConnectionState())
     *
     * @return observable that will emit {@link com.polidea.rxandroidble.RxBleConnection.RxBleConnectionState} changes
     */
    Observable<RxBleConnection.RxBleConnectionState> observeConnectionStateChanges();

    /**
     * Returns current connection state of the device's {@link android.bluetooth.BluetoothGatt}
     *
     * @return the RxBleConnectionState
     */
    RxBleConnection.RxBleConnectionState getConnectionState();

    /**
     * @param context     Android's context.
     * @param autoConnect Flag related to
     *                    {@link android.bluetooth.BluetoothDevice#connectGatt(Context, boolean, BluetoothGattCallback)} autoConnect flag.
     *                    If false, the connection will fail with {@link com.polidea.rxandroidble.exceptions.BleGattException} if
     *                    the device is not in range after a 30-second timeout. If true, the connection will be pending indefinitely.
     *                    Unlike the native Android API, if set to true and the connection is lost there will NOT be any attempt to
     *                    reconnect unless explicitly resubscribed.
     * @return Observable emitting the connection.
     * @throws BleDisconnectedException        emitted when the BLE link has been disconnected either when the connection
     *                                         was already established or was in pending connection state. This occurs when the
     *                                         connection was released as a part of expected behavior
     *                                         (with {@link android.bluetooth.BluetoothGatt#GATT_SUCCESS} state).
     * @throws BleGattException                emitted when the BLE link has been interrupted as a result of an error.<commit_msg>Added a usage hint to device’s observe state function (#381)<commit_after>package com.polidea.rxandroidble;

import android.bluetooth.BluetoothDevice;
import android.bluetooth.BluetoothGattCallback;
import android.content.Context;
import android.support.annotation.NonNull;
import android.support.annotation.Nullable;

import com.polidea.rxandroidble.exceptions.BleDisconnectedException;
import com.polidea.rxandroidble.exceptions.BleGattCallbackTimeoutException;
import com.polidea.rxandroidble.exceptions.BleGattException;

import rx.Observable;

public interface RxBleDevice {

    /**
     * Observe changes to connection state of the device's {@link android.bluetooth.BluetoothGatt}.
     * This Observable will never emit errors.
     *
     * If you would like to have the initial state as well you can use observeConnectionStateChanges().startWith(getConnectionState())
     *
     * NOTE: This is a convenience function for easy state changes monitoring of an individual peripheral that may be useful in the UI.
     * It is not meant to be a trigger for reconnecting a particular device—for this purpose one should react on the errors emitted from
     * {@link #establishConnection(boolean)}
     *
     * @return observable that will emit {@link com.polidea.rxandroidble.RxBleConnection.RxBleConnectionState} changes
     */
    Observable<RxBleConnection.RxBleConnectionState> observeConnectionStateChanges();

    /**
     * Returns current connection state of the device's {@link android.bluetooth.BluetoothGatt}
     *
     * @return the RxBleConnectionState
     */
    RxBleConnection.RxBleConnectionState getConnectionState();

    /**
     * @param context     Android's context.
     * @param autoConnect Flag related to
     *                    {@link android.bluetooth.BluetoothDevice#connectGatt(Context, boolean, BluetoothGattCallback)} autoConnect flag.
     *                    If false, the connection will fail with {@link com.polidea.rxandroidble.exceptions.BleGattException} if
     *                    the device is not in range after a 30-second timeout. If true, the connection will be pending indefinitely.
     *                    Unlike the native Android API, if set to true and the connection is lost there will NOT be any attempt to
     *                    reconnect unless explicitly resubscribed.
     * @return Observable emitting the connection.
     * @throws BleDisconnectedException        emitted when the BLE link has been disconnected either when the connection
     *                                         was already established or was in pending connection state. This occurs when the
     *                                         connection was released as a part of expected behavior
     *                                         (with {@link android.bluetooth.BluetoothGatt#GATT_SUCCESS} state).
     * @throws BleGattException                emitted when the BLE link has been interrupted as a result of an error.
{'fraction_non_alphanumeric': 0.06030780243378669, 'fraction_numerical': 0.0012526843235504653, 'mean_word_length': 2.8491735537190084, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 5, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 12, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5452369', 'n_tokens_mistral': 1346, 'n_tokens_neox': 1298, 'n_words': 469}