protocol definitions for ZFFramework More...

#include "ZFObject.h"

Classes
class	v_ZFProtocolLevel
	level type for ZFProtocol, see ZFPROTOCOL_IMPLEMENTATION_BEGIN More...

class	v_ZFProtocolInstanceState
	instance state of ZFProtocol More...

class	ZFProtocol
	base class of all protocol of ZFFramework More...

class	v_ZFProtocol
	type wrapper for ZFTypeId::Value More...

class	ZFProtocolImplInfo
	see ZFProtocolImplInfoGetAll More...

class	v_ZFProtocolImplInfo
	type wrapper for ZFTypeId::Value More...

Macros
#define	ZFPROTOCOL_INTERFACE_CLASS(ModuleName)
	access the class name of ZFProtocol for ModuleName

#define	ZFPROTOCOL_INTERFACE_BEGIN(ZFLIB_, ModuleName)
	declare a protocol interface for ZFFramework

#define	ZFPROTOCOL_INTERFACE_END(ModuleName)
	for more information, please refer to ZFPROTOCOL_INTERFACE_BEGIN

#define	ZFPROTOCOL_INTERFACE_OPTIONAL
	macro to show that the protocol is optional

#define	ZFPROTOCOL_INTERFACE_REGISTER(ModuleName)
	statically register the protocol interface, must be placed in source file

#define	ZFPROTOCOL_TRY_ACCESS(ModuleName)
	access the protocol implementation

#define	ZFPROTOCOL_ACCESS(ModuleName)
	similar to ZFPROTOCOL_TRY_ACCESS, but assert fail if no implementation

#define	ZFPROTOCOL_IS_AVAILABLE(ModuleName)
	test whether the protocol is available

#define	ZFPROTOCOL_IMPLEMENTATION_PLATFORM_HINT(PlatformHint)
	register platform hint for an implementation, put it between ZFPROTOCOL_IMPLEMENTATION_BEGIN and ZFPROTOCOL_IMPLEMENTATION_END

#define	ZFPROTOCOL_IMPLEMENTATION_PLATFORM_DEPENDENCY_BEGIN()
	declare a dependency

#define	ZFPROTOCOL_IMPLEMENTATION_PLATFORM_DEPENDENCY_ITEM(Protocol, DependencyPlatformHint)
	see ZFPROTOCOL_IMPLEMENTATION_PLATFORM_DEPENDENCY_BEGIN

#define	ZFPROTOCOL_IMPLEMENTATION_PLATFORM_DEPENDENCY_END()
	see ZFPROTOCOL_IMPLEMENTATION_PLATFORM_DEPENDENCY_BEGIN

#define	ZFPROTOCOL_IMPLEMENTATION_CLASS(Implementation)
	the actual class name used by ZFPROTOCOL_IMPLEMENTATION_BEGIN

#define	ZFPROTOCOL_IMPLEMENTATION_BEGIN(ImplementationName, ModuleName, implLevel)
	declare a implementation for specified protocol interface named ModuleName

#define	ZFPROTOCOL_IMPLEMENTATION_END(ImplementationName)
	for more information, please refer to ZFPROTOCOL_IMPLEMENTATION_BEGIN

#define	ZFPROTOCOL_IMPLEMENTATION_CHECK(CheckAction)
	for more information, please refer to ZFPROTOCOL_IMPLEMENTATION_BEGIN

#define	ZFProtocolImplChange(ImplementationName)
	change the implementation at runtime

#define	ZFProtocolImplRemove(ModuleName)
	remove implementation, see ZFProtocolImplChange

Typedefs
typedef v_ZFProtocolLevel::ZFEnumType	ZFProtocolLevel
	see v_ZFProtocolLevel

typedef v_ZFProtocolInstanceState::ZFEnumType	ZFProtocolInstanceState
	see v_ZFProtocolInstanceState

Functions
zfbool	ZFProtocolLevelFromStringT (zfauto &ret, const zfchar src, zfindex srcLen=((zfindex) -1), zfstring errorHint=zft_zfnull)
	see v_ZFProtocolLevel, return enum object if success

zfbool	ZFProtocolLevelToStringT (zfstring &ret, v_ZFProtocolLevel const &value, zfstring errorHint=zft_zfnull)
	see ZFProtocolLevel, return empty string if error

