BluetoothAdapter — یہ کیا ہے، طریقے اور Android میں Bluetooth کا انتظام

BluetoothAdapter کیا ہے: جوہر اور مثال حاصل کرنا

BluetoothAdapter Android آلہ کے طبعی Bluetooth اڈاپٹر کی نمائندگی کرتا ہے۔ ہر آلہ میں بالکل ایک اڈاپٹر ہوتا ہے (مستثنیٰ Android Automotive ہے جس میں متعدد Bluetooth چپس ہیں، جو BluetoothManager.getAdapterList() استعمال کرتا ہے)۔ BluetoothAdapter ریڈیو کی حالت کو سمیٹتا ہے: STATE_OFF (0)، STATE_TURNING_ON (1)، STATE_ON (2)، STATE_TURNING_OFF (3)۔ حالت ACTION_STATE_CHANGED پر BroadcastReceiver کے ذریعے ٹریک کی جاتی ہے۔

BluetoothAdapter مثال حاصل کرنا Android پر کسی بھی BLE ایپلیکیشن کا پہلا قدم ہے۔ تجویز کردہ طریقہ API 18+ سے BluetoothManager.getAdapter() کے ذریعے ہے۔ متبادل جامد طریقہ BluetoothAdapter.getDefaultAdapter() ہے، جو API 5 سے کام کرتا ہے لیکن کم لچکدار ہے۔ دونوں طریقے null لوٹاتے ہیں اگر آلہ میں Bluetooth ماڈیول نہیں ہے (صرف Wi-Fi ٹیبلیٹ، ایمولیٹر)۔ null جانچ لازمی ہے: ایپلیکیشن کو صحیح طریقے سے بند ہونا چاہیے یا BLE خصوصیات کو غیر فعال کرنا چاہیے۔

// BluetoothAdapter حاصل کرنا (تجویز کردہ)
import android.bluetooth.BluetoothAdapter
import android.bluetooth.BluetoothManager
import android.content.Context

class BluetoothHelper(context: Context) {

    private val bluetoothAdapter: BluetoothAdapter?

    init {
        // طریقہ 1: BluetoothManager کے ذریعے (API 18+)
        val manager = context.getSystemService(Context.BLUETOOTH_SERVICE)
                as BluetoothManager?
        bluetoothAdapter = manager?.adapter

        // طریقہ 2: جامد طریقہ کے ذریعے (API 5+)
        // val adapter = BluetoothAdapter.getDefaultAdapter()

        // null جانچ
        if (bluetoothAdapter == null) {
            // آلہ Bluetooth کو سپورٹ نہیں کرتا
        }
    }

    // Bluetooth حالت چیک کریں
    fun isBluetoothEnabled(): Boolean {
        return bluetoothAdapter?.isEnabled == true
    }

    // اڈاپٹر کی معلومات حاصل کریں
    fun getAdapterInfo(): Map<String, String> {
        return mapOf(
            "name" to (bluetoothAdapter?.name ?: "N/A"),
            "address" to (bluetoothAdapter?.address ?: "N/A"),
            "state" to (bluetoothAdapter?.state?.toString() ?: "N/A"),
            "scanMode" to (bluetoothAdapter?.scanMode?.toString() ?: "N/A")
        )
    }
}

BluetoothHelper کلاس بعد میں null جانچ کے ساتھ BluetoothManager کے ذریعے BluetoothAdapter حاصل کرنے کا مظاہرہ کرتا ہے۔ isBluetoothEnabled isEnabled کو چیک کرتا ہے — کسی بھی BLE کارروائی سے پہلے ایک لازمی شرط۔ getAdapterInfo آلہ کا نام، MAC پتہ، حالت اور مرئیت موڈ لوٹاتا ہے۔ اہم: Android 10+ (API 29+) پر، سسٹم سروس ایک جعلی MAC پتہ (02:00:00:00:00:00) لوٹاتی ہے اگر ایپلیکیشن کے پاس BLUETOOTH_ADMIN اور ACCESS_FINE_LOCATION اجازتیں نہیں ہیں۔

BluetoothAdapter کے اہم طریقے: enable, disable, getState, getAddress

