View Single Post
Old 04-07-2019, 11:03 AM   #1
juliansader
Human being with feelings
 
Join Date: Jul 2009
Posts: 3,714
Default API functions: Parameters with "Optional" tag should pass nullptr

Optional parameters can be added to extension-provided API functions by adding the "Optional" suffix to parameter names:

Quote:
// When defining/documenting API function parameters:
// - if a (char*,int) pair is encountered, name them buf, buf_sz
// - if a (const char*,int) pair is encountered, buf, buf_sz as well
// - if a lone basicType *, use varNameOut or varNameIn or
// varNameInOptional (if last parameter(s))
However, there are two problems with optional parameters, both of which (as far as I can see) make it impossible for extensions to know which arguments were passed by the script and which were not:

* Even though extensions should register a "vararg" wrapper function for each API function, and this "vararg" function takes two arguments, (void* arglist[], int numparms), this isn't truly a variadic function since numparms is always the same, namely the total number of possible parameters, including all optional ones.

* As implied by the previous point, optional parameters that are omitted by the scripts are still all included in the arglist[]. This would have been acceptable, if the extension could somehow distinguish omitted parameters, for example if omitted parameters were NULL pointers (NB: optional parameters are always pointers). However, omitted parameters are not NULL pointers; instead they look like normal parameters and they simply point to zero values. From the extension's perspective, there is no difference between an omitted parameter and a parameter with argument 0.


Optional parameters are very useful, particularly to expand the features of an existing API function without breaking existing scripts.

There are two possible solutions:
* numparms should reflect the actual number of arguments passed, or
* omitted parameters should be nullptr.

Last edited by juliansader; 07-01-2019 at 12:55 PM.
juliansader is offline   Reply With Quote