DOCSEARCHbyAlgolia
Submit Docs

SpamBlocker Documentation

repository·master·Indexed 23 days ago

https://github.com/aj3423/spamblocker

An Android application for blocking spam calls and messages, adhering to GDPR, HIPAA, and CCPA standards. The documentation covers application configuration via the Configs class, regex and pattern-based blocking rules, the ISchedule interface for bot services, CSV parsing utilities, and a structured permission management system for Android manifest and system settings.

Tokens
4.3K
Snippets
8
Records
22
Agent score
83%

What's inside spamblocker

  1. Understand SpamBlocker data privacy and compliance

    master

    SpamBlocker is designed to be privacy-centric and is compliant with GDPR, HIPAA, and CCPA regulations.

    Key privacy behaviors:

    • No Data Collection: The application does not collect or share personal data or usage analytics.
    • No Trackers: There are no advertising SDKs or trackers included in the application.
    • Local Storage: External API keys are stored only on the user's device and only after user action.
    • User-Initiated Actions: All external interactions require user action (e.g., pressing a button) by default. Automatic interactions are disabled unless explicitly configured by the user.

  2. Identify third-party data exposure risks

    master

    While SpamBlocker does not send personal data to third parties, using external services (such as online database downloading or phone number verification/validation) may result in the following data being sent to those third-party servers:

    1. User's credentials (API key)
    2. User's IP address
    3. Phone number verified and/or validated
    4. Country codes (auto-detected or manually set)
    5. Operating system (detected via TCP/TLS fingerprint)

    Note: Always refer to the specific third-party service's privacy policy to understand how they handle your data, as they may collect different subsets of this information.

  3. How configuration categories work

    master

    The application organizes settings into logical Category groups. When loading or applying configurations via the Configs class, you use a CategorySelection object to determine which subsets of settings are processed. This prevents unnecessary processing of large data sets (like history logs or spam databases) when only minor settings (like theme or language) are being backed up or restored.

    Available categories include:

    • OTHERS: Core settings like Global, Contact, STIR, SpamDB, Notification, etc.
    • REGEX_RULES: Pattern-based settings like RegexOptions, NumberRules, ContentRules, PushAlert, etc.
    • APIS: API-related settings like ApiQuery and ApiReport.
    • WORKFLOWS: Automation settings like BotOptions and Bots.
    • LANGUAGE: Language settings.
    • THEME: UI theme and color settings.
    • SPAM_NUMBERS: The SpamNumbers database.
    • HISTORY_LOGS: Call and SMS history records.

  4. Configure Regex and Pattern rules

    master

    The application uses several classes to manage pattern-based blocking and UI behavior for regex lists.

    • RegexOptions: Controls UI behavior for regex lists (e.g., numberCollapsed, contentCollapsed, maxRegexRows, textboxLimit).
    • PatternRules (Abstract): A base for rule sets. It provides load() and apply() logic that interacts with specific RegexTable implementations.
    • NumberRules: Manages regex rules for phone numbers via NumberRegexTable.
    • ContentRules: Manages regex rules for message content via ContentRegexTable.
    • QuickCopyRules: Manages regex rules for quick copy features via QuickCopyRegexTable.

  5. How permissions are managed in Spam Blocker

    master

    The project uses a structured hierarchy to manage various Android permissions. All permissions inherit from the PermissionType.Basic abstract class, which provides a unified interface for checking status, requesting access, and handling results.

    There are three main types of permission implementations:

    1. Regular Permissions: Standard Android manifest permissions (e.g., Contacts, ReadSMS). These use launcherRegular to request access.
    2. LaunchByIntent Permissions: Protected permissions that require navigating the user to specific system settings via an Intent (e.g., UsageStats, NotificationAccess, WriteSettings). These use launcherProtected.
    3. Storage Access Framework (SAF) Permissions: Specialized permissions for directory access (e.g., SafDirDirAccess) that use launcherSAF to handle Uri selection and persistence.

    Note: The class names for Regular permissions (e.g., Contacts, ReceiveSMS) must never be renamed, as they are used to recover permission states during backup restores.

  6. Available ISchedule implementations

    master

    The following concrete implementations of ISchedule are available:

    • Daily: Runs once every day at a specific Time (hour and minute).
    • Weekly: Runs on specific days of the week (weekdays) at a specific Time.
    • Periodically: Runs at a recurring interval defined by the Time (e.g., if Time is 01:00, it runs every 1 hour and 0 minutes).
    • Delay: (Internal use only) Used for auto-reporting numbers. It runs once after a specified Time delay.

  7. Review requested Android permissions

    master

    SpamBlocker optionally requests the following Android permissions to enable specific features. Users should be aware of these when configuring the app:

    PermissionPurpose
    INTERNETTo download, query, or report numbers
    ANSWER_PHONE_CALLSTo hang-up calls
    POST_NOTIFICATIONSTo show notifications
    READ_CONTACTSTo match contacts
    RECEIVE_SMS & RECEIVE_MMSTo receive new SMS/MMS messages
    SEND_SMSTo reply to contacts after calls are blocked
    READ_CALL_LOG & READ_SMSTo check if a call is repeated
    READ_CALENDARTo adjust rules based on calendar events
    READ_PHONE_STATETo monitor ringing state
    NOTIFICATION_ACCESSTo monitor notifications from other apps
    WRITE_SETTINGSTo change the ringtone
    READ_LOGTo report bugs via adb log
    SYSTEM_ALERT_WINDOWTo show a floating caller ID window
    SCHEDULE_EXACT_ALARMTo repeat notifications for important messages
    REQUEST_IGNORE_BATTERY_OPTIMIZATIONSTo allow the app to work in the background

  8. Use the Permission object to manage access

    master

    The Permission object is the primary entry point for interacting with all supported permissions in the application. It provides pre-instantiated permission objects and utility methods to manage them.

    Key Methods:

    • Permission.all(): Returns a List<Basic> containing every supported permission object.
    • Permission.allEnabled(): Returns a List<Basic> containing only the permissions that are currently granted.
    • Permission.init(ctx): Must be called once (typically at app startup) to synchronize the isGranted state of all permission objects with the actual system state using check(ctx).

    Available Permission Objects:

    • callScreening (CallScreening)
    • contacts (Contacts)
    • receiveSMS (ReceiveSMS)
    • sendSMS (SendSMS)
    • receiveMMS (ReceiveMMS)
    • answerCalls (AnswerCalls)
    • callLog (CallLog)
    • phoneState (PhoneState)
    • readSMS (ReadSMS)
    • calendar (Calendar)
    • writeSettings (WriteSettings)
    • notificationAccess (NotificationAccess)
    • showOverlay (ShowOverlay)
    • usageStats (UsageStats)
    • batteryUnRestricted (BatteryUnRestricted)
    • scheduleAlarm (ScheduleAlarm)

  9. Parse CSV files with CSVParser

    master

    The CSVParser class provides a state-machine based parser for reading CSV files. It automatically detects separators (supporting ,, ;, or |) from the header line and handles UTF-8 BOM (Byte Order Mark) detection.

    To use the parser, provide a PushbackReader and an optional columnMap to rename headers during the parsing process. The parse() method returns a Csv object containing the mapped headers and the parsed rows.

  10. Use columnMap to rename CSV headers

    master

    When initializing CSVParser, you can provide a columnMap: Map<String, String> to normalize header names. The parser will look at the original header names in the file and replace them with the values provided in your map. If a header is not present in the map, the original name is preserved.

    Example mapping:

    • Input header: "Spam Number" $\rightarrow$ Output header: "pattern" (if mapped via columnMap["Spam Number"] = "pattern")

  11. Serialize and parse ISchedule objects

    master

    Schedules can be converted to and from JSON strings using the provided extension functions. This is useful for persisting schedule configurations.

    • serialize(): Converts an ISchedule instance into a JSON string using BotJson and a PolymorphicSerializer.
    • parseSchedule(): An extension function on String that attempts to decode a JSON string back into an ISchedule instance. Returns null if the string is empty or parsing fails.
    fun ISchedule.serialize(): String {
    return BotJson.encodeToString(PolymorphicSerializer(ISchedule::class), this)
}

fun String.parseSchedule(): ISchedule? {
    if (isEmpty()) return null
    return try {
        BotJson.decodeFromString(PolymorphicSerializer(ISchedule::class), this)
    } catch (_: Exception) {
        null
    }
}

  12. Manage application configuration with the Configs class

    master

    The Configs class is the central container for all application settings. It allows you to aggregate various configuration modules (like Global, RegexOptions, Theme, etc.) into a single serializable object. This is primarily used for creating backups or importing settings from a backup file.

    To use Configs:

    1. Load settings: Use load(ctx, categories) to read current settings from SharedPreferences or the database into the Configs object. You must provide a CategorySelection to specify which categories of settings to include.
    2. Export to bytes: Use toByteArray() to serialize the configuration into a GZIP-compressed byte array.
    3. Import from bytes: Use Configs.fromByteArray(bytes) to reconstruct a Configs object from a compressed byte array.
    4. Apply settings: Use apply(ctx, categories) to write the values currently held in the Configs object back to the application's SharedPreferences or database.