Core API/Methods: Difference between revisions

Newer edit →

VisualWikitext

Revision as of 14:45, 23 September 2024

Methods are used to execute actions and request data back from the API.

Launching

launch

Emulate the scanning of a token.

Parameters

This method accepts two types of parameters:

A single string, in which case the string will be treated as the token text.
Or an object with the following keys:

Key	Type	Required	Description
type	string	No	An internal category of the type of token being scanned. Not currently in use outside of logging.
uid	string	No*	The UID of the token being scanner. For example, the UID of an NFC tag. Used for matching mappings.
text	string	No*	The main text to be processed from a scan, should contain TapScript.
data	string	No*	The raw data read from a token, converted to a hexadecimal string. Used in mappings and detection of NFC toys such as Amiibos and Lego Dimensions.

These parameters allow emulating a token exactly as it would be read directly from an attached reader on the server. A request's parameters must contain at least a populated uid, text or data value.

Result

This method returns null on success.

Currently, it is not reported if the launched TapScript encounters an error during launching.

Example

stop

Kill any active launcher, if possible.

Parameters

None.

Result

This method returns null on success.

Currently, it is not reported if a process was killed or not.

Example

history

Returns a list of the last recorded token launches.

Parameters

None.

Result

Example

Media

media.search

Query the media database and return all matching indexed media.

This request accepts the following parameters object:

Key	Type	Required	Description
query	string	Yes	Case-insensitive search by filename. By default, query is split by white space and results are found which contain every word.
system	string[]	No	Case-sensitive list of system IDs to restrict search to. A missing key or empty list will search all systems.
maxResults	number	No	Max number of results to return. Default is 250.

And a response with the following results object:

Key	Type	Required	Description
results	Media[]	Yes	A list of all search results from the given query.
total	number	Yes	Total number of search results.

Media object

Key	Type	Required	Description
system	System	Yes	System which the media has been indexed under.
name	string	Yes	A human-readable version of the result's filename without a file extension.
path	string	Yes	Path to the media file. If possible, this path will be compressed into the `<system>/<path>` launch format.

System object

Key	Type	Required	Description
id	string	Yes	Internal system ID for this system.
name	string	Yes	Display name of the system.
category	string	Yes	Category of system. This field is not yet formalised.

media.index

Start a new media database index.

This method can, optionally, take a list of strings of system IDs to restrict the index to just those systems.

This method does not block and wait for the index to complete. It will return a response immediately and start in the background. media.indexing notifications will be sent to show progress of current indexing process.

systems

List all currently indexed systems.

This method has no parameters and returns a response results object of a list of System objects.

Settings

settings

List currently set configuration settings.

This method will list values set in the Config File. Values may be hidden which are not appropriate to be read remotely.

Parameters

This method has no parameters.

Results

Key	Type	Required	Description
reader	string[]	Yes	A list of manually configured reader driver connection strings. See reader.
audioFeedback	boolean	Yes
detectReaders	boolean	Yes
insertMode	boolean	Yes
insertModeBlocklist	string[]	Yes
insertModeExitDelay	number	Yes
consoleLogging	boolean	Yes
debug	boolean	Yes	See debug.
systems	Systems config	Yes	The systems section of the config file.

Systems config

Key	Type	Required	Description
rootFolder	string[]	Yes

API config

settings.update

Update one or more settings in-memory and save changes to disk.

Mappings

mappings

List all mappings.

Returns a list of all active and inactive mappings entries stored on server.

Parameters

Results

mappings.new

Create a new mapping.

Parameters

Results

mappings.delete

Delete an existing mapping.

Parameters

Results

mappings.update

Change an existing mapping.

Parameters

Results

Readers

readers

List all currently connected readers.

Parameters

Results

readers.write

Attempt to write given text to the first available write-capable reader, if possible.

@@ Line 1: / Line 1: @@
-=== Launching ===
+Methods are used to execute actions and request data back from the API.
-==== launch ====
+== Launching ==
+=== launch ===
 Emulate the scanning of a token.
