Provider entry point

The single exported function that a FOBJ provider DLL/SO must implement. More...

Typedefs
typedef void	TfFobjExit(void *pvGbl, void **ppHdl, int *piRetco, const unsigned int *piVersion, const unsigned int *piFunc, TuFobjPar *puPara, const unsigned int *piMsgSiz, char *pcMsg)
	FOBJ provider entry point function type.

Detailed Description

The single exported function that a FOBJ provider DLL/SO must implement.

Typedef Documentation

TfFobjExit

typedef void TfFobjExit(void *pvGbl, void **ppHdl, int *piRetco, const unsigned int *piVersion, const unsigned int *piFunc, TuFobjPar *puPara, const unsigned int *piMsgSiz, char *pcMsg)

FOBJ provider entry point function type.

This is the only symbol that a FOBJ provider library must export. The default exported name is FOBJ_DEFFUC_NAME ("FOBJUSR").

Parameter table

Parameter	Direction	Type	Description
pvGbl	in	POINTER	FLAM global handle (struct Fl5Gbl*);
			NULL-safe. External providers may
			ignore it. FLAM-internal providers
			may cast it to struct Fl5Gbl* to use
			FLAM logging and I/O services.
ppHdl	in/out	POINTER	Provider handle. NULL on first OPN;
			set by provider at OPN, freed at CLS.
piRetco	out	INTEGER	Return code (0 = success).
piVersion	in	INTEGER	Interface version (FOBJ_VERSION).
			Together with *piFunc, determines
			the active TuFobjPar union member.
			Providers should return an error from
			OPN if the major version differs.
piFunc	in	INTEGER	Function code (FOBJ_FUNC_*).
puPara	in/out	POINTER	Parameter union; member by *piFunc.
piMsgSiz	in	INTEGER	Capacity of pcMsg buffer in bytes.
pcMsg	out	POINTER	Error/info message (null-terminated).

Note

On a successful OPN with an informational message, the provider may write a non-empty string to pcMsg; FLAM will log it as an informational message. On error, set *piRetco != 0 and write a diagnostic string to pcMsg.

Lifecycle: *ppHdl is NULL on FOBJ_FUNC_NEW; the provider allocates a handle and writes its address to *ppHdl. All subsequent calls pass the same handle until FOBJ_FUNC_FRE, at which point the provider must free the handle and set *ppHdl to NULL. FOBJ_FUNC_CLS closes the storage connection but does not free the handle.

Minimal skeleton

void FOBJUSR(
      void*               pvGbl,
      void**              ppHdl,
      int*                piRetco,
      const unsigned int* piVersion,
      const unsigned int* piFunc,
      TuFobjPar*          puPara,
      const unsigned int* piMsgSiz,
      char*               pcMsg)
{
   (void)pvGbl;
   if (FOBJ_VER_MAJOR(*piVersion) != FOBJ_VER_MAJOR(FOBJ_VERSION)) {
      snprintf(pcMsg, *piMsgSiz, "FOBJ version mismatch: %u", *piVersion);
      *piRetco = 1;
      return;
   }
   *piRetco = 0;
   switch (*piFunc) {
   case FOBJ_FUNC_OPN: ... break;
   case FOBJ_FUNC_CLS: ... break;
   case FOBJ_FUNC_PUT: ... break;
   case FOBJ_FUNC_GET: ... break;
   default:
      snprintf(pcMsg, *piMsgSiz,
               "Unknown function code %u", *piFunc);
      *piRetco = 1;
   }
}