The SetProp function enables you to use a variable value throughout an IPB session without using a global variable, which is susceptible to namespace conflicts with other sessions. SetProp is one of a set of three functions:
-
Use SetProp to register a new variable with the session or to change the value of an existing variable.
-
Use GetProp to access the variable.
-
Use RemoveProp to remove the variable from the list of variables associated with the session when it is no longer needed.
Suppose you want to throw an exception from within a PBNI extension and the exception itself is also defined by the PBNI extension. You call the IPB_Session NewObject function to create an instance of the exception, causing the PBX_CreateNonVisualObject function to be called.
One way to set the value of the fields of the exception before the function returns in a thread-safe manner is to create a new object or structure to hold the exception information before calling NewObject. You can call SetProp to store the structure or the object in the current IPB_Session. When PBX_CreateNonVisualObject is called, you can call GetProp to get the structure or object to obtain the exception information, then call RemoveProp to remove the data you stored in the current session.
You can also use these functions when initializing and uninitializing a session. If the extension exports the PBX_NOTIFY function, the PBVM calls PBX_Notify immediately after an extension PBX is loaded and just before the PBX is unloaded. You can use this function to initialize and uninitialize a session. For example, you could create a session manager object, and store it in the IPB session using the SetProp function. Later, you could use GetProp to obtain the session object.
