# APIs

Source: https://docs.interop.io/desktop/capabilities/more/apis/index.html

## Jump List

The jump list is a configurable categorized list of actions that can be shown in the context menu when the user right-clicks on a Windows taskbar icon of an interop-enabled app or a group of such icons:

![Jump List](https://docs.interop.io/desktop/images/platform-features/jump-list.png)

> ⚠️ *Note that, currently, the jump list isn't available for [web groups](https://docs.interop.io/desktop/capabilities/windows/window-management/overview/index.md#window_groups-web_groups).*

### Configuration

The jump list can be enabled, disabled and configured globally and per app. The [app definition](https://docs.interop.io/desktop/developers/configuration/application/index.md#jump_list) will override the global [system configuration](https://docs.interop.io/desktop/developers/configuration/system/index.md#window_settings-jump_list).

> ⚠️ *Note that the jump list configuration allows you to enable or disable the jump list and configure the [predefined actions](#jump_list-predefined_actions) (e.g., change their names or icons), but in order to add custom jump list categories and actions for your apps, you must use the [jump list API](#jump_list-jump_list_api).*

To configure the jump list system-wide, use the `"jumpList"` property of the `"windows"` top-level key in the `system.json` [system configuration](https://docs.interop.io/desktop/developers/configuration/system/index.md) file of **io.Connect Desktop**. The following is the default system jump list configuration:

```json
{
    "windows": {
        "jumpList": {
            "enabled": true,
            "categories": [
                {
                    "title": "Tasks",
                    "actions": [
                        {
                            "icon": "%IO_CD_ROOT_DIR%/assets/images/center.ico",
                            "type": "centerScreen",
                            "singleInstanceTitle": "Center on Primary Screen",
                            "multiInstanceTitle": "Center all on Primary Screen"
                        }
                    ]
                }
            ]
        }
    }
}
```

The `"jumpList"` object has the following properties:

| Property | Type | Description |
|----------|------|-------------|
| `"categories"` | `object[]` | Categorized lists with actions to execute when the user clicks on them. |
| `"enabled"` | `boolean` | If `true` (default), will enable the jump list. |

Each object in the `"categories"` array has the following properties:

| Property | Type | Description |
|----------|------|-------------|
| `"actions"` | `object[]` | List of actions contained in the category. |
| `"title"` | `string` | Title of the category to be displayed in the context menu. |

Each object in the `"actions"` array has the following properties:

| Property | Type | Description |
|----------|------|-------------|
| `"icon"` | `string` | Icon for the action to be displayed in the context menu. Must point to a local file. |
| `"multiInstanceTitle"` | `string` | Title of the action to be displayed in the context menu when there are multiple instances with grouped Windows taskbar icons. |
| `"singleInstanceTitle"` | `string` | Title of the action to be displayed in the context menu when there is a single instance with a single Windows taskbar icon. |
| `"type"` | `string` | Type of the [predefined action](#jump_list-predefined_actions) to execute. |

To override the system configuration per app, use the `"jumpList"` property of the `"details"` top-level key in the [app definition](https://docs.interop.io/desktop/developers/configuration/application/index.md) file. The following example demonstrates how to disable the jump list for an app:

```json
{
    "title": "My App",
    "type": "window",
    "name": "my-app",
    "details": {
        "url": "https://downloadtestfiles.com/",
        "jumpList": {
            "enabled": false
        }
    }
}
```

### Predefined Actions

To use a predefined action, set the `"type"` property of the action object to the respective value (see [Jump List > Configuration](#jump_list-configuration)). The following are the currently supported predefined actions:

- `"centerScreen"` - centers an app or a group of app instances on the primary screen. This action is extremely useful when you have many windows open on multiple displays and can't find the app you need. Use this action to find an app that: you may have moved to another screen or outside the screen bounds altogether; may be hidden behind other windows; may have been resized and become too small to notice; or may have simply blended visually with other apps:

![Center on Primary](https://docs.interop.io/desktop/images/platform-features/jump-list-center.mp4)

- `"newWorkspace"` - opens a new [Workspace](https://docs.interop.io/desktop/capabilities/windows/workspaces/overview/index.md). This action by default is part of the jump list for the Workspaces App. Clicking on the action opens a new empty Workspace in the last opened instance of the Workspaces App. If this action is part of the jump list for another app and the Workspaces App isn't currently open when the user clicks on the action, it will be started:

![New Workspace](https://docs.interop.io/desktop/images/platform-features/jump-list-new-workspace.mp4)

### Jump List API

The jump list API is accessible via the [`IOConnectWindow`](https://docs.interop.io/desktop/reference/javascript/windows/ioconnectwindow/index.md) object which describes an instance of an io.Connect Window:

```javascript
const myWindow = io.windows.my();
// Check whether the jump list is enabled for the current window.
const isJumpListEnabled = await myWindow.jumpList.isEnabled();
```

#### Enable or Disable the Jump List

To enable or disable the jump list dynamically, use the [`setEnabled()`](https://docs.interop.io/desktop/reference/javascript/windows/jumplist/index.md#JumpList-setEnabled) method and pass a Boolean value as an argument:

```javascript
const myWindow = io.windows.my();

// Checking whether the jump list is enabled for the current window.
const isJumpListEnabled = await myWindow.jumpList.isEnabled();

if (!isJumpListEnabled) {
    // Enabling the jump list.
    await myWindow.jumpList.setEnabled(true);
}
```

#### Categories

Jump list categories are used for grouping actions in a section under a common name. You can find a category by name, get a list of all available categories, create a new category or remove an existing one. The categories API is accessible via the `jumpList.categories` object.

To find a category by name, use the [`find()`](https://docs.interop.io/desktop/reference/javascript/windows/jumplistcategoriesapi/index.md#JumpListCategoriesAPI-find) method:

```javascript
const myCategory = await myWindow.jumpList.categories.find("My Category");
```

To get a list of all available categories, use the [`list()`](https://docs.interop.io/desktop/reference/javascript/windows/jumplistcategoriesapi/index.md#JumpListCategoriesAPI-list) method:

```javascript
const categoryList = await myWindow.jumpList.categories.list();
```

To create a category, use the [`create()`](https://docs.interop.io/desktop/reference/javascript/windows/jumplistcategoriesapi/index.md#JumpListCategoriesAPI-create) method. Pass a title for the category and a list of [`JumpListActionSettings`](https://docs.interop.io/desktop/reference/javascript/windows/jumplistactionsettings/index.md) objects describing the actions in the category:

```javascript
// Category settings.
const title = "My Category";
const actions = [
   {
        // Icon for the action. Must point to a local file.
        icon: "../images/action-one.ico",
        // Callback that will be executed when the user clicks on the action.
        callback: () => console.log("Action 1"),
        // Title of the action when there is a single instance with a single Windows taskbar icon.
        singleInstanceTitle: "Execute Action 1",
        // Title of the action when there are multiple instances with grouped Windows taskbar icons.
        multiInstanceTitle: "Execute Action 1 for All"
    },
    {
        icon: "../images/action-two.ico",
        callback: () => console.log("Action 2"),
        singleInstanceTitle: "Execute Action 2",
        multiInstanceTitle: "Execute Action 2 for All"
    }
];

// Creating a category.
await myWindow.jumpList.categories.create(title, actions);
```

To remove a category, use the [`remove()`](https://docs.interop.io/desktop/reference/javascript/windows/jumplistcategoriesapi/index.md#JumpListCategoriesAPI-remove) method and pass the category title as an argument:

```javascript
await myWindow.jumpList.categories.remove("My Category");
```

#### Actions

Each [`JumpListCategory`](https://docs.interop.io/desktop/reference/javascript/windows/jumplistcategory/index.md) object has an `actions` property through which you can access the actions API. You can create, remove or list all available actions in the current category.

To get a list of all available actions in a category, use the [`list()`](https://docs.interop.io/desktop/reference/javascript/windows/jumplistactionsapi/index.md#JumpListActionsAPI-list) method:

```javascript
const myCategory = await myWindow.jumpList.categories.find("My Category");

const actions = await myCategory.actions.list();
```

To create an action in a category, use the [`create()`](https://docs.interop.io/desktop/reference/javascript/windows/jumplistactionsapi/index.md#JumpListActionsAPI-create) method. Pass a list of [`JumpListActionSettings`](https://docs.interop.io/desktop/reference/javascript/windows/jumplistactionsettings/index.md) objects describing the actions.

The following example demonstrates creating an action in the "Tasks" category that will toggle the io.Connect theme:

```javascript
// Finding a category.
const category = await myWindow.jumpList.categories.find("Tasks");
// Action settings.
const actions = [
    {
        icon: "../images/toggle-theme.ico",
        // This action will toggle the io.Connect theme.
        callback: async () => {
            const currentTheme = await io.themes.getCurrent();
            if (currentTheme.name === "dark") {
                io.themes.select("light");
            } else {
                io.themes.select("dark");
            }
        },
        singleInstanceTitle: "Toggle Theme",
        multiInstanceTitle: "Toggle Theme"
    }
];

// Creating actions for an existing category.
await category.actions.create(actions);
```

![Jump List Action](https://docs.interop.io/desktop/images/platform-features/jump-list-action.mp4)

To remove one or more actions from a category, use the [`remove()`](https://docs.interop.io/desktop/reference/javascript/windows/jumplistactionsapi/index.md#JumpListActionsAPI-remove) method and pass a list of [`JumpListActionSettings`](https://docs.interop.io/desktop/reference/javascript/windows/jumplistactionsettings/index.md) objects to remove:

```javascript
const actions = [
   {
        icon: "../images/action-one.ico",
        callback: () => console.log("Action 1"),
        singleInstanceTitle: "Execute Action 1",
        multiInstanceTitle: "Execute Action 1 for All"
    },
    {
        icon: "../images/action-two.ico",
        callback: () => console.log("Action 2"),
        singleInstanceTitle: "Execute Action 2",
        multiInstanceTitle: "Execute Action 2 for All"
    }
];

// Removing actions from a category.
await category.actions.remove(actions);
```

## Hotkeys

The Hotkeys API allows apps to register key combinations and receive notifications when a key combination is pressed by the user irrespective of whether the app is on focus or not. Hotkeys are useful for web apps that don't have access to system resources and can't register global shortcuts.

### Configuration

To control the hotkeys behavior, use the `"hotkeys"` top-level key in the `system.json` [system configuration](https://docs.interop.io/desktop/developers/configuration/system/index.md) file of **io.Connect Desktop**.

Example configuration:

```json
{
    "hotkeys": {
        "enabled": true,
        "blacklist": ["appManager"],
        "reservedHotkeys": ["ctrl+c", "ctrl+p", "ctrl+s"]
    }
}
```

The `"hotkeys"` object has the following properties:

| Property | Type | Description |
|----------|------|-------------|
| `"enabled"` | `boolean` | If `true`, hotkeys will be enabled. |
| `"blacklist"` | `string[]` | List of names of apps that won't be able to register hotkeys. |
| `"reservedHotkeys"` | `string[]` | List of reserved (system or other) hotkeys that app won't be able to override. |
| `"whitelist"` | `string[]` | List of names of apps that will be able to register hotkeys. |

### Hotkeys API

The Hotkeys API is accessible via the [`io.hotkeys`](https://docs.interop.io/desktop/reference/javascript/hotkeys/api/index.md) object.

To register a hotkey, use the [`register()`](https://docs.interop.io/desktop/reference/javascript/hotkeys/api/index.md#API-register) method:

```javascript
// Define a hotkey.
const hotkeyDefinition = {
    hotkey: "shift+alt+c",
    description: "Open Client Details"
};

// This function will be invoked when the hotkey is pressed.
const hotkeyHandler = () => {
    io.appManager.application("Client Details").start();
};

// Register the hotkey.
await io.hotkeys.register(hotkeyDefinition, hotkeyHandler);
```

To remove a hotkey, use the [`unregister()`](https://docs.interop.io/desktop/reference/javascript/hotkeys/api/index.md#API-unregister) and pass the value of the hotkey combination as an argument:

```javascript
await io.hotkeys.unregister("shift+alt+c");
```

To remove all hotkeys registered by your app, use the [`unregisterAll()`](https://docs.interop.io/desktop/reference/javascript/hotkeys/api/index.md#API-unregisterAll) method:

```javascript
await io.hotkeys.unregisterAll();
```

To check if your app has registered a specific hotkey, use the [`isRegistered()`](https://docs.interop.io/desktop/reference/javascript/hotkeys/api/index.md#API-isRegistered) method:

```javascript
// Returns a Boolean value.
const isRegistered = io.hotkeys.isRegistered("shift+alt+c");
```

### Hotkeys View

There is a utility view that allows you to see all hotkeys registered by different apps. You can open it from the **io.Connect Desktop** tray icon menu - right-click on the tray icon to display the menu. When you click on the "Hotkeys" item you will see a list of the hotkeys registered by your app:

![Hotkeys](https://docs.interop.io/desktop/images/platform-features/hotkeys.mp4)

For a complete list of the available Hotkeys API methods and properties, see the [Hotkeys API reference documentation](https://docs.interop.io/desktop/reference/javascript/hotkeys/api/index.md).

## Displays

**io.Connect Desktop** provides a way for apps to programmatically capture screenshots of the available monitors. Based on custom logic you can capture one or all monitors in order to save a snapshot of the visual state at a given moment.

### Configuration

To enable display capturing you must add the `"allowCapture"` property to your app definition file and set it to `true`.

```json
{
    "name": "MyApp",
    "type": "window",
    "allowCapture": true,
    "details": {
        "url": "http://localhost:3000"
    }
}
```

### Displays API

> ⚠️ *Note that as of **io.Connect Desktop** 10.4, the [Intent Resolver UI](https://docs.interop.io/desktop/capabilities/data-sharing/intents/overview/index.md#intent_resolver) requires the Displays API to be enabled in order to operate properly. The Displays API is enabled by default. If you have explicitly disabled it when initializing the [`@interopio/desktop`](https://www.npmjs.com/package/@interopio/desktop) library and the Intent Resolver UI has been enabled, the Displays API will be automatically enabled and a warning will be logged in the console. To disable the Displays API, you must also disable the Intent Resolver UI.*

The Displays API is accessible via the [`io.displays`](https://docs.interop.io/desktop/reference/javascript/displays/api/index.md) object.

#### All Displays

To get all displays, use the [`all()`](https://docs.interop.io/desktop/reference/javascript/displays/api/index.md#API-all) method. It returns an array of all available [`Display`](https://docs.interop.io/desktop/reference/javascript/displays/display/index.md) objects:

```javascript
const allDsiplays = await io.displays.all();
```

#### Primary Display

You can get the primary display with the [`getPrimary()`](https://docs.interop.io/desktop/reference/javascript/displays/api/index.md#API-getPrimary) method:

```javascript
// Returns the primary display.
const primaryDisplay =  await io.displays.getPrimary();
```

Example of finding and capturing the primary display:

```javascript
const display = await io.displays.getPrimary();
const screenshot = await display.capture({ scale:0.5 });
```

#### Specific Display

To get a specific display, use the [`get()`](https://docs.interop.io/desktop/reference/javascript/displays/api/index.md#API-get) method. It accepts a display ID as an argument and resolves with a [`Display`](https://docs.interop.io/desktop/reference/javascript/displays/display/index.md) object:

```javascript
const displayID = 2528732444;

// returns a display by ID
const display = await io.displays.get(displayID);
```

#### Capturing All Displays

To capture all displays, use the [`captureAll()`](https://docs.interop.io/desktop/reference/javascript/displays/api/index.md#API-captureAll) method. It accepts a [`CaptureAllOptions`](https://docs.interop.io/desktop/reference/javascript/displays/capturealloptions/index.md) object and returns a Base64 encoded string or an array of Base64 encoded strings depending on the specified [`combined`](https://docs.interop.io/desktop/reference/javascript/displays/capturealloptions/index.md#CaptureAllOptions-combined) option.

The following example demonstrates how to capture all available displays and combine the screenshots into a single image with `width` set to 2000 pixels. The aspect ratio of the combined images will be preserved (the omitted `keepAspectRatio` property in the `size` object defaults to `true`) and the images will be arranged the way you have arranged your displays from your operating system settings:

```javascript
const screenshot = await io.displays.captureAll({ combined: true, size: { width: 2000 } });
```

The [`CaptureAllOptions`](https://docs.interop.io/desktop/reference/javascript/displays/capturealloptions/index.md) object has the following properties:

| Property | Type | Description |
|----------|------|-------------|
| `combined` | `boolean` | **Required**. If `true`, will return a single image of all captured displays. If `false`, will return separate images for all captured displays. |
| `size` | `object` | Accepts either a [`ScaleOptions`](https://docs.interop.io/desktop/reference/javascript/displays/scaleoptions/index.md) or an [`AbsoluteSizeOptions`](https://docs.interop.io/desktop/reference/javascript/displays/absolutesizeoptions/index.md) object, specifying the size of the output image. |

#### Capturing Single Displays

To capture a single display, use the `capture()` method at top level of the API or on a [`Display`](https://docs.interop.io/desktop/reference/javascript/displays/display/index.md) instance.

When you use the [`capture()`](https://docs.interop.io/desktop/reference/javascript/displays/api/index.md#API-capture) method at top level of the API, pass a [`CaptureOptions`](https://docs.interop.io/desktop/reference/javascript/displays/captureoptions/index.md) object. The following example demonstrates how to use the display ID to find and capture the desired display and also how to specify capturing options. The `width` and `height` of the output image will be half the width and height of the captured monitor. The captured image is returned as a Base64 encoded string:

```javascript
const displayID = 2528732444;
const captureOptions = {
    id: displayID,
    size: { scale: 0.5 }
}

const screenshot = await io.displays.capture(captureOptions);
```

The [`CaptureOptions`](https://docs.interop.io/desktop/reference/javascript/displays/captureoptions/index.md) object has the following properties:

| Property | Type | Description |
|----------|------|-------------|
| `id` | `number` | **Required**. ID of the targeted display. |
| `size` | `object` | Accepts either a [`ScaleOptions`](https://docs.interop.io/desktop/reference/javascript/displays/scaleoptions/index.md) or an [`AbsoluteSizeOptions`](https://docs.interop.io/desktop/reference/javascript/displays/absolutesizeoptions/index.md) object, specifying the size of the output image. |

The [`ScaleOptions`](https://docs.interop.io/desktop/reference/javascript/displays/scaleoptions/index.md) object has only one property - `scale`, which accepts a number. The value you pass to it specifies the size of the output image relative to the actual screen size. For instance, if you use `scale: 0.5` the height and width of the output image will be half the height and width of the captured screen.

The [`AbsoluteSizeOptions`](https://docs.interop.io/desktop/reference/javascript/displays/absolutesizeoptions/index.md) object has the following properties:

| Property | Type | Description |
|----------|------|-------------|
| `height` | `number` | Specifies the height of the output image. Defaults to the captured display height. |
| `keepAspectRatio` | `boolean` | Whether to keep the aspect ratio of the output image when you specify `width` and/or `height` of the output image. If `true` and both `width` and `height` are set, then the specified `width` will be used as a basis for the output image aspect ratio. |
| `width` | `number` | Specifies the width of the output image. Defaults to the captured display width. |

When you use the [`capture()`](https://docs.interop.io/desktop/reference/javascript/displays/display/index.md#Display-capture) method of a [`Display`](https://docs.interop.io/desktop/reference/javascript/displays/display/index.md) instance, pass either a [`ScaleOptions`](https://docs.interop.io/desktop/reference/javascript/displays/scaleoptions/index.md) or an [`AbsoluteSizeOptions`](https://docs.interop.io/desktop/reference/javascript/displays/absolutesizeoptions/index.md) object, specifying the size of the output image. The following example demonstrates how to find and capture all non-primary displays:

```javascript
const screenshots = await Promise.all(
            // Get all displays.
            (await io.displays.all())
            // Filter out the primary display.
            .filter(display => !display.isPrimary)
            .map(display => display.capture({ scale: 0.5 })));
```

#### Capturing Windows & Window Groups

You can use the [`capture()`](https://docs.interop.io/desktop/reference/javascript/windows/ioconnectwindow/index.md#IOConnectWindow-capture) method of an io.Connect Window instance or an io.Connect Window group to capture the respective window or window group. This method works also for minimized windows and window groups but doesn't work for hidden windows.

```javascript
// Capture the current window.
const windowScreenshot = await io.windows.my().capture();

// Capture the current group.
const groupScreenshot = await io.windows.groups.my.capture();
```

#### Converting Display Bounds

Available since io.Connect Desktop 10.2 & @interopio/desktop 6.20.0

To convert bounds between the different coordinate systems, use the [`convertBounds()`](https://docs.interop.io/desktop/reference/javascript/displays/api/index.md#API-convertBounds) method of the Displays API. Pass a [`ConvertBoundsOptions`](https://docs.interop.io/desktop/reference/javascript/displays/convertboundsoptions/index.md) object as a required argument. The method resolves with a [`ConvertBoundsResult`](https://docs.interop.io/desktop/reference/javascript/displays/convertboundsresult/index.md) object containing the converted bounds, the target coordinate system, and the target display:

```javascript
const options = {
    bounds: { top: 100, left: 100, width: 400, height: 300 },
    // Coordinate system of the input bounds.
    type: "physical",
    // Coordinate system to which to convert the input bounds.
    targetType: "logical"
};

const { bounds, type, display } = await io.displays.convertBounds(options);
```

The following coordinate systems are supported, as described in the[`BoundsType`](https://docs.interop.io/desktop/reference/javascript/displays/boundstype/index.md) enumeration:

| Value | Description |
|-------|-------------|
| `"electron"` | Electron DIP pixels. |
| `"logical"` | Location scaled by the primary display scale, size scaled by the target display scale. |
| `"physical"` | Physical screen pixels. |

#### Retrieving Displays by Bounds

Available since io.Connect Desktop 10.2 & @interopio/desktop 6.20.0

To retrieve a display by bounds, use the [`getByBounds()`](https://docs.interop.io/desktop/reference/javascript/displays/api/index.md#API-getByBounds) method of the Displays API. Pass a [`GetByBoundsOptions`](https://docs.interop.io/desktop/reference/javascript/displays/getbyboundsoptions/index.md) object as a required argument:

```javascript
const options = {
    bounds: { top: 100, left: 100, width: 400, height: 300 },
    type: "logical"
};

const display = await io.displays.getByBounds(options);
```

#### Events

The [`onDisplayChanged()`](https://docs.interop.io/desktop/reference/javascript/displays/api/index.md#API-onDisplayChanged) method allows you to handle the event that fires when a display has been modified - its resolution or position has changed, a display has been connected or disconnected, etc. Pass a handler that will be invoked each time a display changes and use the list of [`Display`](https://docs.interop.io/desktop/reference/javascript/displays/display/index.md) objects that it receives as an argument to react to the changes:

```javascript
const handler = (displays) => {
    // React to DPI changes, display connected or disconnected, monitor position changed, etc.
    console.log(displays);
};

io.displays.onDisplayChanged(handler);
```

For a complete list of the available Displays API methods and properties, see the [Displays API reference documentation](https://docs.interop.io/desktop/reference/javascript/displays/api/index.md).

## Cookies

Web apps can retrieve, filter, set and remove cookies programmatically by using the io.Connect Cookies API.

### Configuration

By default, interop-enabled web apps aren't allowed to manipulate cookies. To allow an app to manipulate cookies, use the `"allowCookiesManipulation"` property of the `"details"` top-level key in the [app definition](https://docs.interop.io/desktop/developers/configuration/application/index.md) file:

```json
{
    "details": {
        "allowCookiesManipulation": true
    }
}
```

### Cookies API

The Cookies API is accessible via the [`io.cookies`](https://docs.interop.io/desktop/reference/javascript/cookies/api/index.md) object.

> ⚠️ *Note that the Cookies API always operates on the default browser session, regardless of the session of the calling window (see [Developers > Configuration > Application > Isolated Browser Sessions for Apps](https://docs.interop.io/desktop/developers/configuration/application/index.md#isolated-browser-sessions-for-apps)). Only the cookie storage is isolated, not the API.*

#### Get

To retrieve all cookies, use the [`get()`](https://docs.interop.io/desktop/reference/javascript/cookies/api/index.md#API-get) method:

```javascript
const allCookies = await io.cookies.get();
```

The [`get()`](https://docs.interop.io/desktop/reference/javascript/cookies/api/index.md#API-get) method returns a list of [`Cookie`](https://docs.interop.io/desktop/reference/javascript/cookies/cookie/index.md) objects.

To filter the cookies, pass a [`CookiesGetFilter`](https://docs.interop.io/desktop/reference/javascript/cookies/cookiesgetfilter/index.md) object with the properties which you want to use as a filter.

The following example demonstrates filtering cookies by domain:

```javascript
const filter = { domain: "interop.io" };

// Get a list of cookies for the same domain.
const filteredCookies = await io.cookies.get(filter);
```

The [`CookiesGetFilter`](https://docs.interop.io/desktop/reference/javascript/cookies/cookiesgetfilter/index.md) object has the following optional properties, which you can use in any combination to filter the cookies:

| Property | Type | Description |
|----------|------|-------------|
| `domain` | `string` | Retrieves the cookies whose domains match or are subdomains of the specified domain. |
| `name` | `string` | Filters the cookies by name. |
| `path` | `string` | Retrieves the cookies whose path matches the specified path. |
| `secure` | `boolean` | Filters cookies by their `Secure` attribute. |
| `session` | `boolean` | If `true`, will return only the session cookies. If `false`, will return only the persistent cookies. |
| `url` | `string` | Retrieves the cookies which are associated with the specified URL. If not specified, will retrieve the cookies for all URLs. |

#### Set

To create a cookie, use the [`set()`](https://docs.interop.io/desktop/reference/javascript/cookies/api/index.md#API-set) method. It accepts as a required argument a [`CookiesSetDetails`](https://docs.interop.io/desktop/reference/javascript/cookies/cookiessetdetails/index.md) object with a required `url` property:

```javascript
const cookie = {
    url: "https://example.com",
    name: "MyCookie",
    value: "42"
};

await io.cookies.set(cookie);
```

The [`CookiesSetDetails`](https://docs.interop.io/desktop/reference/javascript/cookies/cookiessetdetails/index.md) object has the following properties:

| Property | Type | Description |
|----------|------|-------------|
| `domain` | `string` | Domain for the cookie. Will be normalized with a preceding dot in order to be valid for subdomains too. |
| `expirationDate` | `number` | The expiration date of the cookie as a number of seconds since the UNIX epoch. If not specified, the cookie will become a session cookie and won't be persisted between sessions. |
| `httpOnly` | `boolean` | If `true`, the cookie will be marked with an `HttpOnly` attribute. Default is `false`. |
| `name` | `string` | Name for the cookie. |
| `path` | `string` | Path for the cookie. |
| `sameSite` | `"unspecified"` \| `"no_restriction"` \| `"lax"` \| `"strict"` | The value to be applied to the `SameSite` attribute. If set to `"no_restriction"`, the `secure` property will be set automatically to `true`. Default is `"lax"`. |
| `secure` | `boolean` | If `true`, the cookie will be marked with a `Secure` attribute. Default is `false`, unless the `SameSite` attribute has been set to `None`. |
| `url` | `string` | **Required.** URL to associate with the cookie. |
| `value` | `string` | Value for the cookie. |

#### Remove

To remove a cookie, use the [`remove()`](https://docs.interop.io/desktop/reference/javascript/cookies/api/index.md#API-remove) method and pass the cookie URL and name:

```javascript
const url = "https://example.com";
const name = "MyCookie";

await io.cookies.remove(url, name);
```

## Environment Variables

io.Connect apps can be allowed dynamic access to all available [environment variables](https://docs.interop.io/desktop/developers/configuration/overview/index.md#environment_variables) registered by the OS and the io.Connect framework via configuration.

> ℹ️ *For details on the environment variables registered by the io.Connect framework, see the [Developers > Configuration > Overview > Environment Variables](https://docs.interop.io/desktop/developers/configuration/overview/index.md#environment_variables) section.*

### Configuration

To allow an app to access all available environment variables, use the `"allowEnvVars"` property of the `"details"` top-level key in the [app definition](https://docs.interop.io/desktop/developers/configuration/application/index.md):

```json
{
    "details": {
        "allowEnvVars": true
    }
}
```

### Dynamic Access

To access all available environment variables registered by the OS and the io.Connect framework dynamically, use the `env` property of the `iodesktop` object injected in the global `window` object. The `env` property is an object containing all available environment variables as properties:

```javascript
const envVars = iodesktop.env;

Object.entries(envVars).forEach((envVar) => {
    const [envVarName, envVarValue] = envVar;

    console.log(`${envVarName}: "${envVarValue}"`);
});
```

## Request Headers

You can allow io.Connect web apps to manipulate the headers for web requests dynamically.

### Configuration

To allow web apps to manipulate request headers dynamically, use the `"allowHeadersManipulation"` top-level key in the [app definition](https://docs.interop.io/desktop/developers/configuration/application/index.md):

```json
{
    "allowHeadersManipulation": true
}
```

### Dynamic Manipulation

To manipulate the request headers for web requests dynamically, use the `customHeaders` property of the `iodesktop` object injected in the global `window` object.

To set custom request headers, use the `set()` method. You can use the returned header ID later to retrieve or remove the header. The following example demonstrates how to set a custom header for all web requests originating from all apps and sent to any URL:

```javascript
const header = { "My-Custom-Header": "custom-header-value" };

const headerId = await iodesktop.customHeaders.set(header);
```

You can also supply a web request filter as a second argument to `set()`, specifying which requests to target:

```javascript
const header = { "My-Custom-Header": "custom-header-value" };
const filter = {
    urls: ["https://my-app.com/assets/*"],
    applications: ["my-app"],
    types: ["mainFrame", "image", "stylesheet"]
};

const headerId = await iodesktop.customHeaders.set(header, filter);
```

The filter object has the following properties:

| Property | Type | Description |
|----------|------|-------------|
| `applications` | `string[]` | Array of io.Connect app names. The headers of all web requests sent from the specified apps will be modified. Providing an empty array won't match any apps and will prevent modifying the request headers. |
| `types` | `string[]` | Array of web request types. The possible array item values are `"mainFrame"`, `"subFrame"`, `"stylesheet"`, `"script"`, `"image"`, `"font"`, `"object"`, `"xhr"`, `"ping"`, `"cspReport"`, `"media"`, `"webSocket"` and `"other"`. You can target requests originating from the main frame or the sub frames, or specify the content type of the targeted web request. Providing an empty array won't match any requests and will prevent modifying the request headers. |
| `urls` | `string[]` | Array of URLs. The headers of all web requests sent to the specified URLs will be modified. Supports wildcard characters (`*`). Providing an empty array won't match any URLs and will prevent modifying the request headers. |

You can use any combination of these properties to fine-tune the filter for matching web requests depending on your specific use case. The `applications` array enables you to filter the apps from which the web requests originate, while the `urls` array enables you to filter them based on their destination. The `types` array enables you to filter the web requests based on their type. Providing an empty array for any of the properties will prevent matching any web requests, effectively preventing all requests from being modified.

> ⚠️ *Note that this feature is available only for apps of type `"window"`. This means that using the `applications` array will work only for such apps. If you want to modify the request headers of other types of web apps (e.g., the Workspaces App or the Web Group App), use the `urls` array instead.*

To retrieve all custom request headers, use the `getAll()` method:

```javascript
const allCustomHeaders = await iodesktop.customHeaders.getAll();
```

To retrieve a specific header, use the `get()` method and pass its ID as an argument:

```javascript
const header = await iodesktop.customHeaders.get(headerId);
```

To remove all custom request headers, use the `removeAll()` method:

```javascript
await iodesktop.customHeaders.removeAll();
```

To remove a specific header, use the `remove()` method and pass its ID as an argument:

```javascript
await iodesktop.customHeaders.remove(headerId);
```

## Proxy Settings

You can configure the proxy settings on system level for all users, or allow io.Connect apps to manipulate them dynamically if different user groups must use different proxy settings.

### Configuration

Available since io.Connect Desktop 9.3

> ⚠️ *Note that the following proxy settings are fully aligned with the Electron proxy settings. For more details about the available settings and example usage, see the [Electron documentation](https://www.electronjs.org/docs/latest/api/structures/proxy-config). If you are experiencing unresolvable problems with the Electron proxy settings, you can try using the settings described in the [Legacy Settings](#proxy_settings-configuration-legacy_settings) section.*

The proxy settings can be changed from the `"proxy"` top-level key in the `system.json` [system configuration](https://docs.interop.io/desktop/developers/configuration/system/index.md) file of **io.Connect Desktop**:

```json
{
    "proxy": {
        "mode": "pac_script",
        "pacScript": "https://my-pac-script.js"
    }
}
```

The `"proxy"` object has the following properties:

| Property | Type | Description |
|----------|------|-------------|
| `"mode"` | `"direct"` \| `"auto_detect"` \| `"pac_script"` \| `"fixed_servers"` \| `"system"` | Proxy mode. |
| `"pacScript"` | `string` | URL pointing to a proxy auto-configuration script (PAC). |
| `"proxyBypassRules"` | `string` | Rules indicating which URLs should bypass the proxy settings. |
| `"proxyRules"` | `string` | Rules indicating which proxies to use. |

To allow an app to manipulate proxy settings dynamically, use the `"allowProxySettingManipulation"` property of the `"details"` top-level key in the [app definition](https://docs.interop.io/desktop/developers/configuration/application/index.md) file:

```json
{
    "details": {
        "allowProxySettingManipulation": true
    }
}
```

### Dynamic Manipulation

To manipulate the proxy settings dynamically, use the `iodesktop` object injected in the global `window` object:

```javascript
const settings = {
    mode: "pac_script",
    pacScript: "https://my-pac-script.js"
};

// Set proxy settings.
iodesktop.setProxySettings(settings);

// Get proxy settings.
const proxySettings = await iodesktop.getProxySettings();
```

The object passed as an argument to `setProxySettings()` has the same shape as the `"proxy"` object described in the [Configuration](#proxy_settings-configuration) section.

## OS Info

You can allow apps to access OS information (list of running processes, OS version, io.Connect start time) through their [app definition](https://docs.interop.io/desktop/developers/configuration/application/index.md). The information can then be retrieved through the `iodesktop` object injected in the global `window` object when the app is started.

### Configuration

To allow an app to access OS information, set the `"allowOSInfo"` property to `true` in the `"details"` top-level key:

```json
{
    "details": {
        "allowOSInfo": true
    }
}
```

### Dynamic Access

To retrieve the necessary OS information, use the `iodesktop` object injected in the global `window` object:

```javascript
// Returns a list of all running processes.
const processes = await iodesktop.os.getProcesses();

// Extracting the PID, name and start time of the first process from the list.
const { pid, name, startTime } = processes[0];

// Returns the OS version as a string.
const version = iodesktop.os.getVersion();

// Returns the io.Connect start time as a string - e.g., "2021-10-20T06:54:49.411Z".
const startTime = iodesktop.glue42StartTime;
```

## Clearing Cache

**io.Connect Desktop** allows your apps to clear different types of cached data at runtime. All methods for clearing cache are available on the `iodesktop` object injected in the global `window` object and resolve when the respective operation has completed.

The same operations are available to the end users from the "Cache" submenu of the tray icon menu of **io.Connect Desktop**.

### Configuration

To allow an app to clear cache, use the `"allowClearingCache"` top-level key in the [app definition](https://docs.interop.io/desktop/developers/configuration/application/index.md) file:

```json
{
    "allowClearingCache": true
}
```

This setting controls the access to all cache clearing methods described below.

### Network Cache

To clear the HTTP cache, use the `clearCache()` method:

```javascript
await iodesktop.clearCache();
```

### Host Resolver Cache

To clear the DNS cache, use the `clearHostResolverCache()` method:

```javascript
await iodesktop.clearHostResolverCache();
```

### Storage Data

Available since io.Connect Desktop 10.4 & @interopio/desktop 6.22.0

To clear the storage data, use the `clearStorageData()` method:

```javascript
await iodesktop.clearStorageData();
```

To clear only specific types of storage, pass an object with a `storages` property holding an array of the storage types to clear:

```javascript
const options = {
    storages: ["cookies", "indexdb"]
};

await iodesktop.clearStorageData(options);
```

> ⚠️ *Note that the object accepted as an argument by the `clearStorageData()` method is fully aligned with the Electron storage data settings. For more details on the available properties and their accepted values, see the [Electron documentation](https://www.electronjs.org/docs/latest/api/session#sesclearstoragedataoptions).*

### Auth Cache

Available since io.Connect Desktop 10.4 & @interopio/desktop 6.22.0

To clear the cached HTTP authentication credentials, use the `clearAuthCache()` method:

```javascript
await iodesktop.clearAuthCache();
```

## Hide & Show Windows

Available since io.Connect Desktop 9.4

If you need to show or hide a window dynamically (e.g., an authentication app) but don't want to initialize the entire [`@interopio/desktop`](https://www.npmjs.com/package/@interopio/desktop) library, use the `showWindow()` and `hideWindow()` methods of the `iodesktop` object injected in the global `window` object:

```javascript
// Hide a window.
await iodesktop.hideWindow();

// Show a hidden window.
await iodesktop.showWindow();
```

## Retrieving System Paths

Available since io.Connect Desktop 9.7.1 & @interopio/desktop 6.10.0

To retrieve any of the system paths used by **io.Connect Desktop**, use the `getPath()` method of the `iodesktop` object injected in the global `window` object and pass as an argument one of the following string values:

| Value | Description |
|-------|-------------|
| `"appData"` | Retrieves the **io.Connect Desktop** working directory (e.g., `C:\Users\<username>\AppData\Local\interop.io\io.Connect Desktop\Desktop`). |
| `"desktop"` | Retrieves the desktop directory for the current user (e.g., `C:\Users\<username>\Desktop`). |
| `"documents"` | Retrieves the documents directory for the current user (e.g., `C:\Users\<username>\Documents`). |
| `"downloads"` | Retrieves the downloads directory for the current user (e.g., `C:\Users\<username>Downloads`). |
| `"exe"` | Retrieves the path to the **io.Connect Desktop** executable file (e.g., `C:\Users\<username>\AppData\Local\interop.io\io.Connect Desktop\Desktop\io-connect-desktop.exe`). |
| `"home"` | Retrieves the profile directory for the current user (e.g., `C:\Users\<username>`). |
| `"music"` | Retrieves the music directory for the current user (e.g., `C:\Users\<username>\Music`). |
| `"pictures"` | Retrieves the pictures directory for the current user (e.g., `C:\Users\<username>\Pictures`). |
| `"recent"` | Retrieves the recent files directory for the current user (e.g., `C:\Users\<username>\AppData\Roaming\Microsoft\Windows\Recent`). |
| `"temp"` | Retrieves the temporary directory for the current user (e.g., `C:\Users\<username>\AppData\Local\Temp`). |
| `"userData"` | Retrieves the [user data directory](https://docs.interop.io/desktop/developers/configuration/system/index.md#folders) for the current environment and region in which **io.Connect Desktop** is running (e.g., `C:\Users\<username>\AppData\Local\interop.io\io.Connect Desktop\UserData\<ENV>-<REG>`). |
| `"videos"` | Retrieves the videos directory for the current user (e.g., `C:\Users\<username>\Videos`). |

The following example demonstrates retrieving the desktop directory for the current user:

```javascript
const desktopDir = await iodesktop.getPath("desktop");
```

## Platform Version

Available since io.Connect Desktop 10.0

To retrieve the platform version, use the `uiVersion` property of the `iodesktop` object injected in the global `window` object:

```javascript
const platformVersion = iodesktop.uiVersion;
```

The `uiVersion` property will return the default platform version or the custom version specified in the `"uiVersion"` property of the `system.json` [system configuration](https://docs.interop.io/desktop/developers/configuration/system/index.md) file of **io.Connect Desktop**.

> ℹ️ *For details on how to specify a custom platform version, see the [Developers > Configuration > System > Platform Version](https://docs.interop.io/desktop/developers/configuration/system/index.md#platform_version) section.*