+==== Parameters ====
 This method accepts two types of parameters:
-* A single string, in which case the string will be treated as the token text with default launch options. Similar to the [[TapTo API#Launch Endpoint|Launch Endpoint]].
+* A single string, in which case the string will be treated as the token text.
-* Or a parameters object with the following keys:
+* Or an object with the following keys:
 {| class="wikitable"
@@ Line 37: / Line 40: @@
 These parameters allow emulating a token exactly as it would be read directly from an attached reader on the server. A request's parameters must contain at least a populated <code>uid</code>, <code>text</code> or <code>data</code> value.
-This method does not have any response results. Currently, it is not reported if the launched TapScript encounters an error during launching.
+==== Result ====
+This method returns null on success.
+Currently, it is not reported if the launched TapScript encounters an error during launching.
+==== Example ====
-==== stop ====
+=== stop ===
 Kill any active launcher, if possible.
-This methods takes no parameters and does not currently report whether it was successful or not.
+==== Parameters ====
+None.
+==== Result ====
+This method returns null on success.
-==== history ====
+Currently, it is not reported if a process was killed or not.
-=== Media ===
+==== Example ====
-==== media.search ====
+=== history ===
+Returns a list of the last recorded token launches.
+==== Parameters ====
+None.
+==== Result ====
+==== Example ====
+== Media ==
+=== media.search ===
 Query the media database and return all matching indexed media.
@@ Line 136: / Line 160: @@
 |Category of system. This field is not yet formalised.
 |}
-==== media.index ====
+=== media.index ===
 Start a new media database index.
@@ Line 143: / Line 168: @@
 This method does not block and wait for the index to complete. It will return a response immediately and start in the background. <code>media.indexing</code> notifications will be sent to show progress of current indexing process.
-==== systems ====
+=== systems ===
 List all currently indexed systems.
 This method has no parameters and returns a response results object of a list of [[TapTo API#System object|System objects]].
-=== Settings ===
+== Settings ==
-==== settings ====
+=== settings ===
 List currently set configuration settings.
 This method will list values set in the [[Config File (tapto.ini)|Config File]]. Values may be hidden which are not appropriate to be read remotely.
-===== Parameters =====
+==== Parameters ====
 This method has no parameters.
@@ Line 226: / Line 251: @@
 ====== API config ======
-==== settings.update ====
+=== settings.update ===
 Update one or more settings in-memory and save changes to disk.
 === Mappings ===
-==== mappings ====
+=== mappings ===
 List all mappings.
@@ Line 240: / Line 265: @@
 ===== Results =====
-==== mappings.new ====
+=== mappings.new ===
 Create a new mapping.
@@ Line 247: / Line 272: @@
 ===== Results =====
-==== mappings.delete ====
+=== mappings.delete ===
 Delete an existing mapping.
@@ Line 254: / Line 279: @@
 ===== Results =====
-==== mappings.update ====
+=== mappings.update ===
 Change an existing mapping.
@@ Line 261: / Line 286: @@
 ===== Results =====
-=== Readers ===
+== Readers ==
-==== readers ====
+=== readers ===
 List all currently connected readers.
@@ Line 270: / Line 295: @@
 ===== Results =====
-==== readers.write ====
+=== readers.write ===
 Attempt to write given text to the first available write-capable reader, if possible.
@@ Line 277: / Line 302: @@
 ===== Results =====
-=== Clients ===
+== Clients ==
 ''Clients can only be managed through the API via a device-local connection.''
-==== clients ====
+=== clients ===
 List all clients (including disconnected) and associated data.
-==== clients.new ====
+=== clients.new ===
 Create a new client with a newly generated ID and secret.
-==== clients.delete ====
+=== clients.delete ===
 Delete an existing client.
-=== Service ===
+== Service ==
-==== version ====
+=== version ===
 Return server's current version and platform.