# Query SMS

{% hint style="danger" %}
**Requires *****`READ_SMS`***** permission.**
{% endhint %}

Add the following permission in your `AndroidManifest.xml`

```markup
<uses-permission android:name="android.permission.READ_SMS"/>
```

## getInboxSms()

#### Returns Future\<List<[SmsMessage](#smsmessage)>>

| Parameters | Type                              | Description                                                             | Optional | Default Value                                                                |
| :--------: | --------------------------------- | ----------------------------------------------------------------------- | :------: | ---------------------------------------------------------------------------- |
|   Columns  | List of [`SmsColumn`](#smscolumn) | Columns to be returned by the query                                     |    ✔️    | \[ `SmsColumn.ID`, `SmsColumn.ADDRESS`, `SmsColumn.BODY`, `SmsColumn.DATE` ] |
|   Filter   | [`SmsFilter`](#smsfilter)         | Filters the result by given constraints. Works like `SQL WHERE` clause. |    ✔️    | `null`                                                                       |
|  sortOrder | List of [`OrderBy`](#orderby)     | Sorts the result prioritized by order of declaration.                   |    ✔️    | `null`                                                                       |

```dart
List<SmsMessage> messages = await telephony.getInboxSms(
        columns: [SmsColumn.ADDRESS, SmsColumn.BODY],
        filter: SmsFilter.where(SmsColumn.ADDRESS)
                 .equals("1234567890")
                 .and(SmsColumn.BODY)
                 .like("starwars"),
        sortOrder: [OrderBy(SmsColumn.ADDRESS, sort: Sort.ASC),
                OrderBy(SmsColumn.BODY)]
        );
```

#### All parameters are optional.

```dart
List<SmsMessage> messages = await telephony.getInboxSms();
```

## getSentSms()

#### Returns Future\<List<[SmsMessage](#smsmessage)>>

| Parameters | Type                              | Description                                                             | Optional | Default Value                                                                |
| :--------: | --------------------------------- | ----------------------------------------------------------------------- | :------: | ---------------------------------------------------------------------------- |
|   Columns  | List of [`SmsColumn`](#smscolumn) | Columns to be returned by the query                                     |    ✔️    | \[ `SmsColumn.ID`, `SmsColumn.ADDRESS`, `SmsColumn.BODY`, `SmsColumn.DATE` ] |
|   Filter   | [`SmsFilter`](#smsfilter)         | Filters the result by given constraints. Works like `SQL WHERE` clause. |    ✔️    | `null`                                                                       |
|  sortOrder | List of [`OrderBy`](#orderby)     | Sorts the result prioritized by order of declaration.                   |    ✔️    | `null`                                                                       |

```dart
List<SmsMessage> messages = await telephony.getSentSms(
        columns: [SmsColumn.ADDRESS, SmsColumn.BODY],
        filter: SmsFilter.where(SmsColumn.ADDRESS)
                 .equals("1234567890")
                 .and(SmsColumn.BODY)
                 .like("starwars"),
        sortOrder: [OrderBy(SmsColumn.ADDRESS, sort: Sort.ASC),
                OrderBy(SmsColumn.BODY)]
        );
```

#### All parameters are optional.

```dart
List<SmsMessage> messages = await telephony.getSentSms();
```

## getDraftSms()

#### Returns Future\<List<[SmsMessage](#smsmessage)>>

| Parameters | Type                              | Description                                                             | Optional | Default Value                                                                |
| :--------: | --------------------------------- | ----------------------------------------------------------------------- | :------: | ---------------------------------------------------------------------------- |
|   Columns  | List of [`SmsColumn`](#smscolumn) | Columns to be returned by the query                                     |    ✔️    | \[ `SmsColumn.ID`, `SmsColumn.ADDRESS`, `SmsColumn.BODY`, `SmsColumn.DATE` ] |
|   Filter   | [`SmsFilter`](#smsfilter)         | Filters the result by given constraints. Works like `SQL WHERE` clause. |    ✔️    | `null`                                                                       |
|  sortOrder | List of [`OrderBy`](#orderby)     | Sorts the result prioritized by order of declaration.                   |    ✔️    | `null`                                                                       |

```dart
List<SmsMessage> messages = await telephony.getDraftSms(
        columns: [SmsColumn.ADDRESS, SmsColumn.BODY],
        filter: SmsFilter.where(SmsColumn.ADDRESS)
                 .equals("1234567890")
                 .and(SmsColumn.BODY)
                 .like("starwars"),
        sortOrder: [OrderBy(SmsColumn.ADDRESS, sort: Sort.ASC),
                OrderBy(SmsColumn.BODY)]
        );
```

#### All parameters are optional.

```dart
List<SmsMessage> messages = await telephony.getDraftSms();
```

## SmsMessage

| Property             | Type                  |
| -------------------- | --------------------- |
| **`id`**             | `int`                 |
| **`address`**        | `String`              |
| **`body`**           | `String`              |
| **`date`**           | `int` in milliseconds |
| **`dateSent`**       | `int` in milliseconds |
| **`read`**           | `bool`                |
| **`seen`**           | `bool`                |
| **`subject`**        | `String`              |
| **`subscriptionId`** | `int`                 |
| **`threadId`**       | `int`                 |
| **`type`**           | `SmsType`             |
| **`status`**         | `SmsStatus`           |

## SmsColumn

| Columns               |
| --------------------- |
| **`ID`**              |
| **`ADDRESS`**         |
| **`BODY`**            |
| **`DATE`**            |
| **`DATE_SENT`**       |
| **`READ`**            |
| **`SEEN`**            |
| **`STATUS`**          |
| **`SUBJECT`**         |
| **`SUBSCRIPTION_ID`** |
| **`THREAD_ID`**       |
| **`TYPE`**            |

## SmsFilter

Generates a filter that will be used by an query. The methods read like an SQL query. The select part is determined `columns` parameter on one of the query methods. The `SmsFilter` handle the `WHERE` part.

#### Example

```sql
WHERE address = '123456789' 
AND body LIKE 'falcon'
OR date > '232123432'
```

#### Becomes

```dart
SmsFilter.where(SmsColumn.ADDRESS)
         .equals('123456789')
         .and(SmsColumn.BODY)
         .like('falcon')
         .or(SmsColumn.DATE)
         .greaterThan('232123432');
```

### Initializing a filter

Sms Filter works like a **`SQL WHERE`** clause. Initialize the filter by calling the **`where`** method and pass in the column name.

```dart
SmsFilter.where(SmsColumn.ID);
```

### Methods

#### equals()

Compares equality between the column values and the value provided to the function.

```dart
SmsFilter.where(SmsColumn.ID).equals('12');
```

#### greaterThan()

Adds a greater than `>` operator.

```dart
SmsFilter.where(SmsColumn.ID).greaterThan('2');
```

#### lessThan()

Adds a less than operator.

```dart
SmsFilter.where(SmsColumn.ID).lessThan('40');
```

#### greaterThanOrEqualTo()

Adds a greater than or equal to operator.

```dart
SmsFilter.where(SmsColumn.ID).greaterThanOrEqualTo('6');
```

#### lessThanOrEqualTo()

Adds a less than or equal to operator.

```dart
SmsFilter.where(SmsColumn.ID).lessThanOrEqualTo('30');
```

#### notEqualTo()

Checks for inequality.

```dart
SmsFilter.where(SmsColumn.ID).notEqualTo('14');
```

#### like()

Adds the **`LIKE`** operator.

```dart
SmsFilter.where(SmsColumn.BODY).like('%abc%');
```

#### inValues()

Adds the **`IN`** operator.

```dart
SmsFilter.where(SmsColumn.ID).inValues(['13', '15', '20']);
```

#### between()

Adds the **`BETWEEN`** operator.

```dart
SmsFilter.where(SmsColumn.ID).between('10','20');
```

#### not

Adds a **`NOT`** operator.

```dart
SmsFilter.where(SmsColumn.BODY).not.like('%a%');
```

### Combining Methods

#### and()

Adds the **`AND`** operator between two statements.

```dart
SmsFilter.where(SmsColumn.ID)
         .greaterThanOrEqualTo('6')
         .and(SmsColumn.BODY)
         .like('%abc%');
```

#### or()

Adds the **`OR`** operator between two statements.

```dart
SmsFilter.where(SmsColumn.ID)
         .greaterThan('10')
         .or(SmsColumn.ID)
         .lessThan('50');
```

## OrderBy

Creates an **`ORDER BY`** statement.

```dart
OrderBy(SmsColumn.ID);
```

Optionally you can provide a sort order. Defaults to **`DESC`**

```dart
OrderBy(SmsColumn.ID, sort: Sort.ASC);
```

## Sort

| Values     |
| ---------- |
| **`ASC`**  |
| **`DESC`** |