sieve_parse_args
Name
sieve_parse_args — Parses arguments for a Sieve extension
Synopsis
#include "sieve/ecsieve.h"
| int **sieve_parse_args** ( | args, | |
| | errbuf, | |
| | errbuflen, | |
| | offset, | |
| | fmt, | |
| | ...); | |
SIEVEARGS * <var class="pdparam">args</var>;
char * <var class="pdparam">errbuf</var>;
int <var class="pdparam">errbuflen</var>;
int <var class="pdparam">offset</var>;
const char * <var class="pdparam">fmt</var>;
<var class="pdparam">...</var>;
Description
This function parses arguments for a Sieve extension.
- args
-
The arguments to parse.
- errbuf
-
The buffer to hold the reason for an error.
- errbuflen
-
The size of
errbufin bytes. - offset
-
Which argument to treat as the first.
- fmt
-
A format string that specifies the types of the arguments that you expect.
- ...
-
The variable argument(s).
The format string can be composed from the following place holders:
-
?– indicates that 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 to some default value. -
%– expects a hash parameter. Corresponds to the address of a SIEVEARGS * to hold the hash pointer. -
s– expects 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– expects a numeric parameter. Corresponds to the address of a SIEVEARGS * and an u_int32_t to receive its value. -
@– expects a stringlist. Corresponds to the address of a SIEVEARGS* to hold the stringlist pointer. -
*– expects any Sieve value. Corresponds to the address of a SIEVEARGS * to hold the pointer. -
:{COMPARATOR}– an optional Sieve comparator specifier. Corresponds to an int * arg that will be set to one of theSIEVE_COMP_XXXcomparator identifiers. -
:{ADDRESS-PART}– an optional addressing qualifier, such as:localpartor:domain. Corresponds to an int * arg that will be set to one of theSIEVE_ADDRPART_XXXaddressing identifiers. -
:{MATCH-TYPE}– an optional match type specifier, such as:is,:containsor:matches. Corresponds to two int* args that will be set to one of theSIEVE_MATCH_XXXidentifiers andSIEVE_REL_XXXidentifiers.* -
:{name} expects a tagged argument:nameto be present. Has no corresponding argument, unless prefixed by a?, in which case the argument must be the address of an int that will be set to1if the parameter is present. -
:{name:s}– expects:namefollowed by a string. Corresponding args are as though you specifieds. The Boolean flag that:{name}would have had does not apply to this case. You may specify any argument specifiers inside the curly braces, except for additional tagged argument names (rfc3028 forbids that usage style). -
?:{name=i}–:nameis optional. Corresponding args are &int, int. The former will be updated to the value of the latter. This can be used to implement mutually exclusive tags. See the example below.
Find below some examples with error handling omitted:
const char *str; int str_len;
sieve_parse_args(args, errbuf, sizeof(errbuf), 0, 's', &str, &str_len);
SIEVEARGS *arg;
sieve_parse_args(args, errbuf, sizeof(errbuf), 0,
'@', &arg);
sieve_parse_args(args, errbuf, sizeof(errbuf), 0,
'%', &arg);
sieve_parse_args(args, errbuf, sizeof(errbuf), 0,
'*', &arg);
u_int32_t num; sieve_parse_args(args, errbuf, sizeof(errbuf), 0,
'i', &num);
// requires that :tagged be in the args
sieve_parse_args(args, errbuf, sizeof(errbuf), 0, ':{tagged}');
// :tagged is optional
int tagged = 0;
sieve_parse_args(args, errbuf, sizeof(errbuf), 0, '?:{tagged}', &tagged);
// mutually exclusive tags.
// selected will be set to either USE_LOCALPART or USE_DOMAIN
// depending on whether :localpart or :domain tags were found.
// or left at 0 if neither were present.
int selected = 0;
sieve_parse_args(args, errbuf, sizeof(errbuf), 0, '?:{localpart=i}?:{domain=i}',
&selected, USE_LOCALPART, &selected, USE_DOMAIN);
On success this function returns 1, zero on failure.
It is legal to call this function in any thread.