# DO NOT EDIT THIS FILE!
#
# This code is generated off of PyCDP modules. If you need to make
# changes, edit the generator and regenerate all of the modules.

from __future__ import annotations
import typing

from ..context import get_connection_context, get_session_context

import cdp.target
from cdp.target import (
    AttachedToTarget,
    BrowserContextID,
    DetachedFromTarget,
    ReceivedMessageFromTarget,
    RemoteLocation,
    SessionID,
    TargetCrashed,
    TargetCreated,
    TargetDestroyed,
    TargetID,
    TargetInfo,
    TargetInfoChanged
)


async def activate_target(
        target_id: TargetID
    ) -> None:
    '''
    Activates (focuses) the target.

    :param target_id:
    '''
    connection = get_connection_context('target.activate_target')
    return await connection.execute(cdp.target.activate_target(target_id))


async def attach_to_browser_target() -> SessionID:
    '''
    Attaches to the browser target, only uses flat sessionId mode.

    **EXPERIMENTAL**

    :returns: Id assigned to the session.
    '''
    connection = get_connection_context('target.attach_to_browser_target')
    return await connection.execute(cdp.target.attach_to_browser_target())


async def attach_to_target(
        target_id: TargetID,
        flatten: typing.Optional[bool] = None
    ) -> SessionID:
    '''
    Attaches to the target with given id.

    :param target_id:
    :param flatten: **(EXPERIMENTAL)** *(Optional)* Enables "flat" access to the session via specifying sessionId attribute in the commands.
    :returns: Id assigned to the session.
    '''
    connection = get_connection_context('target.attach_to_target')
    return await connection.execute(cdp.target.attach_to_target(target_id, flatten))


async def close_target(
        target_id: TargetID
    ) -> bool:
    '''
    Closes the target. If the target is a page that gets closed too.

    :param target_id:
    :returns: 
    '''
    connection = get_connection_context('target.close_target')
    return await connection.execute(cdp.target.close_target(target_id))


async def create_browser_context() -> BrowserContextID:
    '''
    Creates a new empty BrowserContext. Similar to an incognito profile but you can have more than
    one.

    **EXPERIMENTAL**

    :returns: The id of the context created.
    '''
    connection = get_connection_context('target.create_browser_context')
    return await connection.execute(cdp.target.create_browser_context())


async def create_target(
        url: str,
        width: typing.Optional[int] = None,
        height: typing.Optional[int] = None,
        browser_context_id: typing.Optional[BrowserContextID] = None,
        enable_begin_frame_control: typing.Optional[bool] = None,
        new_window: typing.Optional[bool] = None,
        background: typing.Optional[bool] = None
    ) -> TargetID:
    '''
    Creates a new page.

    :param url: The initial URL the page will be navigated to.
    :param width: *(Optional)* Frame width in DIP (headless chrome only).
    :param height: *(Optional)* Frame height in DIP (headless chrome only).
    :param browser_context_id: *(Optional)* The browser context to create the page in.
    :param enable_begin_frame_control: **(EXPERIMENTAL)** *(Optional)* Whether BeginFrames for this target will be controlled via DevTools (headless chrome only, not supported on MacOS yet, false by default).
    :param new_window: *(Optional)* Whether to create a new Window or Tab (chrome-only, false by default).
    :param background: *(Optional)* Whether to create the target in background or foreground (chrome-only, false by default).
    :returns: The id of the page opened.
    '''
    connection = get_connection_context('target.create_target')
    return await connection.execute(cdp.target.create_target(url, width, height, browser_context_id, enable_begin_frame_control, new_window, background))


async def detach_from_target(
        session_id: typing.Optional[SessionID] = None,
        target_id: typing.Optional[TargetID] = None
    ) -> None:
    '''
    Detaches session with given id.

    :param session_id: *(Optional)* Session to detach.
    :param target_id: **(DEPRECATED)** *(Optional)* Deprecated.
    '''
    connection = get_connection_context('target.detach_from_target')
    return await connection.execute(cdp.target.detach_from_target(session_id, target_id))