zfstring	ZFProtocolLevelToString (v_ZFProtocolLevel const &value, zfstring errorHint=zft_zfnull)
	see v_ZFProtocolLevel, return empty string if error

const zfstring &	ZFTypeId_ZFProtocolLevel (void)

zfbool	ZFProtocolLevelFromDataT (_ZFP_PropTypeW_ZFProtocolLevel &v, const ZFSerializableData &serializableData, zfstring outErrorHint=zft_zfnull, ZFSerializableData outErrorPos=zft_zfnull)
	see ZFTYPEID_DECLARE

_ZFP_PropTypeW_ZFProtocolLevel	ZFProtocolLevelFromData (const ZFSerializableData &serializableData, zfstring outErrorHint=zft_zfnull, ZFSerializableData outErrorPos=zft_zfnull)
	see ZFTYPEID_DECLARE

zfbool	ZFProtocolLevelToDataT (ZFSerializableData &serializableData, _ZFP_PropTypeW_ZFProtocolLevel const &v, zfstring *outErrorHint=zft_zfnull)
	see ZFTYPEID_DECLARE

ZFSerializableData	ZFProtocolLevelToData (_ZFP_PropTypeW_ZFProtocolLevel const &v, zfstring *outErrorHint=zft_zfnull)
	see ZFTYPEID_DECLARE

zfbool	ZFProtocolLevelFromStringT (_ZFP_PropTypeW_ZFProtocolLevel &v, const zfchar src, zfindex srcLen=((zfindex) -1), zfstring errorHint=zft_zfnull)
	util method to convert ZFProtocolLevel from string

_ZFP_PropTypeW_ZFProtocolLevel	ZFProtocolLevelFromString (const zfchar src, zfindex srcLen=((zfindex) -1), zfstring errorHint=zft_zfnull)
	util method to convert ZFProtocolLevel from string

zfbool	ZFProtocolLevelToStringT (zfstring &s, _ZFP_PropTypeW_ZFProtocolLevel const &v, zfstring *errorHint=zft_zfnull)
	util method to convert ZFProtocolLevel to string

zfstring	ZFProtocolLevelToString (_ZFP_PropTypeW_ZFProtocolLevel const &v, zfstring *errorHint=zft_zfnull)
	util method to convert ZFProtocolLevel to string

zfbool	ZFProtocolInstanceStateFromStringT (zfauto &ret, const zfchar src, zfindex srcLen=((zfindex) -1), zfstring errorHint=zft_zfnull)
	see v_ZFProtocolInstanceState, return enum object if success

zfbool	ZFProtocolInstanceStateToStringT (zfstring &ret, v_ZFProtocolInstanceState const &value, zfstring errorHint=zft_zfnull)
	see ZFProtocolInstanceState, return empty string if error

zfstring	ZFProtocolInstanceStateToString (v_ZFProtocolInstanceState const &value, zfstring errorHint=zft_zfnull)
	see v_ZFProtocolInstanceState, return empty string if error

const zfstring &	ZFTypeId_ZFProtocolInstanceState (void)

zfbool	ZFProtocolInstanceStateFromDataT (_ZFP_PropTypeW_ZFProtocolInstanceState &v, const ZFSerializableData &serializableData, zfstring outErrorHint=zft_zfnull, ZFSerializableData outErrorPos=zft_zfnull)
	see ZFTYPEID_DECLARE

_ZFP_PropTypeW_ZFProtocolInstanceState	ZFProtocolInstanceStateFromData (const ZFSerializableData &serializableData, zfstring outErrorHint=zft_zfnull, ZFSerializableData outErrorPos=zft_zfnull)
	see ZFTYPEID_DECLARE

zfbool	ZFProtocolInstanceStateToDataT (ZFSerializableData &serializableData, _ZFP_PropTypeW_ZFProtocolInstanceState const &v, zfstring *outErrorHint=zft_zfnull)
	see ZFTYPEID_DECLARE

ZFSerializableData	ZFProtocolInstanceStateToData (_ZFP_PropTypeW_ZFProtocolInstanceState const &v, zfstring *outErrorHint=zft_zfnull)
	see ZFTYPEID_DECLARE