BluetoothAdapter Bluetooth ریڈیو کو کنٹرول کرنے کے طریقے فراہم کرتا ہے۔ enable() اور disable() Bluetooth کو آن اور آف کرتے ہیں۔ دونوں طریقوں کے لیے BLUETOOTH_ADMIN اجازت درکار ہے اور وہ غیر متزامن طور پر انجام پاتے ہیں: enable() کال کرنے کے بعد، سسٹم ریڈیو کو فعال کرنے کا عمل شروع کرتا ہے، اور حالت BluetoothAdapter.ACTION_STATE_CHANGED ایکشن کے ساتھ BroadcastReceiver کے ذریعے ٹریک کی جاتی ہے۔ Android 10+ پر، enable() اور disable() کے لیے اضافی سسٹم مراعات درکار ہیں — عام ایپلیکیشنز صارف ڈائیلاگ کے بغیر پروگرام کے ذریعے Bluetooth کو کنٹرول نہیں کر سکتیں۔

getState() اڈاپٹر کی موجودہ حالت لوٹاتا ہے: STATE_OFF (10)، STATE_TURNING_ON (11)، STATE_ON (12)، STATE_TURNING_OFF (13)۔ getAddress() Bluetooth اڈاپٹر کا MAC پتہ لوٹاتا ہے۔ Android 6+ پر، MAC پتہ درخواست کرنے کے لیے ACCESS_FINE_LOCATION (یا API 31+ کے لیے ACCESS_COARSE_LOCATION) درکار ہے۔ Android 10+ پر، getAddress() مستقل پتہ 02:00:00:00:00:00 لوٹاتا ہے — حقیقی پتہ عوامی API کے ذریعے دستیاب نہیں ہے۔

getScanMode() اڈاپٹر کے مرئیت موڈ کا تعین کرتا ہے: SCAN_MODE_NONE (غیر مرئی)، SCAN_MODE_CONNECTABLE (منسلک آلات کو مرئی)، SCAN_MODE_CONNECTABLE_DISCOVERABLE (سب کو مرئی)۔ مرئیت موڈ حفاظت کے لیے وقت میں محدود ہے (عام طور پر 60–300 سیکنڈ)۔ setScanMode() کے ذریعے موڈ سیٹ کرنے کے لیے Android 10+ پر BLUETOOTH_ADMIN اور سسٹم اجازت درکار ہے۔

آلات کی اسکیننگ: startDiscovery اور BluetoothLeScanner

BluetoothAdapter دو قسم کی اسکیننگ کو سپورٹ کرتا ہے۔ کلاسک Bluetooth اسکیننگ (BR/EDR) startDiscovery() کے ذریعے شروع ہوتی ہے — یہ فون اور ہیڈسیٹ سمیت ہر قسم کے Bluetooth آلات کا پتہ لگاتی ہے۔ نتائج BluetoothDevice.ACTION_FOUND ایکشن کے ساتھ BroadcastReceiver کے ذریعے لوٹائے جاتے ہیں۔ startDiscovery() 12 سیکنڈ تک چلتا ہے اور cancelDiscovery() کال کرکے منسوخ کیا جا سکتا ہے۔ یہ طریقہ BLE کے لیے متروک ہے — BluetoothLeScanner استعمال کریں۔

BluetoothAdapter کے ذریعے BLE اسکیننگ متروک طریقہ startLeScan(LeScanCallback) استعمال کرتی ہے۔ API 21 سے شروع کرتے ہوئے، Google BluetoothLeScanner استعمال کرنے کی تجویز کرتا ہے، جو BluetoothAdapter.getBluetoothLeScanner() کے ذریعے حاصل ہوتا ہے۔ BluetoothLeScanner زیادہ لچکدار API فراہم کرتا ہے: ScanSettings کے ذریعے اسکیننگ کنفیگریشن (موڈ، کال بیک کی قسم، میچ موڈ)، ScanFilter کے ذریعے فلٹرنگ (سروس UUID، آلہ کے نام، MAC پتے کے ذریعے)، اور پس منظر اسکیننگ کے لیے PendingIntent سپورٹ۔

// پرانی (متروک) بمقابلہ نئی BLE اسکیننگ API
import android.bluetooth.BluetoothAdapter
import android.bluetooth.le.*

class BLEScanner(private val bluetoothAdapter: BluetoothAdapter?) {

    // متروک: startLeScan (API 18+، API 21)
    @Suppress("DEPRECATION")
    fun legacyScan() {
        bluetoothAdapter?.startLeScan { device, rssi, scanRecord ->
            print("Found (LE Scan): $device.name, RSSI: $rssi")
        }
    }

