saf-esm.h File Reference

ESF Manager ESM Loader and Interface and ESM Module API. More...

Data Structures
struct	SafEsmApi
	ESM Module API Procedure Table. More...
struct	SafLockInfo
	ESM Module API Optional Lock Information. More...
struct	SafPTab
	ESM Module Procedure Table. More...
struct	SafEsmConfig
	ESM Module Configuration. More...
Defines
#define	SafESM_H
#define	SafESM_API_VER_MAJ 1
	structure major version
#define	SafESM_API_VER_MIN 4
	structure minor version
#define	SafQUERY_MT 1
	32-bit int, nonzero for multithreaded env
#define	SafQUERY_ALLGRP 2
	32-bit int, nonzero if all-groups mode
#define	SafQUERY_THREADID 3
	unsigned long, OS thread ID
#define	SafQUERY_NAME 4
	const-char pointer, server name
#define	SafQUERY_FEDERATE 5
	char pointer, value of [Operation] / Federate in ESF config, or null
#define	SafQUERY_REDUNDANT 6
	char pointer, value of [Operation] / Redundant in ESF config, or null
#define	SafCTL_LOCK_TMOUT 1
	32-bit int, minimum lock timeout (seconds)
#define	SafESM_API_LOCK_INFO_VER 1
	structure version
#define	SafESM_API_LOCK_GLOBAL 0
	lock whole subsystem (default)
#define	SafESM_API_LOCK_LOCAL 1
	lock just in process
#define	SafESM_PT_VER 1
	Table version.
#define	SafESM_IF_VER 1
	Initial interface version.
#define	SafESM_UPDATE 0
	Normal Update request.
#define	SafESM_UPDATED 1
	Cached Update request (update private data only).
#define	SafESM_REFRESH 2
	Refresh request (flush all private data).
#define	SafESM_RECONFIG 0
#define	SafESM_CFG_VER 1
	Structure version.
#define	SafESMRC_OK 0
	Success.
#define	SafESMRC_NOTIMPL 1
	Procedure is not implemented.
#define	SafESMRC_PARAM 2
	Invalid parameter.
#define	SafESMRC_RESOURCE 3
	Resource allocation failure.
#define	SafESMRC_EXTERNAL 4
	External failure (eg in ESM).
#define	SafESMRC_MGRFAIL 5
	Failure in an ESF Manager service.
#define	SafESMRC_FAIL 100
	Other failure.
Functions
mf_uns32	SafEsmInit (struct SafInit *Init)
	ESF ESM Module Loading and Initialization.
mf_uns32	SafEsmExit (void)
	Inform ESM Modules of Process Exit.
mf_uns32	SafEsmUnload (void)
	Unload ESM Modules.
mf_uns32	SafEsmEnable (mf_uns32 Index)
mf_uns32	SafEsmDisable (mf_uns32 Index)
const char *	SafEsmName (mf_uns32 Index)
	Provide the Name of an ESM Module (For Logging).
mf_uns32	SafEsmCVerify (mf_uns32 EsmIdx, struct safpb_parameter_block *)
	Call an ESM Module's `Verify` Procedure.
mf_uns32	SafEsmCAuth (mf_uns32 EsmIdx, struct safpb_parameter_block *)
	Call an ESM Module's `Auth` Procedure.
mf_uns32	SafEsmCXAuth (mf_uns32 EsmIdx, struct safpb_parameter_block *)
	Call an ESM Module's `XAuth` Procedure.
mf_uns32	SafEsmCAdmin (mf_uns32 EsmIdx, struct safpb_parameter_block *)
	Call an ESM Module's `Admin` Procedure.
mf_uns32	SafEsmCControl (mf_s32 Type, mf_uns32 EsmIdx, void *Data)
	Call an ESM Module's `Control` Procedure.
mf_uns32	SafEsmCUpdate (mf_s32 Type, mf_uns32 EsmIdx, struct safpb_parameter_block *)
	Call an ESM Module's `Update` Procedure.
mf_uns32	SafExtractVerifyStrings (struct safpb_parameter_block Request, char UserBuf, mf_uns32 UserMax, char PassBuf, mf_uns32 PassMax, char NPassBuf, mf_uns32 NPassMax, char GroupBuf, mf_uns32 GroupMax, void Reserved)
	Extract the variable-length string data from a Verify request.
