This documentation covers version 1.0.13 of libsrs2.
The library does not modify any input arguments allocated in the memory of the caller, except possibly for the srs handle. Input email addresses are never modified.
#include <srs2.h>
The srs2 header file must be included.
srs_t
The srs_t structure is a handle to an SRS rewriting engine. There are two ways to construct a handle: srs_new() and srs_init(). It is recommended that srs_new() be used unless you are scared of malloc().
srs_t *srs_new();
Returns a new handle for accessing the SRS rewriting engine. This is the first function you will call in any SRS sequence. If you call srs_new(), you do not need to call srs_init().
void srs_free(srs_t *srs);
Destroys a handle previously allocated by srs_new(). The memory previously used to store secrets is overwritten using memset() and deallocated using free().
void srs_add_secret(srs_t *srs, const char *secret);
Adds a new secret to the SRS library. Only the first secret is used for forward-rewriting addresses. All secrets are attempted for reverse-rewriting addresses. You must call this function at least once. Storage for secrets is allocated using strdup(). The memory containing the original copy of the secret may be freed or reused after this call.
int srs_forward(srs_t *srs, char *buf, int buflen,
const char *sender, const char *alias);
Rewrites sender to appear from the domain given in alias. alias may be an email address or a domain. The NUL-terminated rewritten address is placed in buf, which is of size buflen. If buflen is too small, SRS_EBUFTOOSMALL is returned. A conservative assumption is that the rewritten address will be of size at most strlen(sender) + strlen(alias) + 64.
int srs_forward_alloc(srs_t *srs, char **sptr,
const char *sender, const char *alias);
Similar to srs_forward() except that libsrs2 is responsible for allocating memory to contain the parsed address. A pointer to the rewritten address is written into *sptr. The caller is responsible for freeing this memory. On error, an error code is returned and NULL is written into *sptr. This function never returns SRS_EBUFTOOSMALL.
int srs_reverse(srs_t *srs, char *buf, int buflen, const char *sender);
Rewrites a previously rewritten SRS address into its original form. The NUL-terminated rewritten address is placed in buf, which is of size buflen. If buflen is too small, SRS_EBUFTOOSMALL is returned. The rewritten address will be no longer than sender.
int srs_reverse_alloc(srs_t *srs, char **sptr, const char *sender);
Similar to srs_reverse() except that libsrs2 is responsible for allocating memory to contain the parsed address. A pointer to the rewritten address is written into *sptr. The caller is responsible for freeing this memory. On error, an error code is returned and NULL is written into *sptr. This function never returns SRS_EBUFTOOSMALL.
const char * srs_strerror(int code);
Translates a return code from libsrs2 into a textual description of the error. See Return codes below.
srs_t srs;
srs_init(srs_t *srs);
An alternative way to construct a rewriting engine. This option is not recommended unless you do not have malloc() since it requires recompiling the application if the size of the srs_t structure changes. Trust me, you probably have malloc().
Users calling srs_init() are responsible for updating srs->secrets and srs->numsecrets. This is inelegant and discouraged. It may improve in the future.
int srs_set_separator(srs_t *srs, char c);
char srs_get_separator(srs_t *srs);
Get or set the initial separator used in rewriting. The initial separator is the separator appearing immediately after the SRS0 or SRS1 tag. Administrators may wish to set this separator to some character which their MTA recognises as an email address delimiter, so that messages incoming to SRS addresses may be recognised as all those directed to an srs0 or srs1 account. Permissible characters are +, - and =. Returns SRS_ESEPARATORINVALID if an invalid separator is given.
int srs_set_noforward(srs_t *srs, srs_bool b);
char srs_get_noforward(srs_t *srs);
Set or get the flag which disables all SRS forwards rewriting.
int srs_set_noreverse(srs_t *srs, srs_bool b);
char srs_get_noreverse(srs_t *srs);
Set or get the flag which disables all SRS reverse rewriting.
SRS functions return codes indicating the status of the requested operation. Return codes fall into classes, so that the user may treat all return codes in a class identically, for the purpose of client program behaviour. The class of a return code is given by the SRS_ERROR_TYPE(x) macro. Currently defined classes of return code are:
The specific return codes from SRS functions are mostly self-explanatory. They are listed here. See also srs_strerror(), which returns a textual error message for any return code.