async def dispose_browser_context(
        browser_context_id: BrowserContextID
    ) -> None:
    '''
    Deletes a BrowserContext. All the belonging pages will be closed without calling their
    beforeunload hooks.

    **EXPERIMENTAL**

    :param browser_context_id:
    '''
    connection = get_connection_context('target.dispose_browser_context')
    return await connection.execute(cdp.target.dispose_browser_context(browser_context_id))


async def expose_dev_tools_protocol(
        target_id: TargetID,
        binding_name: typing.Optional[str] = None
    ) -> None:
    '''
    Inject object to the target's main frame that provides a communication
    channel with browser target.

    Injected object will be available as ``window[bindingName]``.

    The object has the follwing API:
    - ``binding.send(json)`` - a method to send messages over the remote debugging protocol
    - ``binding.onmessage = json => handleMessage(json)`` - a callback that will be called for the protocol notifications and command responses.

    **EXPERIMENTAL**

    :param target_id:
    :param binding_name: *(Optional)* Binding name, 'cdp' if not specified.
    '''
    connection = get_connection_context('target.expose_dev_tools_protocol')
    return await connection.execute(cdp.target.expose_dev_tools_protocol(target_id, binding_name))


async def get_browser_contexts() -> typing.List[BrowserContextID]:
    '''
    Returns all browser contexts created with ``Target.createBrowserContext`` method.

    **EXPERIMENTAL**

    :returns: An array of browser context ids.
    '''
    connection = get_connection_context('target.get_browser_contexts')
    return await connection.execute(cdp.target.get_browser_contexts())


async def get_target_info(
        target_id: typing.Optional[TargetID] = None
    ) -> TargetInfo:
    '''
    Returns information about a target.

    **EXPERIMENTAL**

    :param target_id: *(Optional)*
    :returns: 
    '''
    connection = get_connection_context('target.get_target_info')
    return await connection.execute(cdp.target.get_target_info(target_id))


async def get_targets() -> typing.List[TargetInfo]:
    '''
    Retrieves a list of available targets.

    :returns: The list of targets.
    '''
    connection = get_connection_context('target.get_targets')
    return await connection.execute(cdp.target.get_targets())


async def send_message_to_target(
        message: str,
        session_id: typing.Optional[SessionID] = None,
        target_id: typing.Optional[TargetID] = None
    ) -> None:
    '''
    Sends protocol message over session with given id.

    :param message:
    :param session_id: *(Optional)* Identifier of the session.
    :param target_id: **(DEPRECATED)** *(Optional)* Deprecated.
    '''
    connection = get_connection_context('target.send_message_to_target')
    return await connection.execute(cdp.target.send_message_to_target(message, session_id, target_id))


async def set_auto_attach(
        auto_attach: bool,
        wait_for_debugger_on_start: bool,
        flatten: typing.Optional[bool] = None
    ) -> None:
    '''
    Controls whether to automatically attach to new targets which are considered to be related to
    this one. When turned on, attaches to all existing related targets as well. When turned off,
    automatically detaches from all currently attached targets.

    **EXPERIMENTAL**

    :param auto_attach: Whether to auto-attach to related targets.
    :param wait_for_debugger_on_start: Whether to pause new targets when attaching to them. Use ```Runtime.runIfWaitingForDebugger``` to run paused targets.
    :param flatten: **(EXPERIMENTAL)** *(Optional)* Enables "flat" access to the session via specifying sessionId attribute in the commands.
    '''
    connection = get_connection_context('target.set_auto_attach')
    return await connection.execute(cdp.target.set_auto_attach(auto_attach, wait_for_debugger_on_start, flatten))


async def set_discover_targets(
        discover: bool
    ) -> None:
    '''
    Controls whether to discover available targets and notify via
    ``targetCreated/targetInfoChanged/targetDestroyed`` events.

    :param discover: Whether to discover available targets.
    '''
    connection = get_connection_context('target.set_discover_targets')
    return await connection.execute(cdp.target.set_discover_targets(discover))


async def set_remote_locations(
        locations: typing.List[RemoteLocation]
    ) -> None:
    '''
    Enables target discovery for the specified locations, when ``setDiscoverTargets`` was set to
    ``true``.

    **EXPERIMENTAL**

    :param locations: List of remote locations.
    '''
    connection = get_connection_context('target.set_remote_locations')
    return await connection.execute(cdp.target.set_remote_locations(locations))