zfbool	ZFProtocolInstanceStateFromStringT (_ZFP_PropTypeW_ZFProtocolInstanceState &v, const zfchar src, zfindex srcLen=((zfindex) -1), zfstring errorHint=zft_zfnull)
	util method to convert ZFProtocolInstanceState from string

_ZFP_PropTypeW_ZFProtocolInstanceState	ZFProtocolInstanceStateFromString (const zfchar src, zfindex srcLen=((zfindex) -1), zfstring errorHint=zft_zfnull)
	util method to convert ZFProtocolInstanceState from string

zfbool	ZFProtocolInstanceStateToStringT (zfstring &s, _ZFP_PropTypeW_ZFProtocolInstanceState const &v, zfstring *errorHint=zft_zfnull)
	util method to convert ZFProtocolInstanceState to string

zfstring	ZFProtocolInstanceStateToString (_ZFP_PropTypeW_ZFProtocolInstanceState const &v, zfstring *errorHint=zft_zfnull)
	util method to convert ZFProtocolInstanceState to string

const zfstring &	ZFTypeId_ZFProtocol (void)

ZFProtocol *	ZFProtocolForName (const zfchar name, const zfchar desiredImpl=(zft_zfnull))
	get protocol with name or null if no such protocol

zfbool	ZFProtocolIsAvailable (const zfchar name, const zfchar desiredImpl=(zft_zfnull))
	check whether protocol is available

const zfstring &	ZFTypeId_ZFProtocolImplInfo (void)

ZFCoreArray< ZFProtocolImplInfo >	ZFProtocolImplInfoGetAll ()
	for debug use only, get all protocol's info

ZFCoreArray< ZFProtocolImplInfo >	ZFProtocolImplInfoGetAllImplemented ()
	util method to ZFProtocolImplInfoGetAll

ZFCoreArray< ZFProtocolImplInfo >	ZFProtocolImplInfoGetAllNotImplemented ()
	util method to ZFProtocolImplInfoGetAll

void	ZFProtocolImplInfoPrint (const ZFOutput &callback=(ZFOutputDefault()))
	util method to ZFProtocolImplInfoGetAll

void	ZFProtocolImplInfoPrint (const ZFProtocolImplInfo &data, const ZFOutput &callback=(ZFOutputDefault()))
	util method to ZFProtocolImplInfoGetAll

Detailed Description

protocol definitions for ZFFramework

Macro Definition Documentation

◆ ZFPROTOCOL_INTERFACE_CLASS

#define ZFPROTOCOL_INTERFACE_CLASS ( ModuleName )

access the class name of ZFProtocol for ModuleName

usually no use, unless the protocol module needs a constructor

◆ ZFPROTOCOL_INTERFACE_BEGIN

#define ZFPROTOCOL_INTERFACE_BEGIN	(		ZFLIB_,
			ModuleName )

declare a protocol interface for ZFFramework

a protocol interface is a part that must be implemented, usually it's under Module/protocol such as ZFCore/protocol, meaning you should implement all protocols under ZFCore/protocol if you want to use ZFCore module
this macro is used internally to declare a protocol
typical usage:

// in a *.h file
ZFPROTOCOL_INTERFACE_BEGIN(ZFLIB_APP, SomeModule)
    public: // you can add constructors, but with no arguments only
        ZFPROTOCOL_INTERFACE_CLASS(SomeModule)(void) {...}
        virtual ~ZFPROTOCOL_INTERFACE_CLASS(SomeModule)(void) {...}
    public: // declare protocols here
        virtual void moduleFunc(void) zfpurevirtual;
    private:
        SomeType member; // you can add member here
ZFPROTOCOL_INTERFACE_END(SomeModule)

for the difference between them, see ZFPROTOCOL_TRY_ACCESS
for how to implement it, see ZFPROTOCOL_IMPLEMENTATION_BEGIN
for how to access the implementation, see ZFPROTOCOL_TRY_ACCESS

Note: all protocol is singleton mode

◆ ZFPROTOCOL_TRY_ACCESS

#define ZFPROTOCOL_TRY_ACCESS ( ModuleName )

access the protocol implementation

