35.2. slapi_pblock_get()

Gets the value of a name-value pair from a parameter block.
Syntax

#include "slapi-plugin.h"
int slapi_pblock_get( Slapi_PBlock *pb, int arg, void *value );

Parameters

This function takes the following parameters:

pb
Parameter block.
arg
ID of the name-value pair to get. For a list of IDs that you can specify, see Part V, “Parameter Block Reference”.
value
Pointer to the value retrieved from the parameter block.
Returns

This function returns one of the following values:

  • 0 if successful.
  • -1 if an error occurs (for example, if an invalid ID is specified).
Memory Concerns

The void *value argument should always be a pointer to the type of value you are retrieving: 

int connid = 0;
...
retval = slapi_pblock_get(pb, SLAPI_CONN_ID, &connid);
SLAPI_CONN_ID is an integer value, so you will pass in a pointer to the address of an integer to get the value. Similarly, for a char * value (a string), pass in a pointer to/address of the value. For example: 
char *binddn = NULL;
...
retval = slapi_pblock_get(pb, SLAPI_CONN_DN, &binddn);
With certain compilers on some platforms, you may have to cast the value to (void *).
We recommend that you set the value to 0 or NULL before calling slapi_pblock_get() to avoid reading from uninitialized memory, in case the call to slapi_pblock_get() fails.
In most instances, the caller should not free the returned value. The value will usually be freed internally or through the call to slapi_pblock_destroy(). There are two exceptions, though:
  • If the value is explicitly set by the caller through slapi_pblock_set(). In this case, the caller is responsible for memory management. If the value is freed, it is strongly recommended that the free is followed by a call to slapi_pblock_set() with a value of NULL.
  • With SLAPI_CONN_DN. For some operations like password extop, if the given DN is empty (""), then one byte is leaked when the DN is reassigned to the bind DN. Calling slapi_pblock_get() with SLAPI_CONN_DN does a strdup, unlike most other invocations of slapi_pblock_get(). That memory must be freed with slapi_ch_free_string().
For example, this sets the value explicitly by the caller, which is the first exception: 
char *someparam = NULL;
...
someparam = slapi_ch_strdup(somestring);

slapi_pblock_set(pb, SOME_PARAM, someparam);

someparam = NULL; /* avoid dangling reference */
...
slapi_pblock_get(pb, SOME_PARAM, &someparam);

slapi_pblock_set(pb, SOME_PARAM, NULL); /* make sure no one else can reference this parameter */

slapi_ch_free_string(&someparam);
...
Some internal functions may change the value passed in, so it is recommended to use slapi_pblock_get() to retrieve the value again, rather than relying on a potential dangling pointer. This is shown in the example above, which sets someparam to NULL after setting it in the pblock.
See Also