# `ExOxvif.Events`
[🔗](https://github.com/cortfritz/ex_oxvif/blob/v0.1.0/lib/ex_oxvif/events.ex#L1)

Events service: pull-point subscriptions.

    {:ok, sub} = ExOxvif.Events.create_pull_point(session, termination: 60_000)
    {:ok, messages} = ExOxvif.Events.pull_messages(session, sub, wait: 5_000)

Durations are given in milliseconds and sent to the device as ISO 8601
durations. A subscription expires unless renewed with `renew/3`.

# `create_pull_point`

```elixir
@spec create_pull_point(ExOxvif.Session.t(), keyword()) ::
  {:ok, ExOxvif.Events.Subscription.t()} | {:error, ExOxvif.Error.t()}
```

Create a pull-point subscription.

Options:

  * `:filter` - a topic expression, e.g. `"tns1:VideoSource/MotionAlarm"`
  * `:termination` - initial lifetime in milliseconds (device default if
    omitted)

# `pull_messages`

```elixir
@spec pull_messages(
  ExOxvif.Session.t(),
  ExOxvif.Events.Subscription.t() | String.t(),
  keyword()
) ::
  {:ok, [ExOxvif.Events.Message.t()]} | {:error, ExOxvif.Error.t()}
```

Pull pending messages, waiting on the device for up to `:wait`
milliseconds (default 5000) for at least one.

Options: `:wait`, `:max_messages` (default 100). The call `:timeout`
defaults to `:wait` plus 15 seconds.

# `renew`

```elixir
@spec renew(
  ExOxvif.Session.t(),
  ExOxvif.Events.Subscription.t() | String.t(),
  pos_integer(),
  ExOxvif.call_opts()
) :: {:ok, String.t()} | {:error, ExOxvif.Error.t()}
```

Extend a subscription to `termination` milliseconds from now. Returns the
new termination time reported by the device.

# `unsubscribe`

```elixir
@spec unsubscribe(
  ExOxvif.Session.t(),
  ExOxvif.Events.Subscription.t() | String.t(),
  ExOxvif.call_opts()
) :: :ok | {:error, ExOxvif.Error.t()}
```

Cancel a subscription.

---

*Consult [api-reference.md](api-reference.md) for complete listing*