    // نیا: BluetoothLeScanner (API 21+)
    fun modernScan() {
        val scanner = bluetoothAdapter?.bluetoothLeScanner
            ?: return

        // اسکین کی ترتیبات
        val settings = ScanSettings.Builder()
            .setScanMode(ScanSettings.SCAN_MODE_LOW_LATENCY)
            .setCallbackType(ScanSettings.CALLBACK_TYPE_ALL_MATCHES)
            .setMatchMode(ScanSettings.MATCH_MODE_AGGRESSIVE)
            .build()

        // سروس کے ذریعے فلٹر کریں (دل کی دھڑکن UUID)
        val filters = listOf(
            ScanFilter.Builder()
                .setServiceUuid(ParcelUuid.fromString("0000180D-0000-1000-8000-00805F9B34FB"))
                .build()
        )

        // اسکین شروع کریں
        scanner.startScan(filters, settings, object : ScanCallback() {
            override fun onScanResult(callbackType: Int, result: ScanResult) {
                val device = result.device
                val rssi = result.rssi
                print("Found (BLE Scanner): ${device.name}, RSSI: $rssi, address: ${device.address}")
            }

            override fun onScanFailed(errorCode: Int) {
                print("Scan error: $errorCode")
            }
        })
    }
}

BLEScanner کلاس متروک startLeScan اور جدید BluetoothLeScanner کا موازنہ کرتا ہے۔ legacyScan میں، LeScanCallback BluetoothDevice، RSSI اور خام scanRecord وصول کرتا ہے۔ modernScan میں، LOW_LATENCY موڈ (زیادہ سے زیادہ دریافت کی رفتار) کے ساتھ ScanSettings اور دل کی دھڑکن کی سروس UUID (0x180D) کے ذریعے فلٹر کرنے کے لیے ScanFilter استعمال کیا جاتا ہے۔ ScanCallback توسیعی معلومات کے ساتھ ScanResult آبجیکٹ فراہم کرتا ہے: نام، RSSI، اشتہار ڈیٹا، کنکشن کی قسم۔

BluetoothManager: BluetoothAdapter تک رسائی کے لیے جدید API

BluetoothManager ایک نظام Android سروس ہے، جو API 18 (Android 4.3) میں متعارف کرائی گئی، Bluetooth کارروائیوں کے انتظام کے لیے۔ API 18 سے پہلے، BluetoothAdapter حاصل کرنے کا واحد طریقہ جامد طریقہ getDefaultAdapter() تھا۔ BluetoothManager فراہم کرتا ہے: adapter — ایک BluetoothAdapter مثال، getConnectedDevices() — منسلک آلات کی فہرست، getDevicesMatchingConnectionStates() — حالت کے ذریعے فلٹرنگ۔ BluetoothManager پرانے APIs پر BluetoothLeScanner حاصل کرنے کے لیے بھی استعمال ہوتا ہے۔

BluetoothManager کے فوائد براہ راست BluetoothAdapter.getDefaultAdapter() کال کرنے کے مقابلے میں: ایپلیکیشن ایک جامد سنگلٹن پر منحصر نہیں ہوتی، مینیجر سیاق و سباق (Activity/Application) کا احترام کرتا ہے، جو Android Enterprise کے کثیر اکاؤنٹ منظرناموں کے لیے اہم ہے۔ متعدد Bluetooth چپس والے Android Automotive پر، BluetoothManager.getAdapterList() تمام دستیاب اڈاپٹر لوٹاتا ہے — BluetoothAdapter.getDefaultAdapter() صرف پہلا لوٹاتا ہے۔

// BLE کے لیے BluetoothManager استعمال کرنا
class BLEConnection(context: Context) {

    private val bluetoothManager: BluetoothManager =
        context.getSystemService(Context.BLUETOOTH_SERVICE) as BluetoothManager

    private val adapter: BluetoothAdapter? = bluetoothManager.adapter

    // منسلک BLE آلات کی فہرست حاصل کریں
    fun getConnectedDevices(): List<BluetoothDevice> {
        return bluetoothManager.getConnectedDevices(
            BluetoothProfile.GATT
        )
    }

    // حالت کے ذریعے آلات کو فلٹر کریں
    fun getDevicesByState(states: IntArray): List<BluetoothDevice> {
        return bluetoothManager.getDevicesMatchingConnectionStates(
            BluetoothProfile.GATT, states
        )
    }

