Common Programming Considerations

Integer Values

All integer values passed by server to server extension and back to server in interface methods are all in host byte order (less significant octet first, or so-called "little-Endian" order). This includes integer values of RADIUS attributes and dates.

Important note. All IP addresses are in network byte order. This includes NAS and client addresses, user's IP addresses used in synchronization.

Include Files

If extension needs to use TACACS+ constants (such as TAC_PLUS_AUTHEN_SVC_PPP, TAC_PLUS_AUTHEN_TYPE_CHAP, etc.), it should include tacacs_codes.h file located in /SDK subdirectory of ClearBox Server installation.

Memory Allocation

According to COM programming considerations caller should allocate and free memory for the arguments passed to the callee. If callee allocates memory, it's freed by the caller.

Arguments with BSTR type are allocated by SysAllocString and released by SysFreeString. Memory for arrays is allocated calling CoTaskMemAlloc and freed by CoTaskMemFree.

Extension Properties

Extension may need to read some configuration parameters, and is free in the way how to do it. It may them from ini-file, for instance. ClearBox Server offers standard mechanism to allow user configure extension properties. In order to use it:

1. Extension must be registered in CATID_TACRADServerExtension COM-category defined in ext_category.h file (located in /SDK subdirectory). Component categories is the standard mechanism to determine what plug-ins are available for a host application. A server extension is a plug-in, which are hosted by ClearBox server.
   
   If extension is implemented with ATL library, use IMPLEMENTED_CATEGORY(CATID_TACRADServerExtension) macro (see MSDN for details).
   
   Another way to mark a server extension as supporting this category is to use directly ICatRegister::RegisterClassImplCategories implementation provided by the Component Category Manager.
   
2. Extension must implement standard IPersistPropertyBag interface described in MSDN. Note, that only its Load and Save methods (plus IUnknown methods) are called, so extension needs not to implement InitNew and GetClassID methods.
   All properties are stored in the system registry, and extension may tell the server to encrypt some of them (to prevent unauthorized access). If property name begins with '#' character, it is stored encrypted, in clear text otherwise.
   All properties are stored as UNICODE strings (with VT_BSTR vartype). So if extension has to store some data other than strings, it must perform conversion from/to strings.

Reporting Errors

Different errors may occur during extension execution, and all of them should be logged. At minimal level, extension may return standard HRESULT error code describing the error. If it is not sufficient, extension may use standard COM-exceptions mechanism.

In this case extension implements ISupportErrorInfo to tell server what interfaces do provide information about an error.
When an error occurs, extension calls CreateErrorInfo to create error object and provides error description, which is logged by server.

Important note. Extension methods should not return error codes (values other than S_OK and S_FALSE) in normal conditions as COM-exception mechanism is rather slow, and it might affect performance greatly, especially if error is returned for every packet extension processes.