1# External (template)
2
3Class `Napi::External<T>` inherits from class [`Napi::TypeTaggable`][].
4
5The `Napi::External` template class implements the ability to create a `Napi::Value` object with arbitrary C++ data. It is the user's responsibility to manage the memory for the arbitrary C++ data.
6
7`Napi::External` objects can be created with an optional Finalizer function and optional Hint value. The Finalizer function, if specified, is called when your `Napi::External` object is released by Node's garbage collector. It gives your code the opportunity to free any dynamically created data. If you specify a Hint value, it is passed to your Finalizer function.
8
9Note that `Napi::Value::IsExternal()` will return `true` for any external value.
10It does not differentiate between the templated parameter `T` in
11`Napi::External<T>`. It is up to the addon to ensure an `Napi::External<T>`
12object holds the correct `T` when retrieving the data via
13`Napi::External<T>::Data()`. One method to ensure an object is of a specific
14type is through [type tags](./object.md#TypeTag).
15
16## Methods
17
18### New
19
20```cpp
21template <typename T>
22static Napi::External Napi::External::New(napi_env env, T* data);
23```
24
25- `[in] env`: The `napi_env` environment in which to construct the `Napi::External` object.
26- `[in] data`: The arbitrary C++ data to be held by the `Napi::External` object.
27
28Returns the created `Napi::External<T>` object.
29
30### New
31
32```cpp
33template <typename T>
34static Napi::External Napi::External::New(napi_env env,
35                    T* data,
36                    Finalizer finalizeCallback);
37```
38
39- `[in] env`: The `napi_env` environment in which to construct the `Napi::External` object.
40- `[in] data`: The arbitrary C++ data to be held by the `Napi::External` object.
41- `[in] finalizeCallback`: A function called when the `Napi::External` object is released by the garbage collector accepting a T* and returning void.
42
43Returns the created `Napi::External<T>` object.
44
45### New
46
47```cpp
48template <typename T>
49static Napi::External Napi::External::New(napi_env env,
50                    T* data,
51                    Finalizer finalizeCallback,
52                    Hint* finalizeHint);
53```
54
55- `[in] env`: The `napi_env` environment in which to construct the `Napi::External` object.
56- `[in] data`: The arbitrary C++ data to be held by the `Napi::External` object.
57- `[in] finalizeCallback`: A function called when the `Napi::External` object is released by the garbage collector accepting T* and Hint* parameters and returning void.
58- `[in] finalizeHint`: A hint value passed to the `finalizeCallback` function.
59
60Returns the created `Napi::External<T>` object.
61
62### Data
63
64```cpp
65T* Napi::External::Data() const;
66```
67
68Returns a pointer to the arbitrary C++ data held by the `Napi::External` object.
69
70[`Napi::TypeTaggable`]: ./type_taggable.md
71