# CaptureRequest

This is main API for capturing player's screen.

I also recommend to check [promise documentation](https://github.com/dankmolot/gm_promise) since `CaptureRequest` heavily uses promises

## RSC.CaptureRequest.New

```rust
CaptureRequest RSC.CaptureRequest.New()
```

Creates a new `CaptureRequest` object.

## .onMessage

```lua
request.onMessage = RSC.Event.New()
-- :On(function( request: CaptureRequest, type: MESSAGE_TYPE, message: str, source: MESSAGE_SOURCE ) end)
```

This event emitted when `CaptureRequest` receive new message.\
Event arguments:

* request - [CaptureRequest](https://pika-soft.gitbook.io/rsc/api/classes/capturerequest)
* type - [MESSAGE\_TYPE](https://pika-soft.gitbook.io/rsc/enums#rsc.message_type)
* message - string
* source - [MESSAGE\_SOURCE](https://pika-soft.gitbook.io/rsc/enums#rsc.message_source)

```lua
-- Example of using request.onMessage event
local request = RSC.CaptureRequest.New()
-- Print every message
request.onMessage:On(function(request, type, message) print(message) end)
-- Capture a player with index 1
request:Capture( Entity(1) ):Await()

-- Printed messages to console:
-- #rsc.notify.copying_screen
-- #rsc.notify.screen_to_image
-- ...
```

## .onResult

```lua
request.onResult = RSC.Event.New()
-- :On(function( request: CaptureRequest, ok: bool, result: str ) end)
```

This event emitted when `CaptureRequest` receive result.\
Event arguments:

* request - [CaptureRequest](https://pika-soft.gitbook.io/rsc/api/classes/capturerequest)
* ok - bool
* result - string

```lua
-- Example of using request.onMessage event
local request = RSC.CaptureRequest.New()
-- Print every message
request.onResult:On(function(request, ok, result) print(ok, result) end)
-- Capture a player with index 1
request:Capture( Entity(1) ):Await()

-- Printed result to console:
-- true   2a975c6d-c086-4c81-8e7a-b5d7dddcac9d
```

## :Capture(...)

```rust
Promise<nil> CaptureRequest:Capture( victim: Player, serviceName?: str, quality?: number )
```

Starts a capture of given player. You can also specify [service](https://pika-soft.gitbook.io/rsc/api/classes/service) name (by default [recommended](https://pika-soft.gitbook.io/rsc/api/service#rsc.recommended_service)) and [quality level](https://pika-soft.gitbook.io/rsc/utilities#rsc.parsequality) (by default 2). Also it will wait until capture queue is free and capture has successfully requested. Also this function can fail.

Errors:

* Requester doesn't have enough rights `#rsc.errors.no_rights` **Clientside only**
* Invalid victim `#rsc.errors.invalid_victim`
* Invalid service (rarely can happen) `#rsc.errors.invalid_service`
* Trying to start new :Capture(...) while in in queue `already in queue`

```lua
-- Make 10 capture requests
for i = 1, 10 do
    local request = RSC.CaptureRequest.New()
    -- Print result when it is received
    request.onResult:On(function(request, ok, result) print("Got result:", result) end)
    -- Start a capture
    print("Starting a capture number " .. i)
    local ok, err = request:Capture( Entity(1) ):SafeAwait()
    if not ok then return ErrorNoHaltWithStack(err) end -- Something failed
    print("Capture successfully started!")
end

-- Console log:
-- Starting a capture number 1
-- Capture successfully started!
-- Got result: 23c97d34-bf73-470c-a32e-f30fae9d0ec8
-- Starting a capture number 2
-- Capture successfully started!
-- Got result: 6b83d65d-9545-42ed-8134-47d97d28c922
-- Starting a capture number 3
-- ...
```

## :WaitForResult()

```rust
Promise<str> CaptureRequest:WaitForResult()
```

Returns a promise that will be fulfilled with a capture result. If capture failed, then promise become rejected with a capture fail reason. Internally used in [CaptureRequest:GetDownloadURL()](#getdownloadurl) and [CaptureRequest:Download()](#download).

```lua
request:Capture( Entity(1) ):Await()
print( request:WaitForResult():SafeAwait() ) -- true   2181af7b-48f6-4169-af04-d68053a27f1e
```

## :GetDownloadURL()

```rust
Promise<str> CaptureRequest:GetDownloadURL()
```

Gets a download url after result received. Can also throw an error.\
Same as `request:GetService():GetDownloadURL( result, request:GetQuality(), request:GetPrepareData() )`

```lua
request:Capture( Entity(1) ):Await()
print( request:GetDownloadURL():Await() ) -- https://...
```

## :Download()

```rust
Promise<str> CaptureRequest:Download()
```

Downloads capture image after result received. Can also throw an error.\
Same as `request:GetService():Download( result, request:GetQuality(), request:GetPrepareData() )`

```lua
request:Capture( Entity(1) ):Await()
print( request:Download():Await() ) -- PNG...
```

## :IsValid()

```rust
bool CaptureRequest:IsValid()
```

## :IsInQueue()

```rust
bool CaptureRequest:IsInQueue()
```

## :IsEnded()

```rust
bool CaptureRequest:IsEnded()
```

## :GetVictim()

```rust
Player/nil CaptureRequest:GetVictim()
```

## :GetService()

```rust
Service/nil CaptureRequest:GetService()
```

## :GetQuality()

```rust
number CaptureRequest:GetQuality()
```

## :GetUniqueID()

```rust
string CaptureRequest:GetUniqueID()
```

Only valid after successful [:Capture()](#capture-...)

## :GetPrepareData()

```rust
str/nil CaptureRequest:GetPrepareData()
```

## :GetReceivers()

```rust
Array<Player> CaptureRequest:GetReceivers()
```

## :IsOk()

```rust
bool/nil CaptureRequest:IsOk()
```

## :GetResult()

```rust
str CaptureRequest:GetResult()
```

## :AddReceiver(...)

```rust
CaptureRequest:AddReceiver( receiver: Player )
```