return protocol implementation or null if not implemented
typical usage:

ZFPROTOCOL_INTERFACE_CLASS(SomeModule) *impl = zfnull;
// access the implementation of the protocol
impl = ZFPROTOCOL_TRY_ACCESS(SomeModule);
if(impl == zfnull) {
    // error, have no implementation
    exit(); // then you can handle it here, exit or ignore, whatever you like
}
...
// use it
impl->someFunc();

all protocol is singleton protocol, ZFPROTOCOL_TRY_ACCESS would create new instance only for the first time, and the instance would be destroyed at a certain proper time

when using ZFPROTOCOL_TRY_ACCESS, you take full responsibility to check whether the implmentation is available

◆ ZFPROTOCOL_IMPLEMENTATION_PLATFORM_HINT

#define ZFPROTOCOL_IMPLEMENTATION_PLATFORM_HINT ( PlatformHint )

register platform hint for an implementation, put it between ZFPROTOCOL_IMPLEMENTATION_BEGIN and ZFPROTOCOL_IMPLEMENTATION_END

while implementing protocol, you may use ZFPROTOCOL_IMPLEMENTATION_PLATFORM_DEPENDENCY_XXX to explicitly show it require other implementation
the PlatformHint can be any string, but you should make sure it's unique from others, and it's recommended to follow these rules (not necessary):

for common case, use
"framework or system or environment name" + ":" + "hint"
such as "iOS:NSString"
if you need some native wrapper to hold native types, it's recommended to supply in this format:
"framework or system or environment name" + ":" + "wrapper name" + ":" + "hint"
such as "iOS:NSObject:NSString"
and in your wrapper object, supply a native method named "zfnativeImpl" to return the wrapped type, so that native code can use native code to reflect and access the internal types

if you are able to access an implementation, you may check its platform hint by ZFProtocol::protocolImplPlatformHint

◆ ZFPROTOCOL_IMPLEMENTATION_PLATFORM_DEPENDENCY_BEGIN

#define ZFPROTOCOL_IMPLEMENTATION_PLATFORM_DEPENDENCY_BEGIN ( )

declare a dependency

ZFPROTOCOL_IMPLEMENTATION_BEGIN(...)
    ZFPROTOCOL_IMPLEMENTATION_PLATFORM_DEPENDENCY_BEGIN()
        ZFPROTOCOL_IMPLEMENTATION_PLATFORM_DEPENDENCY_ITEM(ProtocolName, "DependencyPlatformHint")
    ZFPROTOCOL_IMPLEMENTATION_PLATFORM_DEPENDENCY_END()
ZFPROTOCOL_IMPLEMENTATION_END(...)

the DependencyPlatformHint is the string declared by ZFPROTOCOL_IMPLEMENTATION_PLATFORM_HINT

◆ ZFPROTOCOL_IMPLEMENTATION_CLASS

#define ZFPROTOCOL_IMPLEMENTATION_CLASS ( Implementation )

the actual class name used by ZFPROTOCOL_IMPLEMENTATION_BEGIN

usually used to declare a constructor for protocol's implementation

◆ ZFPROTOCOL_IMPLEMENTATION_BEGIN

#define ZFPROTOCOL_IMPLEMENTATION_BEGIN	(	ImplementationName,
		ModuleName,
		implLevel )

declare a implementation for specified protocol interface named ModuleName

for what ZFProtocol is, please refer to ZFPROTOCOL_INTERFACE_BEGIN
typical usage:

// in a *.cpp file
ZFPROTOCOL_IMPLEMENTATION_BEGIN(YourImplementation, ModuleName, implLevel)
    public: // you can add your own init steps
        zfoverride
        virtual void protocolOnInit(void) {...}
        zfoverride
        virtual void protocolOnInitFinish(void) {...}
        zfoverride
        virtual void protocolOnDeallocPrepare(void) {...}
        zfoverride
        virtual void protocolOnDealloc(void) {...}
    private: // also, add other member if you like
        SomeType member;
    public: // (necessary) implement all protocols here
        virtual void implementedFunc(void) {
            ...
        }
ZFPROTOCOL_IMPLEMENTATION_END(YourImplementation)

