Gets the value of a name-value pair from a parameter block.
#include "slapi-plugin.h" int slapi_pblock_get( Slapi_PBlock *pb, int arg, void *value );
This function takes the following parameters:
ID of the name-value pair that you want to get. For a list of IDs that you can specify, see Chapter 15, Data Type and Structure Reference
Pointer to the value retrieved from the parameter block.
This function returns one of the following values:
0 if successful.
-1 if an error occurs (for example, if an invalid ID is specified).
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/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() . The exception is 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. For example:
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 references this. */ 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 previous example, which sets someparam to NULL after setting it in the parameter block.