mf_uns32	SafExtractAuthStrings (struct safpb_parameter_block Request, char ClassBuf, mf_uns32 ClassMax, char EntityBuf, mf_uns32 EntityMax, char FacilityBuf, mf_uns32 FacilityMax, char TransBuf, mf_uns32 TransMax, void Reserved)
	Extract the variable-length string data from an Auth request.
mf_uns32	SafExtractXAuthStrings (struct safpb_parameter_block Request, char ClassBuf, mf_uns32 ClassMax, char EntityBuf, mf_uns32 EntityMax, char String1Buf, mf_uns32 String1Max, char String2Buf, mf_uns32 String2Max, void Reserved)
	Extract the variable-length string data from an XAuth request.

Detailed Description

ESF Manager ESM Loader and Interface and ESM Module API.

Data structures and other definitions for the ESF Manager ESM Loader and ESM Module Interface.

See also:: saf-esm.c

Function Documentation

mf_uns32 SafEsmInit ( struct SafInit * Init )

ESF ESM Module Loading and Initialization.

For internal use only.

When ESF Manager is initialized, it calls this function to load and initialize all of the configured ESM Modules. Like the other init functions, this is not threadsafe.

Parameters:

[in,out] Init Pointer to the SafInit structure. Note that some fields (eg Reason and Detail) may be altered by this function.

Returns:: An integer value, zero for success and non-zero if initialization failed. See ESF Manager Initialization Return Codes and ESF Manager Initialization Internal Return Codes.

References SafEsmApi::AceeIterate, SafInit::CasLockF, SafEsmApi::CasLockMgr, SafEsmApi::CasMessage, SafInit::CasMsgF, SafEsmApi::CasService, SafInit::CasTmpF, SafEsmApi::Count, SafInit::Detail, EsmAceeIterate(), SafInit::ESMCfg, SafInit::ESMCnt, EsmFreeConfig(), EsmGetAcee(), EsmGetSafInit(), EsmGetSharedMem(), EsmLockDeq(), EsmLockEnq(), EsmLog1(), EsmParseConfig(), EsmQueryConfig(), EsmSafControl(), EsmSafQuery(), SafEsmApi::ExtractAuthStrings, SafEsmApi::ExtractVerifyStrings, SafEsmApi::ExtractXAuthStrings, SafEsmApi::FreeConfig, SafEsmApi::GetAcee, SafEsmApi::GetSafInit, SafEsmApi::GetSharedMem, SafPTab::Info, SafPTab::Init, SafEsmApi::LockDeq, SafEsmApi::LockEnq, SafEsmApi::Log, SafEsmApi::ParseConfig, SafEsmApi::QueryConfig, SafInit::Reason, SafEsmApi::SafControl, SafESM_API_VER_MAJ, SafESM_API_VER_MIN, SafESM_IF_VER, SafESM_PT_VER, SafExtractAuthStrings(), SafExtractVerifyStrings(), SafExtractXAuthStrings(), SafINIT_ESMCFG, SafINIT_FAIL, SafINIT_INTERNAL, SafINIT_MODLOAD, SafINIT_MODNAME, SafINIT_NULL, SafINIT_OK, SafLog(), SafMGR_FAIL_ESM, SafMGR_FAIL_ESMCFG, SafMGR_FAIL_ESMENTRY, SafMGR_FAIL_GENERAL, SafMGR_FAIL_LOAD, SafMsgCRIT, SafMsgINFO, SafMsgWARN, SafEsmApi::SafQuery, SafQueryCfg(), SafR_OK, and SafPTab::Version.

Referenced by safmgr().

mf_uns32 SafEsmExit ( void )

Inform ESM Modules of Process Exit.

Invoke the Exit procedure for all loaded ESM Modules that implement this procedure. This notifies the modules that the process is exiting.

Currently there are no parameters.

Returns:: An integer value, zero for success, non-zero for error. Currently no specific error codes are defined.

References SafPTab::Exit, SafLog(), and SafMsgWARN.

Referenced by safterm().

mf_uns32 SafEsmUnload ( void )

Unload ESM Modules.

Unload any ESM Modules that were dynamically loaded. This is used when ESF is being shut down for possible restarting in the same process, and helps ensure that the modules will be reinitialized correctly.

Currently there are no parameters.

Returns:: An integer value, zero for success, non-zero for error. Currently no specific error codes are defined.

References SafModUnload().

Referenced by safterm().

const char* SafEsmName ( mf_uns32 Index )

