Skip to content

Commit 5649025

Browse files
committed
Cleanup integrating-external-libraries
1 parent 8686984 commit 5649025

3 files changed

Lines changed: 436 additions & 139 deletions

File tree

‎docs/integrating-external-libraries/defining-entry-points-for-direct-access.md‎

Lines changed: 46 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,62 +1,87 @@
11
# Defining entry points for direct access
22

3-
A library to be loaded and accessed directly through an ExternalObject instance must publish the following entry points. These must be exported as C functions, not C++ functions:
3+
A library to be loaded and accessed directly through an [ExternalObject instance](./externalobject-object.md) must publish the following entry points.
4+
5+
!!! note
6+
These must be exported as C functions, not C++ functions
47

58
---
69

710
## Entry Points
811

9-
The following entry points are required if you wish to use an ExternalObject instance:
12+
The following entry points are required if you wish to use an [ExternalObject instance](./externalobject-object.md):
1013

1114
### ESInitialize()
1215

1316
`char* ESInitialize (TaggedData* argv, long argc);`
1417

15-
| `argv, argc` | The pointer to and number of arguments passed to the constructor,<br/>in the form of TaggedData. |
16-
|----------------|----------------------------------------------------------------------------------------------------|
18+
#### Description
1719

1820
Called when your library is loaded into memory.
1921

20-
Returns a string of function signatures; see [Library initialization](#library-initialization).
22+
#### Parameters
23+
24+
| Parameter | Description |
25+
| ------------ | -------------------------------------------------------------------------------------------- |
26+
| `argv, argc` | The pointer to and number of arguments passed to the constructor, in the form of TaggedData. |
27+
28+
#### Returns
29+
30+
A string of function signatures; see [Library initialization](#library-initialization).
2131

2232
---
2333

2434
### ESGetVersion()
2535

2636
`long ESGetVersion (void );`
2737

38+
#### Description
39+
2840
Takes no arguments, and returns a version number for the library as a long integer.
2941

3042
The result is available in JavaScript as ExternalObject.version.
3143

44+
#### Returns
45+
46+
Long integer
47+
3248
---
3349

3450
### ESFreeMem()
3551

3652
`void ESFreeMem (void* p);`
3753

38-
| `p` | A pointer to the string. |
39-
|-------|----------------------------|
54+
#### Description
4055

4156
Called to free memory allocated for a null-terminated string passed to or from library functions.
4257

43-
Returns nothing.
58+
| Parameter | Description |
59+
| --------- | ------------------------ |
60+
| `p` | A pointer to the string. |
61+
62+
#### Returns
63+
64+
Nothing
4465

4566
---
4667

4768
### ESTerminate()
4869

4970
`void ESTerminate (void );`
5071

72+
#### Description
73+
5174
Called when your library is being unloaded. See [Library termination](#library-termination).
5275

53-
Takes no arguments, and returns nothing.
76+
#### Returns
77+
78+
Nothing
5479

5580
---
5681

5782
## Additional functions
5883

59-
The shared library can contain any number of additional functions. Each function corresponds to a JavaScript method in the ExternalObject instance. If a function is undefined, ExtendScript throws a run-time error.
84+
The shared library can contain any number of additional functions. Each function corresponds to a JavaScript method in the [ExternalObject instance](./externalobject-object.md). If a function is undefined, ExtendScript throws a run-time error.
6085

6186
Each function must accept the following arguments:
6287

@@ -67,9 +92,9 @@ Each function must accept the following arguments:
6792
The variant data does not support JavaScript objects. The following data types are allowed:
6893

6994
- `undefined`
70-
- `Boolean`
95+
- Boolean
7196
- `double`
72-
- `string` - Must be UTF-8 encoded. The library must define an entry point [ESFreeMem()](#externalobject-functions-esfreemem), which ExtendScript calls to release a returned string pointer. If this entry point is missing, ExtendScript does not attempt to release any returned string data.
97+
- String - Must be UTF-8 encoded. The library must define an entry point [ESFreeMem()](#externalobject-functions-esfreemem), which ExtendScript calls to release a returned string pointer. If this entry point is missing, ExtendScript does not attempt to release any returned string data.
7398
- `Script` - A string to be evaluated by ExtendScript. Use to return small JavaScript scripts that define arbitrarily complex data.
7499

75100
If, when a function is invoked, a supplied parameter is undefined, ExtendScript sets the data type to `undefined` and does not attempt to convert the data to the requested type.
@@ -101,13 +126,14 @@ For each function, the string begins with the function name, followed by an unde
101126

102127
The characters that indicate data types are:
103128

104-
| a | Any type. The argument is not converted. This is the default, if no type is supplied or if a type<br/>code is unrecognized. |
105-
|-----|-------------------------------------------------------------------------------------------------------------------------------|
106-
| b | Boolean |
107-
| d | signed 32 bit integer |
108-
| u | unsigned 32 bit integer |
109-
| f | 64 bit floating point |
110-
| s | String |
129+
| Characeter | Description |
130+
| ---------- | --------------------------------------------------------------------------------------------------------------------------- |
131+
| `a` | Any type. The argument is not converted. This is the default, if no type is supplied or if a type<br/>code is unrecognized. |
132+
| `b` | Boolean |
133+
| `d` | signed 32 bit integer |
134+
| `u` | unsigned 32 bit integer |
135+
| `f` | 64 bit floating point |
136+
| `s` | String |
111137

112138
For example, suppose your library defines these two entry points:
113139

@@ -118,7 +144,7 @@ Two ();
118144

119145
The signature strings for these two functions would be `"One_ds"`, `"Two"`.
120146

121-
!!! note
147+
!!! warning
122148
You cannot define function overloading by returning multiple different signatures for one function.
123149

124150
Attempting to do so produces undefined results.

0 commit comments

Comments
 (0)