# Android Device Info Library - API Documentation

This document provides a comprehensive reference for all classes, functions, and properties available in the Android Device Info library.

## Table of Contents

- [AndroidInfo Object](#androidinfo-object)
- [DeviceInfo Object](#deviceinfo-object)
- [AndroidDeviceInfo Object](#androiddeviceinfo-object)
- [AltDeviceNames Object](#altdevicenames-object)
- [DeviceDatabase Class](#devicedatabase-class)
- [Device Types](#device-types)
- [Data Classes](#data-classes)

---

## AndroidInfo Object

The main object for accessing static device information and type detection.

### Properties

#### Info Object
Access to basic device information from `Build` class:

```kotlin
AndroidInfo.Info.brand: String          // Device brand (e.g., "samsung")
AndroidInfo.Info.model: String          // Device model (e.g., "SM-G998U")
AndroidInfo.Info.device: String         // Device name (e.g., "p3qsqw")
AndroidInfo.Info.product: String        // Product name
AndroidInfo.Info.manufacturer: String   // Manufacturer (e.g., "Samsung")
AndroidInfo.Info.hardware: String       // Hardware name
AndroidInfo.Info.board: String          // Board name
AndroidInfo.Info.fingerprint: String    // Build fingerprint
```

#### Version Object
Access to Android version information:

```kotlin
AndroidInfo.Version.release: String     // Android version (e.g., "13")
AndroidInfo.Version.incremental: String // Incremental version
AndroidInfo.Version.sdkInt: Int         // SDK version number (e.g., 33)
AndroidInfo.Version.codename: String    // Version codename
```

#### Device Detection Properties

```kotlin
AndroidInfo.isEmulator: Boolean         // True if running on emulator
AndroidInfo.isPhysicalDevice: Boolean   // True if running on physical device
```

### Functions

#### getType(context: Context): DeviceType
Determines the type of device.

**Parameters:**
- `context: Context` - Application context

**Returns:** `DeviceType` enum value

**Example:**
```kotlin
val deviceType = AndroidInfo.getType(context)
when (deviceType) {
    AndroidInfo.DeviceType.SMARTPHONE -> // Handle smartphone
    AndroidInfo.DeviceType.TABLET -> // Handle tablet
    // ... other cases
}
```

### Vendor-Specific Objects

Empty objects ready for future vendor-specific functionality:

```kotlin
AndroidInfo.Samsung      // Samsung-specific features
AndroidInfo.Xiaomi       // Xiaomi-specific features
AndroidInfo.Oppo         // Oppo-specific features
AndroidInfo.Huawei       // Huawei-specific features
AndroidInfo.OnePlus      // OnePlus-specific features
AndroidInfo.Vivo         // Vivo-specific features
AndroidInfo.LG           // LG-specific features
AndroidInfo.Lenovo       // Lenovo-specific features
AndroidInfo.Sony         // Sony-specific features
AndroidInfo.Google       // Google Pixel-specific features
AndroidInfo.Asus         // Asus-specific features
AndroidInfo.Realme       // Realme-specific features
AndroidInfo.Motorola     // Motorola-specific features
AndroidInfo.Nokia        // Nokia-specific features
AndroidInfo.Honor        // Honor-specific features
AndroidInfo.Infinix      // Infinix-specific features
AndroidInfo.Tecno        // Tecno-specific features
AndroidInfo.ZTE          // ZTE-specific features
AndroidInfo.Meizu        // Meizu-specific features
AndroidInfo.Sharp        // Sharp-specific features
AndroidInfo.Micromax     // Micromax-specific features
```

---

## DeviceInfo Object

Provides async device information retrieval with online API integration.

### Properties

```kotlin
DeviceInfo.api_url_base: String         // Base API URL (default: "https://cdn.oxmc.me/api")
DeviceInfo.api_device: String           // Device API endpoint
DeviceInfo.api_deviceSearch: String     // Device search endpoint
DeviceInfo.api_reportDevice: String     // Device reporting endpoint
DeviceInfo.api_version: String          // API version (default: "v2")
```

### Functions

#### getDeviceInfo(context: Context): Array<String?>
**Suspend function** - Gets comprehensive device information including image URL.

**Parameters:**
- `context: Context` - Application context

**Returns:** Array containing:
- `[0]` - Device name
- `[1]` - Manufacturer
- `[2]` - Model
- `[3]` - Codename
- `[4]` - Image URL (nullable)

**Example:**
```kotlin
lifecycleScope.launch {
    val (name, manufacturer, model, codename, imageUrl) = DeviceInfo.getDeviceInfo(context)
    // Use the information
}
```

#### getDeviceName(context: Context): String
Gets the user-configured device name or falls back to manufacturer + model.

**Parameters:**
- `context: Context` - Application context

**Returns:** Device name string

**Example:**
```kotlin
val deviceName = DeviceInfo.getDeviceName(context)
```

#### getDeviceImage(context: Context, codename: String, model: String, manufacturer: String): String?
**Suspend function** - Fetches device image URL from API.

**Parameters:**
- `context: Context` - Application context
- `codename: String` - Device codename
- `model: String` - Device model
- `manufacturer: String` - Device manufacturer

**Returns:** Image URL string or null if not found

**Example:**
```kotlin
lifecycleScope.launch {
    val imageUrl = DeviceInfo.getDeviceImage(context, "p3qsqw", "SM-G998U", "Samsung")
    // Load image from URL
}
```

#### reportDeviceInfo(context: Context, deviceName: String, manufacturer: String, model: String, codename: String): Boolean
**Suspend function** - Reports device information to the server.

**Parameters:**
- `context: Context` - Application context
- `deviceName: String` - Device name
- `manufacturer: String` - Manufacturer
- `model: String` - Device model
- `codename: String` - Device codename

**Returns:** True if successful, false otherwise

---

## AndroidDeviceInfo Object

Handles device name resolution and caching.

### Functions

#### getCurrentDeviceInfo(context: Context): DeviceInfo
**Worker thread function** - Gets current device information with caching.

**Parameters:**
- `context: Context` - Application context (nullable)

**Returns:** `DeviceInfo` data class instance

**Example:**
```kotlin
// Call from background thread
val deviceInfo = AndroidDeviceInfo.getCurrentDeviceInfo(context)
```

---

## AltDeviceNames Object

Provides alternative device name mappings for known devices.

### Functions

#### getAlternateNameOrDefault(model: String, manufacturer: String, codename: String, default: String): String
Gets alternative device name or returns default.

**Parameters:**
- `model: String` - Device model
- `manufacturer: String` - Device manufacturer
- `codename: String` - Device codename
- `default: String` - Default name if no alternative found

**Returns:** Alternative device name or default

**Example:**
```kotlin
val alternateName = AltDeviceNames.getAlternateNameOrDefault(
    "SM-G998U", 
    "Samsung", 
    "p3qsqw", 
    "Galaxy S21 Ultra"
)
```

#### containsIdentifier(model: String, manufacturer: String, codename: String): Boolean
Checks if device identifiers exist in the alternate names database.

**Parameters:**
- `model: String` - Device model
- `manufacturer: String` - Device manufacturer  
- `codename: String` - Device codename

**Returns:** True if identifiers are found, false otherwise

---

## DeviceDatabase Class

SQLite database helper for device information storage.

### Constructor

```kotlin
DeviceDatabase(context: Context, autoUpdateDB: Boolean = true)
```

**Parameters:**
- `context: Context` - Application context
- `autoUpdateDB: Boolean` - Whether to automatically update database (default: true)

### Functions

#### queryToDevice(codename: String, model: String): DeviceInfo?
Queries the database for device information.

**Parameters:**
- `codename: String` - Device codename
- `model: String` - Device model

**Returns:** `DeviceInfo` object or null if not found

#### close()
Closes the database connection.

**Example:**
```kotlin
DeviceDatabase(context).use { database ->
    val deviceInfo = database.queryToDevice("p3qsqw", "SM-G998U")
    // Use deviceInfo
}
```

---

## Device Types

### DeviceType Enum

```kotlin
enum class DeviceType {
    EMULATOR,     // Development emulator
    SMARTPHONE,   // Standard phone
    TABLET,       // Tablet device
    SMARTWATCH,   // Wearable device
    SMART_TV,     // TV or set-top box
    AUTOMOTIVE,   // Car infotainment
    IOT,          // Internet of Things device
    EREADER,      // E-book reader
    GAMING,       // Gaming device/console
    VR,           // Virtual Reality headset
    FOLDABLE      // Foldable device
}
```

### Device Type Detection Logic

The library uses the following criteria to determine device types:

- **EMULATOR**: Checks build fingerprint, model, manufacturer, and hardware for emulator indicators
- **SMARTWATCH**: Device name starts with "wear", "smartwatch", "watch", or "wrist"
- **SMART_TV**: Device name starts with "tv", "television", "settopbox", "streaming", "media", or "dongle"
- **AUTOMOTIVE**: Device name starts with "car", "automotive", "infotainment", "dashboard", "headunit", or "vehicle"
- **IOT**: Device name starts with "iot", "smart", "connected", "home", "appliance", or "device"
- **EREADER**: Device name starts with "ereader", "ebook", "tablet", or "kindle"
- **GAMING**: Device name starts with "gaming", "console", "handheld", or "portable"
- **VR**: Device name starts with VR-related terms or "quest", "oculus", "meta", "rift"
- **FOLDABLE**: Device name starts with "fold", "flip", "clamshell", "booklet", "dual", or "trifold"
- **TABLET**: Screen smallest width >= 600dp OR model contains "tab"
- **SMARTPHONE**: Default fallback for mobile devices

---

## Data Classes

### DeviceInfo Data Class

```kotlin
class DeviceInfo(
    val manufacturer: String?,    // Device manufacturer
    val marketName: String?,      // Market/commercial name
    val codename: String,         // Internal codename
    val model: String,            // Model identifier
    val timestamp: Long = 0       // Cache timestamp
) {
    val name: String              // Computed property: marketName or capitalized model
}
```

**Properties:**
- `manufacturer`: Device manufacturer (e.g., "Samsung")
- `marketName`: Commercial device name (e.g., "Galaxy S21 Ultra")
- `codename`: Internal device code (e.g., "p3qsqw")
- `model`: Model identifier (e.g., "SM-G998U")
- `timestamp`: When the information was cached
- `name`: The display name (marketName if available, otherwise capitalized model)

### Alternative Constructor

```kotlin
DeviceInfo(jsonObject: JSONObject, timestamp: Long)
```

Creates DeviceInfo from cached JSON data.

---

## Error Handling

Most functions handle errors gracefully:

- Network operations return null or false on failure
- Database operations fall back to alternate name resolution
- Type detection defaults to SMARTPHONE for unknown devices
- Caching operations ignore JSON parsing errors

## Thread Safety

- **AndroidInfo**: Thread-safe (uses lazy initialization)
- **DeviceInfo**: Use suspend functions from coroutine scope
- **AndroidDeviceInfo.getCurrentDeviceInfo()**: Must be called from worker thread
- **DeviceDatabase**: Not thread-safe, use appropriate synchronization

## Performance Considerations

- Device information is cached locally for 30 days
- Network requests have 5-second timeouts
- Database queries are optimized for common device lookups
- Lazy initialization used for expensive operations

## API Configuration

You can customize API endpoints:

```kotlin
DeviceInfo.api_url_base = "https://your-api.com"
DeviceInfo.api_version = "v3"
// Other endpoints will be constructed based on these values
```