Provide the Name of an ESM Module (For Logging).

Return the name of an ESM module, indicated by zero-based index into the module array passed at initialization.

Parameters:

[in] Index The index of the ESM module.

Returns:: A constant string containing the module name, or a default if the name is unavailable.

References SafInit::ESMCfg.

Referenced by SafAdmin(), SafAuth(), SafUpdate(), SafVerify(), and SafXauth().

mf_uns32 SafEsmCVerify	(	mf_uns32	EsmIdx,
		struct safpb_parameter_block *	PBlock
	)

Call an ESM Module's Verify Procedure.

Invoke the Verify procedure for the specified ESM Module, if it provides one. If the module does not implement Verify, return the "Unimplemented" return code SafESMRC_NOTIMPL (see Return Codes).

Parameters:

`[in,out]`	PBlock	The ESF API parameter block for the request
`[in]`	EsmIdx	The index of the ESM Module to call

Returns:: An integer, zero for success, nonzero for error; see ESM Module Procedure Return Codes

References SafESMRC_NOTIMPL, SafESMRC_PARAM, and SafPTab::Verify.

Referenced by SafVerify().

mf_uns32 SafEsmCAuth	(	mf_uns32	EsmIdx,
		struct safpb_parameter_block *	PBlock
	)

Call an ESM Module's Auth Procedure.

Invoke the Auth procedure for the specified ESM Module, if it provides one. If the module does not implement Auth, return the "Unimplemented" return code SafESMRC_NOTIMPL (see Return Codes).

Parameters:

`[in,out]`	PBlock	The ESF API parameter block for the request
`[in]`	EsmIdx	The index of the ESM Module to call

Returns:: An integer, zero for success, nonzero for error; see ESM Module Procedure Return Codes

References SafPTab::Auth, SafESMRC_NOTIMPL, and SafESMRC_PARAM.

Referenced by SafAuth().

mf_uns32 SafEsmCXAuth	(	mf_uns32	EsmIdx,
		struct safpb_parameter_block *	PBlock
	)

Call an ESM Module's XAuth Procedure.

Invoke the XAuth procedure for the specified ESM Module, if it provides one. If the module does not implement XAuth, return the "Unimplemented" return code SafESMRC_NOTIMPL (see Return Codes).

Parameters:

`[in,out]`	PBlock	The ESF API parameter block for the request
`[in]`	EsmIdx	The index of the ESM Module to call

Returns:: An integer, zero for success, nonzero for error; see ESM Module Procedure Return Codes

References SafESMRC_NOTIMPL, SafESMRC_PARAM, and SafPTab::XAuth.

Referenced by SafXauth().

mf_uns32 SafEsmCAdmin	(	mf_uns32	EsmIdx,
		struct safpb_parameter_block *	PBlock
	)

Call an ESM Module's Admin Procedure.

Invoke the Admin procedure for the specified ESM Module, if it provides one. If the module does not implement Admin, return the "Unimplemented" return code SafESMRC_NOTIMPL (see Return Codes).

Parameters:

`[in,out]`	PBlock	The ESF API parameter block for the request
`[in]`	EsmIdx	The index of the ESM Module to call

Returns:: An integer, zero for success, nonzero for error; see ESM Module Procedure Return Codes

References SafPTab::Admin, SafESMRC_NOTIMPL, and SafESMRC_PARAM.

Referenced by SafAdmin().

mf_uns32 SafEsmCControl	(	mf_s32	Type,
		mf_uns32	EsmIdx,
		void *	Data
	)

Call an ESM Module's Control Procedure.

Invoke the Control procedure for the specified ESM Module, if it provides one. If the module does not implement Control, return the "Unimplemented" return code SafESMRC_NOTIMPL (see Return Codes).

Parameters:

`[in]`	Type	The type of control call; see ESF ESM Control Request Types
`[in]`	EsmIdx	The index of the ESM Module to call
`[in,out]`	Data	The data area for this request type

Returns:: An integer, zero for success, nonzero for error; see ESM Module Procedure Return Codes

References SafPTab::Control, SafESMRC_NOTIMPL, and SafESMRC_PARAM.

Referenced by safcfgesm().

mf_uns32 SafEsmCUpdate	(	mf_s32	Type,
		mf_uns32	EsmIdx,
		struct safpb_parameter_block *	PBlock
	)

Call an ESM Module's Update Procedure.