    // آلہ پر BLE سپورٹ چیک کریں
    fun isBLESupported(): Boolean {
        return adapter != null && context.packageManager
            .hasSystemFeature(PackageManager.FEATURE_BLUETOOTH_LE)
    }

    // سسٹم ڈائیلاگ کے ذریعے Bluetooth فعال کرنے کی درخواست کریں
    fun requestEnableBluetooth(activity: MainActivity) {
        if (adapter?.isEnabled == false) {
            val intent = Intent(BluetoothAdapter.ACTION_REQUEST_ENABLE)
            activity.startActivityForResult(intent, REQUEST_ENABLE_BT)
        }
    }

    companion object {
        const val REQUEST_ENABLE_BT = 1001
    }
}

BLEConnection کلاس BluetoothAdapter تک رسائی اور منسلک GATT آلات کی فہرست حاصل کرنے کے لیے BluetoothManager استعمال کرتی ہے۔ isBLESupported PackageManager.hasSystemFeature(FEATURE_BLUETOOTH_LE) کے ذریعے BLE ریڈیو کی موجودگی چیک کرتا ہے — BLE کے بغیر Bluetooth Classic آلات کے لیے ایک اہم جانچ۔ requestEnableBluetooth Bluetooth فعال کرنے کا سسٹم ڈائیلاگ دکھاتا ہے (ACTION_REQUEST_ENABLE)، جس کے لیے BLUETOOTH_ADMIN اجازت درکار نہیں ہے — یہ سسٹم ایپلیکیشن کے بغیر Android 10+ پر Bluetooth فعال کرنے کا واحد قانونی طریقہ ہے۔

BluetoothAdapter کے ساتھ کام کرنے کے لیے Android اجازتیں

اجازتیں BluetoothAdapter کے لیے Android کے ہر ورژن کے ساتھ تیار ہوئی ہیں۔ Android 6–11 (API 23–30) پر، BLE اسکیننگ کے لیے BLUETOOTH، BLUETOOTH_ADMIN اور ACCESS_FINE_LOCATION لازمی ہیں۔ Android 12+ (API 31+) پر، Google نے اجازتوں کو تقسیم کیا: ACCESS_FINE_LOCATION کو BLUETOOTH_SCAN (اسکیننگ)، BLUETOOTH_CONNECT (کنکشن)، BLUETOOTH_ADVERTISE (اشتہار) سے تبدیل کر دیا گیا۔ BLE آلات کی دریافت کے لیے، BLUETOOTH_SCAN کافی ہے، مقام درکار نہیں ہے۔

اجازت جدول Android ورژن کے مطابق:

Android 12+ پر، تمام Bluetooth اجازتیں رن ٹائم اجازتیں ہیں — انہیں ActivityResultContracts.RequestMultiplePermissions کے ذریعے رن ٹائم پر درخواست کیا جانا چاہیے۔ BLUETOOTH_SCAN اور BLUETOOTH_ADVERTISE NEARBY_DEVICES گروپ سے تعلق رکھتی ہیں، BLUETOOTH_CONNECT اسی گروپ سے تعلق رکھتی ہے۔ BLUETOOTH اور BLUETOOTH_ADMIN اجازتیں API < 31 کے ساتھ مطابقت کے لیے مینی فیسٹ میں رہتی ہیں، لیکن API 31+ کے لیے انہیں نظر انداز کیا جاتا ہے — Google نئی اجازتوں کو واضح طور پر بتانے کا تقاضا کرتا ہے۔

// Android 12+ پر Bluetooth اجازتیں درخواست کریں
import android.Manifest
import android.content.pm.PackageManager
import android.os.Build
import androidx.core.content.ContextCompat

class PermissionHelper(context: Context) {

    fun getRequiredPermissions(): Array<String> {
        return if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
            // Android 12+: BLE-
            arrayOf(
                Manifest.permission.BLUETOOTH_SCAN,
                Manifest.permission.BLUETOOTH_CONNECT,
                Manifest.permission.BLUETOOTH_ADVERTISE
            )
        } else {
            // Android 6-11: BLE
            arrayOf(
                Manifest.permission.ACCESS_FINE_LOCATION,
                Manifest.permission.BLUETOOTH,
                Manifest.permission.BLUETOOTH_ADMIN
            )
        }
    }

    // تمام اجازتیں چیک کریں
    fun hasPermissions(context: Context): Boolean {
        return getRequiredPermissions().all { permission ->
            ContextCompat.checkSelfPermission(context, permission)
                    == PackageManager.PERMISSION_GRANTED
        }
    }
}