you must have exactly one implementation for each protocol interface if you want to use the specific module
to achieve this, you may want to use the #ifdef

// in ModuleWindows.cpp
#ifdef _FLAG_WINDOWS
    ZFPROTOCOL_IMPLEMENTATION_BEGIN(YourImplementation, ...)
    ...
    ZFPROTOCOL_IMPLEMENTATION_END(YourImplementation)
#endif
 
// in ModuleLinux.cpp
#ifdef _FLAG_LINUX
    ZFPROTOCOL_IMPLEMENTATION_BEGIN(YourImplementation, ...)
    ...
    ZFPROTOCOL_IMPLEMENTATION_END(YourImplementation)
#endif

the implementation's registration is automatically done by the BEGIN and END macro, what you should do, is to put it in a cpp file and make it active

the third param "implLevel", which has:

is used to specify the implementation level, ordered from low to high priority
for example, if you have a Default and a System level's implementation, the Default one would be overrided and the System one would be used.
however, if you have two same level's implementations, you would get duplicated implementation errors

for how to declare a protocol, see ZFPROTOCOL_INTERFACE_BEGIN

advanced:
you may change implementation at runtime, see ZFProtocolImplChange

you may define implementation which depends on other implementation:

ZFPROTOCOL_IMPLEMENTATION_BEGIN(YourImplementation, ModuleName, implLevel)
    ZFPROTOCOL_IMPLEMENTATION_CHECK({
        return ZFPROTOCOL_IS_AVAILABLE(OtherProtocol);
    })
    ...
ZFPROTOCOL_IMPLEMENTATION_END(YourImplementation)

◆ ZFProtocolImplChange

#define ZFProtocolImplChange ( ImplementationName )

change the implementation at runtime

old implementation's level is ignored and forced to be replaced
it's your responsibility to make sure old implementation isn't in use, otherwise, app may crash

Function Documentation

◆ ZFTypeId_ZFProtocolLevel()

const zfstring & ZFTypeId_ZFProtocolLevel ( void )

inline

◆ ZFTypeId_ZFProtocolInstanceState()

const zfstring & ZFTypeId_ZFProtocolInstanceState ( void )

inline

◆ ZFTypeId_ZFProtocol()

const zfstring & ZFTypeId_ZFProtocol ( void )

inline

◆ ZFProtocolForName()

ZFProtocol * ZFProtocolForName	(	const zfchar *	name,
		const zfchar *	desiredImpl = (zft_zfnull) )

extern

get protocol with name or null if no such protocol

first param is the protocol's name (e.g. "ZFXml")
second param desiredImpl can be assigned to check whether the protocol matches what you want, see ZFPROTOCOL_IMPLEMENTATION_PLATFORM_HINT

◆ ZFProtocolIsAvailable()

zfbool ZFProtocolIsAvailable	(	const zfchar *	name,
		const zfchar *	desiredImpl = (zft_zfnull) )

extern

check whether protocol is available

first param is the protocol's name (e.g. "ZFXml")
second param desiredImpl can be assigned to check whether the protocol matches what you want, see ZFPROTOCOL_IMPLEMENTATION_PLATFORM_HINT

◆ ZFTypeId_ZFProtocolImplInfo()

const zfstring & ZFTypeId_ZFProtocolImplInfo ( void )

inline

Classes

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ ZFPROTOCOL_INTERFACE_CLASS

◆ ZFPROTOCOL_INTERFACE_BEGIN

◆ ZFPROTOCOL_TRY_ACCESS

◆ ZFPROTOCOL_IMPLEMENTATION_PLATFORM_HINT

◆ ZFPROTOCOL_IMPLEMENTATION_PLATFORM_DEPENDENCY_BEGIN

◆ ZFPROTOCOL_IMPLEMENTATION_CLASS

◆ ZFPROTOCOL_IMPLEMENTATION_BEGIN

◆ ZFProtocolImplChange

Function Documentation

◆ ZFTypeId_ZFProtocolLevel()

◆ ZFTypeId_ZFProtocolInstanceState()

◆ ZFTypeId_ZFProtocol()

◆ ZFProtocolForName()

◆ ZFProtocolIsAvailable()

◆ ZFTypeId_ZFProtocolImplInfo()