Invoke the Update procedure for the specified ESM Module, if it provides one. If the module does not implement update, return the "Unimplemented" return code SafESMRC_NOTIMPL (see Return Codes).

Parameters:

`[in]`	Type	The type of update call; see ESF ESM Update Request Types
`[in]`	EsmIdx	The index of the ESM Module to call
`[in,out]`	PBlock	The ESF API parameter block for the request

Returns:: An integer, zero for success, nonzero for error; see ESM Module Procedure Return Codes

References SafESMRC_NOTIMPL, SafESMRC_PARAM, and SafPTab::Update.

Referenced by SafUpdate().

mf_uns32 SafExtractVerifyStrings	(	struct safpb_parameter_block *	Request,
		char *	UserBuf,
		mf_uns32	UserMax,
		char *	PassBuf,
		mf_uns32	PassMax,
		char *	NPassBuf,
		mf_uns32	NPassMax,
		char *	GroupBuf,
		mf_uns32	GroupMax,
		void *	Reserved
	)

Extract the variable-length string data from a Verify request.

The ESF API Parameter Block contains or references a number of pieces of variable-length string data. This function extracts that data as C-style nul-terminated strings, into buffers provided by the caller.

Note that the caller can determine the required buffer size for each character field from its associated length field in the parameter block, except for the Group field, which is never more than nine bytes including the nul terminator.

If any of the size parameters are zero, the function will skip the relevant area in the parameter block; in this case the assocated buffer can be null. If any of the buffers are too small to hold the assocaited string, the function will copy as many bytes as will fit, less one for the terminating nul, which is always added. If any string is truncated in this fashion, the return code will reflect that (see below).

Parameters:

`[in]`	Request	ESF API parameter block
`[out]`	UserBuf	Buffer to receive the UserID string
`[in]`	UserMax	Maximum number of bytes (including nul) to write to UserBuf
`[out]`	PassBuf	Buffer to receive the Password
`[in]`	PassMax	Maximum number of bytes to write to PassBuf
`[out]`	NPassBuf	Buffer to receive the (optional) New Password
`[in]`	NPassMax	Maximum number of bytes to write to NPassBuf
`[out]`	GroupBuf	Buffer to receive the (optional) Group
`[in]`	GroupMax	Maximum number of bytes to write to GroupBuf
	Reserved	Reserved for future use; must be null

Returns:

An integer value, zero for success, non-zero for error. Error codes currently defined:

1: One or more strings was truncated
2: Invalid request (eg this request is not a Verify)
3: Parameter error (null Request, or null buffer with nonzero length)

Other error codes may also be returned.

References safpb_parameter_block::REQUESTS, saf78_REQUEST_VERIFY, saf78_VERSION_1, safpb_parameter_block::safpb_request, safpb_verify::safpb_verify_group, safpb_verify::safpb_verify_NEWPWRD_len, safpb_verify::safpb_verify_NEWPWRD_ptr, safpb_verify::safpb_verify_PWRD_len, safpb_verify::safpb_verify_PWRD_ptr, safpb_verify::safpb_verify_USERID_len, safpb_verify::safpb_verify_USERID_ptr, safpb_parameter_block::safpb_version, and safpb_parameter_block::VERIFY.

Referenced by SafEsmInit().

mf_uns32 SafExtractAuthStrings	(	struct safpb_parameter_block *	Request,
		char *	ClassBuf,
		mf_uns32	ClassMax,
		char *	EntityBuf,
		mf_uns32	EntityMax,
		char *	FacilityBuf,
		mf_uns32	FacilityMax,
		char *	TransBuf,
		mf_uns32	TransMax,
		void *	Reserved
	)

Extract the variable-length string data from an Auth request.

The ESF API Parameter Block contains or references a number of pieces of variable-length string data. This function extracts that data as C-style nul-terminated strings, into buffers provided by the caller.

Note that the caller can determine the required buffer size for each character field from its associated length field in the parameter block, except for the Group field, which is never more than nine bytes including the nul terminator.

If any of the size parameters are zero, the function will skip the relevant area in the parameter block; in this case the assocated buffer can be null. If any of the buffers are too small to hold the assocaited string, the function will copy as many bytes as will fit, less one for the terminating nul, which is always added. If any string is truncated in this fashion, the return code will reflect that (see below).

Parameters:

`[in]`	Request	ESF API parameter block
`[out]`	ClassBuf	Buffer to receive the Class string
`[in]`	ClassMax	Maximum number of bytes (including nul) to write to ClassBuf
`[out]`	EntityBuf	Buffer to receive the Entity
`[in]`	EntityMax	Maximum number of bytes to write to EntityBuf
`[out]`	FacilityBuf	Buffer to receive the (optional) Facility (terminal ID)
`[in]`	FacilityMax	Maximum number of bytes to write to FacilityBuf
`[out]`	TransBuf	Buffer to receive the (optional) Transaction
`[in]`	TransMax	Maximum number of bytes to write to TransBuf
	Reserved	Reserved for future use; must be null

Returns:

An integer value, zero for success, non-zero for error. Error codes currently defined:

1: One or more strings was truncated
2: Invalid request (eg this request is not an Auth)
3: Parameter error (null Request, or null buffer with nonzero length)

Other error codes may also be returned.

References safpb_parameter_block::AUTH, safpb_parameter_block::REQUESTS, saf78_REQUEST_AUTH, saf78_VERSION_1, safpb_auth::safpb_auth_class, safpb_auth::safpb_auth_ENTITY_len, safpb_auth::safpb_auth_ENTITY_ptr, safpb_auth::safpb_auth_FACILITY_len, safpb_auth::safpb_auth_FACILITY_ptr, safpb_auth::safpb_auth_TRANSACTION_len, safpb_auth::safpb_auth_TRANSACTION_ptr, safpb_parameter_block::safpb_request, and safpb_parameter_block::safpb_version.

Referenced by SafEsmInit().

mf_uns32 SafExtractXAuthStrings	(	struct safpb_parameter_block *	Request,
		char *	ClassBuf,
		mf_uns32	ClassMax,
		char *	EntityBuf,
		mf_uns32	EntityMax,
		char *	String1Buf,
		mf_uns32	String1Max,
		char *	String2Buf,
		mf_uns32	String2Max,
		void *	Reserved
	)

Extract the variable-length string data from an XAuth request.

The ESF API Parameter Block contains or references a number of pieces of variable-length string data. This function extracts that data as C-style nul-terminated strings, into buffers provided by the caller.

Note that the caller can determine the required buffer size for each character field from its associated length field in the parameter block, except for the Group field, which is never more than nine bytes including the nul terminator.

If any of the size parameters are zero, the function will skip the relevant area in the parameter block; in this case the assocated buffer can be null. If any of the buffers are too small to hold the assocaited string, the function will copy as many bytes as will fit, less one for the terminating nul, which is always added. If any string is truncated in this fashion, the return code will reflect that (see below).

Parameters:

`[in]`	Request	ESF API parameter block
`[out]`	ClassBuf	Buffer to receive the Class string
`[in]`	ClassMax	Maximum number of bytes (including nul) to write to ClassBuf
`[out]`	EntityBuf	Buffer to receive the Entity
`[in]`	EntityMax	Maximum number of bytes to write to EntityBuf
`[out]`	String1Buf	Buffer to receive the (optional) String1
`[in]`	String1Max	Maximum number of bytes to write to String1Buf
`[out]`	String2Buf	Buffer to receive the (optional) String2
`[in]`	String2Max	Maximum number of bytes to write to String2Buf
	Reserved	Reserved for future use; must be null

Returns:

An integer value, zero for success, non-zero for error. Error codes currently defined:

1: One or more strings was truncated
2: Invalid request (eg this request is not an XAuth)
3: Parameter error (null Request, or null buffer with nonzero length)

Other error codes may also be returned.

References safpb_parameter_block::REQUESTS, saf78_REQUEST_XAUTH, saf78_VERSION_1, safpb_parameter_block::safpb_request, safpb_parameter_block::safpb_version, safpb_xauth::safpb_xauth_CLASS_len, safpb_xauth::safpb_xauth_CLASS_ptr, safpb_xauth::safpb_xauth_ENTITY_len, safpb_xauth::safpb_xauth_ENTITY_ptr, safpb_xauth::safpb_xauth_STRING1_len, safpb_xauth::safpb_xauth_STRING1_ptr, safpb_xauth::safpb_xauth_STRING2_len, safpb_xauth::safpb_xauth_STRING2_ptr, and safpb_parameter_block::XAUTH.

Referenced by SafEsmInit().

saf-esm.h File Reference

Data Structures

Defines

Functions

Detailed Description

Function Documentation