scpt_parse_params

March 26, 2020 Contributors

Name

scpt_parse_params — Parse scriptlet function parameters

Synopsis

#include "modules/scriptlets/ec_scriptlet.h"

| void **scpt_parse_params** ( | thr, |   |
|   | fmt, |   |
|   | ); |   |

scpt_thread * <var class="pdparam">thr</var>;
const char * <var class="pdparam">fmt</var>;
<var class="pdparam">...</var>;

Description

**Configuration Change. ** This feature is available as of version 3.2.

Parse scriptlet function parameters.

Parameters

thr

script thread

fmt

A format string that specifies the types of the arguments.

The variable argument.

The format string can use the following placeholders:

  • ? – The next placeholder is optional. If the argument is not present, then the corresponding variadic arguments will be skipped over unmodified, allowing you to initialize them to some default value.

  • s – A string parameter. Corresponds to the address of a const char * and the address of an int to receive the string and its length.

  • i – An integer parameter. Corresponds to the address of an integer to receive its value.

  • d – A double parameter. Corresponds to the address of a double to receive its value.

  • o – An object. Corresponds to a string representation of the type and a pointer to pointer to the type of the object.

  • O – An object plus a reference. Corresponds to a string representation of the type, a pointer to pointer to the type of the object, and a pointer to an integer to hold a reference to the object. This reference must be released by the caller at an appropriate time.

  • c – A closure. Corresponds to the address of an integer that holds the pinned reference. Use scpt_push_ref to pass this back to Lua. Use scpt_unpin_ref to allow it to be garbage collected.

  • t – A table. Corresponds to the address of an integer that holds the "acceptable index" of the table on the stack. The index will be set to -1 if the parameter was marked as optional, it is present, and it is not a table.

  • T – A table. Corresponds to the address of an integer that holds the pinned reference. Use scpt_push_ref to pass this back to Lua. Use scpt_unpin_ref to allow it to be garbage collected.

  • @O – an object plus a reference. Corresponds to a string representation of the type, a pointer to pointer to the type of the object, and a pointer to a pointer to hold a reference to the object. This reference must be released by the caller at an appropriate time using lua_delrefobj().

  • @c – a closure. Corresponds to the address of a pointer that holds the pinned reference. Use lua_pushobjref() to pass this back to lua. Use lua_delrefobj() to allow it to be garbage collected.

  • @T – A table. Corresponds to the address of a pointer that holds the pinned reference. Use lua_pushobjref() to pass this back to lua. Use lua_delrefobj() to allow it to be garbage collected.

An error is raised if the parameters do not match the format string.

Return Value

This function returns the previously set pointer value.

Threading

It is legal to call this function in any thread.

See Also

Chapter 42, Scriptlet (and Alerting) Functions