PermissionHelper کلاس API سطح کے مطابق اجازتوں کا صحیح سیٹ لوٹاتا ہے۔ Android 12+ پر، بغیر مقام کے BLUETOOTH_SCAN، BLUETOOTH_CONNECT، BLUETOOTH_ADVERTISE استعمال کیا جاتا ہے۔ Android 6–11 پر، BLE اسکیننگ کے لیے اب بھی ACCESS_FINE_LOCATION درکار ہے۔ ڈویلپر کو ActivityResultContracts یا RxPermissions کے ذریعے اجازتوں کی درخواست کرتے وقت دونوں منظرناموں پر غور کرنا چاہیے۔

Kotlin میں BluetoothAdapter کی مکمل مثال

مکمل مثال Kotlin میں ایک BLE ایپلیکیشن کی جو BluetoothAdapter استعمال کرتے ہوئے BLE آلہ کو اسکین، کنیکٹ اور ڈیٹا پڑھتی ہے۔ مثال میں اجازت کی جانچ، اڈاپٹر حاصل کرنا، BluetoothLeScanner کے ذریعے اسکین کرنا اور BluetoothDevice.connectGatt کے ذریعے کنیکٹ کرنا شامل ہے۔

// Kotlin میں مکمل BLE مینیجر
class BLEManager(private val context: Context) {

    private val bluetoothManager: BluetoothManager =
        context.getSystemService(Context.BLUETOOTH_SERVICE) as BluetoothManager
    private val adapter: BluetoothAdapter? = bluetoothManager.adapter
    private var scanner: BluetoothLeScanner? = adapter?.bluetoothLeScanner
    private var gatt: BluetoothGatt? = null

    // 1. سروس کی دریافت
    fun canScan(): Boolean {
        return adapter?.isEnabled == true
                && scanner != null
                && PermissionHelper(context).hasPermissions(context)
    }

    // 2. فلٹر کے ساتھ
    fun startScanning(callback: (BluetoothDevice, Int) -> Unit) {
        if (!canScan()) return

        val settings = ScanSettings.Builder()
            .setScanMode(ScanSettings.SCAN_MODE_LOW_LATENCY)
            .setReportDelay(0)
            .build()

        scanner?.startScan(null, settings, object : ScanCallback() {
            override fun onScanResult(callbackType: Int, result: ScanResult) {
                callback(result.device, result.rssi)
            }
        })
    }

    // 3. اسکین بند کریں
    fun stopScanning() {
        scanner?.stopScan(object : ScanCallback() {})
    }

    // 4. BLE آلہ سے جڑیں
    fun connectToDevice(device: BluetoothDevice) {
        if (adapter?.isEnabled != true) return

        gatt = device.connectGatt(
            context,
            false,
            object : BluetoothGattCallback() {
                override fun onConnectionStateChange(gatt: BluetoothGatt, status: Int, newState: Int) {
                    if (newState == BluetoothProfile.STATE_CONNECTED) {
                        gatt.discoverServices()
                    }
                }

                override fun onServicesDiscovered(gatt: BluetoothGatt, status: Int) {
                    // سروسز مل گئیں، خصوصیات پڑھی جا سکتی ہیں
                }
            },
            BluetoothDevice.TRANSPORT_LE
        )
    }

    // 5. وسائل جاری کریں
    fun disconnect() {
        gatt?.disconnect()
        gatt?.close()
        gatt = null
    }
}

BLEManager کلاس Android پر مکمل BLE سائیکل کو یکجا کرتی ہے: اڈاپٹر اور اجازتوں کی جانچ (canScan)، ScanSettings کے ساتھ BluetoothLeScanner کے ذریعے اسکیننگ (startScanning)، TRANSPORT_LE کے ساتھ BluetoothDevice.connectGatt کے ذریعے کنیکٹ کرنا (connectToDevice)، اور وسائل کو جاری کرنا (disconnect)۔ تمام BLE کارروائیاں UI تھریڈ پر انجام پاتی ہیں — Android مین تھریڈ پر BluetoothGattCallback کال بیک کال کرتا ہے۔ کارکردگی کے لحاظ سے اہم BLE کاموں کے لیے، GATT کارروائیوں کو پس منظر کے HandlerThread میں منتقل کرنے کی سفارش کی جاتی ہے۔