Copyright: Copyright Aldea Interactive 1996-1997. All rights reserved.


AGcAPI programming interface
Introduction

This reference manual documents the AGcAPI programming interface.

You’ll find in information about :

•	the type and two enumerations,

•	eight classes,

•	three functions,

•	nine macros,

•	return values of AGcAPI functions.

What you should know before reading this manual

The AGcAPI programming interface is written in C++. To use it, you must have the Microsoft Visual C++ 4.2 programming environment with the Microsoft Foundation Classes. The next release of the Active Gateway environment will allow to use Microsoft Visual C++ 5.0.

It is necessary to know the basics of the C++ language to use AGcAPI.

We recommend that you study the examples provided with the Active Gateway development kit. We tried to make it as complete as possible. If you have any technical questions, consult the Internet page http://activegateway.aldea-interactive.com/support.html.


AGcAPI : Types and enumerations
Introduction

You will find in this part the AldeaError type and two enumerations acChannelType and acLinkMode useful to the use of the AGcAPI programming interface.


AGcAPI : Classes
Introduction

You will find in this part the eight classes that are helpful for you to use of the AGcAPI programming interface:

CAldeaArray

CAldeaBuffer

CAldeaBaseFrame

CAldeaDateTime

CAldeaException

CAldeaFrame

CAldeaObject

CAldeaProtocolClientPC

CAldeaSlot

CAldeaString

Some functions of the CAldeaProtocol and CAldeaProtocolClient abstract classes are documented because they are useful to use the CAldeaProtocolClientPC inherited class.

Hierarchy Chart

Click on a class to jump to its definition.


Hierarchy Chart

Click on a class to jump to its definition.


AGcAPI : Utility functions
Introduction

You will find in this part, three helper functions:

•	AldeaErrorToString

•	AldeaFormatReturnCode

•	AldeaThrowException


AGcAPI : Macros
Introduction

You will find in this part, nine macros helpful for using the AGcAPI programming interface:

•	CATCH_ALDEA_EXCEPTION

•	DELETE_ALDEA_EXCEPTION

•	GET_ALDEA_EXCEPTION_ERROR

•	GET_ALDEA_EXCEPTION_ERROR_MESSAGE

•	GET_ALDEA_EXCEPTION_ERROR_REASON

•	RETHROW_ALDEA_EXCEPTION

•	ALDEA_CHAR_SYMBOL

•	DEFAULT_SOCKET_PORT_STR

•	DEFAULT_SOCKET_PORT_LONG


AGcAPI : Error codes and return values
Introduction

Here are the error codes and return values of AldeaError type used by the different Active Gateway components.

aeNoError	No error.

aeGenericError	Undefined error. An unknown problem occurred.

aeGenericOpenError	Undefined error when opening a connection. An unknown problem occurred.

aeGenericCloseError	Undefined error when closing a connection. An unknown problem occurred.

aeGenericReadError	Undefined error when receiving data. An unknown problem occurred.

aeGenericWriteError	Undefined error when sending data. An unknown problem occurred..

aeChannelInvalid	The communication channel is not valid.
In TCP/IP communications, one of the machine could not support this protocol.
In serial communication, the port is busy, occupied or does not exist.

aeChannelBroken	The communication was broken. The peer had ended the communication or a problem has occurred in the network.

aeChannelBusy	Internal error. The channel is busy.

aeChannelBadState	Internal error. The communication channel is not in a correct state.

aeNoDTI	Internal server error.

aeThreadBeingKilled	Internal server error.

aeNotEnoughToRead	Internal error while receiving data.

aeOutOfMemory	Memory error.

aeUnknownRequest	Internal server error.

aeServerNeeded	Attempt to open a connection with an incorrect server name (empty string or NULL parameter).

aeWriteBufferFull	Internal error.

aeWrongUserType	Internal error.

aeWouldBlock	Internal error.

aeTimeout	The delay to realize the operation was exceeding. The operation failed.

aeConnectionAlreadyExist	A client of same name is already connected to the server.
To avoid this, try to respect the ID norm:
Ex : CLIENTX:PROGRAMX:ALDEA (client CLIENTX of the program PROGRAMX of the society ALDEA).

aeConvertToBufferError	Internal error.

aeConvertFromBufferError	Internal error.

aeFrameError	The frame is not valid. One of the slots contains a prohibited value or either a value is missing.

aeBuffError	Internal error.

aeBadServer	Server address error.
If the address is a IP address, it is not correct.
If it is a DNS name, the resolution has failed.

aeBadLoginFrame	Internal error during an attempt to connect the server.

aePeerModeIsAsync	The peer is connected in asynchronous mode while the client demands a synchronous connection.

aePeerIsLinked	The peer is already connected with another peer in synchronous mode.

aeNoDataInStack	There is no data to receive.

aeTimeoutPeer	The given time delay to connect to a peer has expired.

aeAlreadyConnected	A communication is already in use.

aeBadPeerName	The peer’s name is not correct.

aeNotConnected	There is no connection.

aeSlotTypeNotSupported	The slot type is not valid.

aePathError	The slot path is not valid or the type slot in not the wanted slot.

aeAldeaDemo	The operation failed because you used a demonstration version.

aeBadTimeout	The timeout value is not valid.

aeServerNotResponding	The server is not responding.  Verify its address and port.

aeBadLength	The array size is not valid.

aePing	Internal message.

aeDllAlreadyExist	Internal message.

aeDllNotExist	Internal message.

aeMissingFuncError	A required extension function is missing.

aeMissingSlotValueError	A required information frame slot is missing.

aeGetNeeded	Only in synchronous mode with confirmation : the client is trying to send data while its peer is trying to send data. It is necessary to do a Get.

aeSendNeeded	Only in synchronous mode with confirmation : the client is trying to receive data while the peer is trying to receive data. It is necessary to do a Send.

aePeerIsDisconnected	Internal server error.

aePeerModeIsSyncWithConf	You are trying to connect to the server in synchronous mode without confirmation while the peer is trying to connect in synchronous with confirmation.

aePeerModeIsSyncWithoutConf	You are trying to connect to  the server in synchronous mode with confirmation while the peer is trying to connect in synchronous mode without confirmation.

aeModeIsNotAsync	You are trying to use an Active Gateway functionality which needs the asynchronous mode.

aeAppNotFoundError	Internal message.

aeGenericBadRequest	Internal message.

aeUnauthorizedOperation	Prohibited operation (for example somebody is trying to unload AGMonitor from the server).

aeBadMode	The client is trying to connect with a server extension and the connection mode is not "synchronous without confirmation".

aeTypeMismatch	You are trying to compare slots of different types.

aeInvalidSlotName	The slot does not have the expected type.

aeMaxConnection	The maximum number of connections has been reached.

aeOpenFileError	Error while opening a file.

aeExtensionUnknownRequest	The request made to the extension in unknown.


Active Gateway Client Application Programming Interface

This programming interface allows you to develop Active Gateway clients and Active Gateway Server extensions.


Type AldeaError

Standard type for return values and error codes

typedef int AldeaError;

Description

This is the standard type for the return values of the most important part of the Active Gateway functions.

The value aeNoError (equal to zero) means that a function succeed. To test the correct execution of a function, you can write:

if (MyFunction() == aeNoError) ...

and for testing if there was an error:

if (MyFunction()) ...


asType enumeration

Enumeration of slot types

enum	asType	{	asString = 0,
asSymbol,
asByte,
asShort,
asBool,
asLong,
asFloat,
asDouble,
asDateTime,
asBuff,
asFrame,
asArray,
asUndefined};

Description

Enumeration of all the possible types of a CAldeaSlot object.

See also

CAldeaSlot, CAldeaSlot::ClassOf, CAldeaArray::Is<type>, CAldeaBaseFrame::Is<type>, CAldeaSlot::Is<type>


eChannelType enumeration

Enumeration of network protocols

enum	acChannelType	{	ac_ctTCPIPSocket= 0,
ac_ctPipe,
ac_ctNetBios};

Description

Enumeration of supported network protocols.

Remarks

The current version of Active Gateway supports only TCP/IP communications (ac_ctTCPIPSocket). The CAldeaProtocolClientPC::CAldeaProtocolClientPC constructor takes ac_ctTCPIPSocket as the default value.

See also

CAldeaProtocolClientPC::CAldeaProtocolClientPC


acLinkMode enumeration

Connection modes enumeration

enum	acLinkMode	{	ac_lmSyncWithoutConf= 0,
ac_lmSyncWithConf,
ac_lmAsync};

Description

This enumeration allows you to choose the connection mode that you want in the constructor or in the Open method of the CAldeaProtocolClientPC object:

•	ac_lmSyncWithoutConf : Synchronous connection (connected mode) with a unique peer and without confirmation of transmission. If the CAldeaProtocolClientPC::Send function returns aeNoError, you are sure the data was correctly transmitted to the Active Gateway server and that the peer is currently connected. You are not aware of any error occurring while the data is being transmitted to the peer.
This is the only connection mode allowed between a client and an Active Gateway server extension.

•	ac_lmSyncWithConf: Synchronous connection (connected mode) with a unique peer and with acknowledgment of transmissions. This mode is identical to the preceding one with the difference that if the CAldeaProtocolClientPC::Send returns aeNoError, you are sure that the peer has received all the data. This mode uses more bandwidth than the preceding mode.

•	ac_lmAsync: Asynchronous connection (not connected mode or « Store and Forward ») with one or several peers. In this mode, data are stored temporarily by the server. When the client connects to the server, the client can retrieve all the data that was stored in the server for it.  The enormous advantage of this mode is that the peers of a client do not need to be connected to the Active Gateway server. Data are distributed following the FIFO(first in first out) principle.

See also

CAldeaProtocolClientPC::CAldeaProtocolClientPC, CAldeaProtocolClientPC::Open


AldeaErrorToString

Converting AldeaError return values into a string

CAldeaString AldeaErrorToString(long nError);

Parameters

nError	A value of type AldeaError.

Return value

A string containing the value passed in parameter.

Description

This function allows you to convert a numerical value of type AldeaError into a string. It doesn't try to explain the error, it only provides an alphanumerical representation.

For example, if the value of the nError parameter is 0 (= aeNoError), the function returns the string "aeNoError". Only the values defined in the AldeaError.h file are correctly converted by AldeaErrorToString. Any other value of the nError parameter returns "aeUnknownError".

See also

type AldeaError


AldeaFormatReturnCode

Adding an information frame into a frame

void AldeaFormatReturnCode(	CAldeaFrame&	oAldeaFrame,
AldeaError	nError,
const CAldeaString&	sError	= NULL,
const CAldeaString&	sReason	= NULL);

Parameters

oAldeaFrame	The CAldeaFrame object in which the information frame will be added.

nError	The error number of type AldeaError.

sError	An error message string. If this parameter is at NULL, it is replaced by the string returned by AldeaErrorToString(nError).

sReason	The error reason.

Description

This function allows you to normalize the frames returned by the Active Gateway Server extensions. His purpose is to homogenize the development of extensions.


AldeaThrowException

Throwing a CAldeaException exception

void AldeaThrowException(	AldeaError	nError	= aeGenericError,
CAldeaString	sError	= NULL,
CAldeaString	sReason	= NULL);

Parameters

nError	Error number of type AldeaError.

sError	Error message (optional).

sReason	Error reason (optional).

Description

This function throws a CAldeaException exception.

Used with the exception macros CATCH_ALDEA_EXCEPTION, DELETE_ALDEA_EXCEPTION, RETHROW_ALDEA_EXCEPTION, GET_ALDEA_EXCEPTION_ERROR, GET_ALDEA_EXCEPTION_ERROR_MESSAGE, and GET_ALDEA_EXCEPTION_ERROR_REASON, it allows you to ensure total compatibility between your code and future changes in the handling of exceptions in the Active Gateway environment.

See also

CAldeaException


CATCH_ALDEA_EXCEPTION

Catching an exception thrown with ThrowAldeaException

#define CATCH_ALDEA_EXCEPTION catch (CAldeaException * pAldeaException)

Description

This macro allows to catch an exception of type  "pointer to a CAldeaException object" thrown with the AldeaThrowException function.

See also

AldeaThrowException


DELETE_ALDEA_EXCEPTION

Destruction of an exception

#define DELETE_ALDEA_EXCEPTION pAldeaException->Delete();

Description

Delete the exception caught by CATCH_ALDEA_EXCEPTION.

It is needed to destroy an exception when it is no longer used, otherwise it implies a loss of memory allocated for the CAldeaException object.

See also

CATCH_ALDEA_EXCEPTION, RETHROW_ALDEA_EXCEPTION


GET_ALDEA_EXCEPTION_ERROR

Exception value

#define GET_ALDEA_EXCEPTION_ERROR pAldeaException->GetErrorCode()

Description

To access a macro to the error code of the exception.

See also

CATCH_ALDEA_EXCEPTION, GET_ALDEA_EXCEPTION_ERROR_MESSAGE, GET_ALDEA_EXCEPTION_ERROR_REASON


GET_ALDEA_EXCEPTION_ERROR_MESSAGE

Exception message

#define GET_ALDEA_EXCEPTION_ERROR_MESSAGE pAldeaException->GetErrorMessage()

Description

To access a macro to the error message of the exception.

See also

CATCH_ALDEA_EXCEPTION, GET_ALDEA_EXCEPTION_ERROR, GET_ALDEA_EXCEPTION_ERROR_REASON


GET_ALDEA_EXCEPTION_ERROR_REASON

Exception reason

#define GET_ALDEA_EXCEPTION_ERROR_REASON pAldeaException->GetErrorReason()

Description

To access a macro to the error reason of the exception.

See also

CATCH_ALDEA_EXCEPTION, GET_ALDEA_EXCEPTION_ERROR, GET_ALDEA_EXCEPTION_ERROR_MESSAGE


RETHROW_ALDEA_EXCEPTION

Rethrowing an exception

#define RETHROW_ALDEA_EXCEPTION throw pAldeaException;

Description

This macro allows you to rethrow an exception caught by CATCH_ALDEA_EXCEPTION. In those case, DO NOT USE DELETE_ALDEA_EXCEPTION.

See also

CATCH_ALDEA_EXCEPTION


ALDEA_CHAR_SYMBOL

The character used to define a symbol

#define ALDEA_CHAR_SYMBOL _T('\'')

Description

This macro defines the character representing a "symbol". When a string begins with this character, the CAldeaSlot member functions interpret it as a "symbol".

See also

CAldeaSlot


DEFAULT_SOCKET_PORT_STR

Default TCP/IP port (string)

#define DEFAULT_SOCKET_PORT_STR T("23789")

Description

This macro becomes a string specifying the default TCP/IP port used by the Active Gateway server.


DEFAULT_SOCKET_PORT_LONG

Default TCP/IP port (long integer)

#define DEFAULT_SOCKET_PORT_LONG 23789

Description

This macro becomes a long integer specifying the default TCP/IP port used by the Active Gateway server.


Types representation

Slot types representation

#define kStrString	_T("STR")
#define kStrSymbol	_T("SYM")
#define kStrByte	_T("BYT")
#define kStrShort	_T("SHR")
#define kStrBool	_T("BOO")
#define kStrLong	_T("LNG")
#define kStrFloat	_T("FLT")
#define kStrDouble	_T("DBL")
#define kStrDate	_T("DAT")
#define kStrBuff	_T("BUF")
#define kStrFrame	_T("FRA")
#define kStrArray	_T("ARR")
#define kStrUndefined	_T("UND")

Description

These macros allow you to identify in shot form (normalized on 3 characters) the different CAldeaSlot object types. They are used as return values of the CAldeaSlot::GetTypeStr member function.

See also

CAldeaSlot::GetTypeStr


CAldeaArray

CAldeaArray inherits from CAldeaBaseFrame.

See also

Hierarchy Chart


CAldeaArray Members

Members functions

CAldeaArray::CAldeaArray

CAldeaArray::~CAldeaArray

CAldeaArray::AddArraySlot

CAldeaArray::ArrayMunger

CAldeaArray::Clone

CAldeaArray::DeepClone

CAldeaArray::Dump

CAldeaArray::Is<type>

CAldeaArray::RemoveElements

CAldeaArray::RemoveSlot

CAldeaArray::SetLength

Members operators

CAldeaArray::operator[]


CAldeaArray::CAldeaArray

Constructor

CAldeaArray::CAldeaArray();
CAldeaArray::CAldeaArray(const CAldeaArray &oArray);

Parameters

oArray	Existing CAldeaArray object which has to be copied in this new CAldeaArray object .

Description

The two constructors initialize a new CAldeaArray object with the specified data.

Please note that, in the second case, the existing array data are not copied. The two arrays will have strictly the same data pointed by their  CAldeaBaseFrame::m_pFrameData. If you want to make a partial copy, pass in parameter the copied array with CAldeaArray::Clone, for a complete copy, pass the copied array with CAldeaArray::DeepClone.

Example

CAldeaArray oAldeaArray1;
oAldeaArray1[0L] = _T("First element");
oAldeaArray1[1L] = _T("Second element");
CAldeaArray oAldeaArray2(oAldeaArray1);
CAldeaArray oAldeaArray3(oAldeaArray1.Clone());
oAldeaArray2[1L] = _T("element 2");	//	Danger oAldeaArray1[1L] contains also
//	the string "element 2". But,
//	oAldeaArray3[1L], contains "Second element"

See also

CAldeaArray::Clone, CAldeaArray::DeepClone, CAldeaArray::~CAldeaArray


CAldeaArray::~CAldeaArray

Destructor

CAldeaArray::~CAldeaArray();

Description

The CAldeaArray destructor automatically destroys  the array data (pointed by CAldeaBaseFrame::m_pFrameData) except if another CAldeaArray object references also this data.

In the following example, when the object oAldeaArray2 is destroyed The data it contains are not destroyed. But, when the last object referencing the data is destroyed (oAldeaArray1), the data are automatically destroyed.

Example

{

CAldeaArray oAldeaArray1;
oAldeaArray1[0L] = _T("First element");
oAldeaArray1[1L] = _T("Second element");
{
CAldeaArray oAldeaArray2(oAldeaArray1);
oAldeaArray2[1L] = _T("Element2");	//	oArrayArray1[1L] contains also the
//	string "Element2".
}	//	Automatic destruction of the object oAldeaArray2.
//	Common data are not destroyed

//	oAldeaArray1 contains it always
}	//	Automatic destruction of oAldeaArray1. This time, data are destroyed.

See also

CAldeaArray::CAldeaArray


CAldeaArray::AddArraySlot

Add an element to the end of an array

long CAldeaArray::AddArraySlot(const CAldeaString&	sString);
long CAldeaArray::AddArraySlot(const unsigned char	nValue);
long CAldeaArray::AddArraySlot(const short	nValue);
long CAldeaArray::AddArraySlot(const BOOL	bValue);
long CAldeaArray::AddArraySlot(const long	nValue);
long CAldeaArray::AddArraySlot(const float	fValue);
long CAldeaArray::AddArraySlot(const double	fValue);
long CAldeaArray::AddArraySlot(const CAldeaFrame&	oFrame);
long CAldeaArray::AddArraySlot(const CAldeaSlot&	oSlot);
long CAldeaArray::AddArraySlot(const CAldeaArray&	oArray);
long CAldeaArray::AddArraySlot(const CAldeaBuffer&	oBuff);
long CAldeaArray::AddArraySlot(const CAldeaDateTime&	oSystemTime);
long CAldeaArray::AddArraySlot(const SYSTEMTIME&	oSystemTime);
long CAldeaArray::AddArraySlot(const COleDateTime&	oOleDateTime);
long CAldeaArray::AddArraySlot(const VARIANT&	oValue);

Description

This function adds a new element to the end of an array.

Example

CAldeaArray oAldeaArray;
oAldeaArray.AddArraySlot(_T("First element"));
oAldeaArray.AddArraySlot((double)12.1);
oAldeaArray.AddArraySlot((long)125);
//	oAldeaArray contains 3 elements ["First element",12.1,125]


CAldeaArray::ArrayMunger

Insert/replace an array object

AldeaError CAldeaArray::ArrayMunger(	long	nDstStart,
long	nDstCount,
CAldeaArray&	oSrcArray,
long	nSrcStart,
long	nSrcCount);

Parameters

nDstStart	Index of the element (in the current CAldeaArray object) from which starts the insertion of the chosen elements from the array source (oSrcArray).

nDstCount	Number of elements of the current CAldeaArray object to replace.

oSrcArray	array source, this provides the elements to insert.

nSrcStart	Index of the first element to insert.

nSrcCount	Number of elements to insert.

Return values

On of the two following values of type AldeaError :

aeNoError	No error occurred.

aeGenericError	An error occurred.

Description

This powerful function of CAldeaArray objects handling allows you  to combine inserted elements and replaced elements in a CAldeaArray object from another CAldeaArray object.

Example

CAldeaArray oAldeaArray1;
oAldeaArray1.AddArraySlot(_T("First element"));
oAldeaArray1.AddArraySlot((double)2.2);
oAldeaArray1.AddArraySlot((long)3);
//	oAldeaArray1 contains 3 elements ["First element",2.2,3]

CAldeaArray oAldeaArray2;
oAldeaArray2.AddArraySlot((short)11);
oAldeaArray2.AddArraySlot((long)22);
oAldeaArray2.AddArraySlot((long)33);
//	oAldeaArray2 contains 3 elements [11,22,33]

oAldeaArray1.ArrayMunger(0,0,oAldeaArray2,0,3);
// give : oAldeaArray1 contains 6 elements [11,22,33,"First element",2.2,3]

oAldeaArray1.ArrayMunger(1,2,oAldeaArray2,0,3);
// give : oAldeaArray1 contains 4 elements ["First element",11,22,33]

oAldeaArray1.ArrayMunger(0,3,oAldeaArray2,0,3);
// give : oAldeaArray1 contains 3 elements [11,22,33]

oAldeaArray1.ArrayMunger(0,1,oAldeaArray2,1,1);
// give : oAldeaArray1 contains 3 elements [22,2.2,3]


CAldeaArray::Clone

Duplication of an array

CAldeaArray CAldeaArray::Clone();

Return value

A CAldeaArray object is a superficial copy of the current object.

Description

This function performs a superficial copy of an array. The CAldeaArray object enumerates all the slots then it copies each of them in the returned CAldeaArray object. In other words if one of the slots contains a CAldeaArray, CAldeaBuffer or CAldeaFrame object, this object is copied, not its contents. Thus, slots of the original object and of its copy will reference the same data of the array.

To make a complete copy, use the member function CAldeaArray::DeepClone.

Example

CAldeaArray oAldeaArray;
CAldeaArray oAldeaArray1;
CAldeaBuffer oAldeaBuffer1;
CAldeaFrame oAldeaFrame1;
oAldeaArray.AddArraySlot(12);
oAldeaArray.AddArraySlot(oAldeaSubArray1);
oAldeaArray.AddArraySlot(oAldeaSubBuffer1);
oAldeaArray.AddArraySlot(oAldeaSubFrame1);
CAldeaArray oAldeaArrayClone = oAldeaArray.Clone();
//	oAldeaArrayClone have four slots of the same name to these of
//	oAldeaArray, except the integer slot (containing 12), the other slots
//	share their data with slots of same name in oAldeaArray

See also

CAldeaArray::DeepClone


CAldeaArray::DeepClone

Complete duplication of an array and  its elements

CAldeaArray CAldeaArray::DeepClone();

Return value

A CAldeaArray object  is a complete copy of the current object.

Description

This function performs a complete copy of an array. All the slots of the array are fully copied, simple types (asLong, asString,...) as complex types (asBuffer, asFrame and asArray). For example, if a slot contains a CAldeaArray object, its copy will not contain the same data of the array, but a complete copy of the data of the array.

To make a superficial copy, use the member function CAldeaArray::Clone.

Example

CAldeaArray oAldeaArray;
CAldeaArray oAldeaArray1;
CAldeaBuffer oAldeaBuffer1;
CAldeaFrame oAldeaFrame1;
oAldeaArray.AddArraySlot(12);
oAldeaArray.AddArraySlot(oAldeaSubArray1);
oAldeaArray.AddArraySlot(oAldeaSubBuffer1);
oAldeaArray.AddArraySlot(oAldeaSubFrame1);
CAldeaArray oAldeaArrayClone = oAldeaArray.DeepClone();
//	oAldeaArrayClone have four slots of the same name to these of
//	oAldeaArray, the slots are completely copied, they don't
//	share their data with slots of same name in oAldeaArray

See also

CAldeaArray::Clone


CAldeaArray::Dump

Representation of the object in string form

virtual CAldeaString CAldeaArray::Dump(BOOL bToDebugger = FALSE) const;

Parameters

bToDebugger	If this parameter is at TRUE, under Win32, the string is sent to the debugger.

Return value

The string representing the object.

Description

This function allows you  to recover a string containing a representation of the array.

Example of string:

[ array at 0x120060
0 : "Jean" (String),
1 : 30 (Long),
2 : { frame at 0120180
street : "Superman street" (String),
city : "Metropolis" (String),
},
]

CAldeaArray::Dump is a help function to the development. Do not use this out of the debugging phase because the bigger the frame is, the longer the process time is.


CAldeaArray::Is<type>

Testing  the slot type

BOOL CAldeaArray::IsArray(long	nIndex)	const;
BOOL CAldeaArray::IsBool(long	nIndex)	const;
BOOL CAldeaArray::IsBuff(long	nIndex)	const;
BOOL CAldeaArray::IsByte(long	nIndex)	const;
BOOL CAldeaArray::IsDateTime(long	nIndex)	const;
BOOL CAldeaArray::IsDouble(long	nIndex)	const;
BOOL CAldeaArray::IsFloat(long	nIndex)	const;
BOOL CAldeaArray::IsFrame(long	nIndex)	const;
BOOL CAldeaArray::IsLong(long	nIndex)	const;
BOOL CAldeaArray::IsNil(long	nIndex)	const;
BOOL CAldeaArray::IsShort(long	nIndex)	const;
BOOL CAldeaArray::IsString(long	nIndex)	const;
BOOL CAldeaArray::IsSymbol(long	nIndex)	const;
BOOL CAldeaArray::IsTrue(long	nIndex)	const;
BOOL CAldeaArray::IsArray(LPCTSTR	pPath)	const;
BOOL CAldeaArray::IsBool(LPCTSTR	pPath)	const;
BOOL CAldeaArray::IsBuff(LPCTSTR	pPath)	const;
BOOL CAldeaArray::IsByte(LPCTSTR	pPath)	const;
BOOL CAldeaArray::IsDateTime(LPCTSTR	pPath)	const;
BOOL CAldeaArray::IsDouble(LPCTSTR	pPath)	const;
BOOL CAldeaArray::IsFloat(LPCTSTR	pPath)	const;
BOOL CAldeaArray::IsFrame(LPCTSTR	pPath)	const;
BOOL CAldeaArray::IsLong(LPCTSTR	pPath)	const;
BOOL CAldeaArray::IsNil(LPCTSTR	pPath)	const;
BOOL CAldeaArray::IsShort(LPCTSTR	pPath)	const;
BOOL CAldeaArray::IsString(LPCTSTR	pPath)	const;
BOOL CAldeaArray::IsSymbol(LPCTSTR	pPath)	const;
BOOL CAldeaArray::IsTrue(LPCTSTR	pPath)	const;

Parameter

nIndex	Index of the element to test.

pPath	Path to a slot of the array. The names of slots must not contain accentuated characters (ASCII codes greater than 127). The point (.) allows to separate the slots. The apostrophe (') and space are prohibited. The path does not differentiate between uppercase and lowercase characters.

Return values

TRUE if the condition is verified and  FALSE if the condition is not verified.

Description

This function test the type of a slot or of an element. If the slot does not exist, the condition is not verified. You have to use CAldeaBaseFrame::HasSlot to test the presence of the slot.

See also

CAldeaBaseFrame::HasSlot, CAldeaBaseFrame::Is<type>, asType


CAldeaArray::RemoveElements

Suppression of the array elements

AldeaError	CAldeaArray::RemoveElements(	long	nIndex,
long	nCount = 1);

Parameters

nIndex	Index of the first element to remove. The first element of an array is at the position 0 (Zero).

nCount	Number of element to remove.

Return value

A value of type AldeaError, aeNoError  if no error occurred.

Description

This function removes nCount elements of the array beginning by those put in at the index nIndex.

Example

CAldeaArray oAldeaArray;
oAldeaArray.AddArraySlot("John");
oAldeaArray.AddArraySlot("Bill");
oAldeaArray.AddArraySlot("Henry");
oAldeaArray.AddArraySlot("Kevin");
oFrame.RemoveElements(1L,2L);

RESULTS :
Before RemoveElements
[
0 : "John",
1 : "Bill",
2 : "Henry",
3 : "Kevin",
]
After RemoveElements
[
0 : "John",
1 : "Kevin",
]


CAldeaArray::RemoveSlot

Deleting an element

AldeaError CAldeaArray::RemoveSlot( long nIndex);

Parameter

nIndex	Index of the element to be removed. The first element of an array is at the index 0(Zero).

Return value

A value of type AldeaError, aeNoError  if no error occurred.

Description

This function removes an element from the array. The index of each element following the removed element is decreased of one unit.

Example

CAldeaArray oAldeaArray;
oAldeaArray.AddArraySlot("John");
oAldeaArray.AddArraySlot("Bill");
oAldeaArray.AddArraySlot("Henry");
oAldeaArray.AddArraySlot("Kevin");
oFrame.RemoveSlot(1L);

RESULTS :
Before RemoveSlot
[
0 : "John",
1 : "Bill",
2 : "Henry",
3 : "Kevin",
]
After RemoveSlot
[
0 : "André",
1 : "John",
2 : "Kevin",
]

See also

CAldeaArray::AddArraySlot

CAldeaBaseFrame::AddSlot

CAldeaBaseFrame::RemoveSlot


CAldeaArray::SetLength

Resizing the array

AldeaError CAldeaArray::SetLength(const long nLength);

Parameters

nLength	Final size of the array.

Description

To change the size of the array :

•	By increasing it, the missing elements are automatically created with the value nil (type asBool).

•	By decreasing it, elements at the end of the array which are in excess are removed.

Example

CAldeaArray oAldeaArray;
oAldeaArray.AddArraySlot((long)12);	//	element 1 (index 0)
oAldeaArray.AddArraySlot((float)1.1);	//	element 2 (index 1)
oAldeaArray.AddArraySlot((long)11);	//	element 3 (index 2)
//	There are three elements.
oAldeaArray.SetLength(2);	//	we need only two elements
//	the element 3 (index 2) is removed.
oAldeaArray.SetLength(10);	//	We need ten elements. The elements
//	of index 2 to 9 are created.


CAldeaArray::operator[ ]

Access to elements operator

CAldeaSlot& CAldeaArray::operator[ ](const long	nPos);
CAldeaSlot& CAldeaArray::operator[ ](LPCTSTR	pPath)
CAldeaSlot& CAldeaArray::operator[ ](CAldeaArray&	oPathArray);

Parameters

nPos	The position (or the index) of one of the elements of the array. The first element is at the position 0 (zero).

pPath	Path to a slot of the array. The names of slots must not contain accentuated characters (ASCII codes greater then 127). The point (.) allows to separate the slots. The apostrophe (') and space are prohibited. The path does not differentiate between uppercase and lowercase characters.

oPathArray	Path to a slot in array form. The array elements must be symbols (type asSymbol) or long integers (type asLong).

Return value

 A reference on a CAldeaSlot object.

Description

These operator allows you to access the object slots.

Warning, if you use these operators to handle CAldeaSlot objects, it is preferable that you first check with the function CAldeaBaseFrame::HasSlot that the element designed by the path (in string or array form) exists. In the case of the element does not exist, it is created in the CAldeaArray object and its value is Nil (type asBool). All the elements preceding it (by order of index) and which do not exist are automatically created at Nil. If you access  the element of index 2999 (the 3000th element) of a ten elements CAldeaArray, 2990 elements will be created.

Example

CAldeaArray oAldeaArray;
oAldeaArray[0L] = (long)128;	//	0L is the same as (long)0
oAldeaArray[_T("1.Slot1")] = (long)128;	//	Creation of a child frame at the index1
//	child frame contains the slot Slot1.
CAldeaSlot oAldeaSlot1(oAldeaFrame[0L]);	//	oAldeaSlot1 is correctly
//	initialize because the element existed
//	in the array (type asLong).
CAldeaSlot oAldeaSlot2(oAldeaFrame[_T("1.Slot1")]);	//	oAldeaSlot1 is correctly
//	initialized because it was existing
//	in the frame (type asLong).
CAldeaSlot oAldeaSlot3(oAldeaFrame[10L]);	//	oAldeaSlot3 have the type of asNil
//	because it is being created in the
//	array. The elements 2 to 9
//	were created automatically.

See also

CAldeaBaseFrame::HasSlot, CAldeaBaseFrame::operator[ ]


CAldeaBuffer

CAldeaBuffer inherits from CAldeaObject.

The function of this class is to encapsulate the management of a memory area (a buffer) and to share it with other CAldeaBuffer objects and to destroy (release) it automatically when any CAldeaBuffer object references it.

The CAldeaBuffer objects are based on the reference counter principle:

•	when an object is created, it references a memory area. If it is copied (by the constructor or the assignation operator), the reference counter on this area is increased. This area is not copied out, it is only referenced one more time.

•	When a CAldeaBuffer object is destroyed the reference counter is decreased. When the counter is at to zero, the memory area is automatically destroyed (released).

See also

Hierarchy Chart


Les membres de CAldeaBuffer
CAldeaBuffer Membres

Member Functions

CAldeaBuffer::CAldeaBuffer

CAldeaBuffer::~CAldeaBuffer

CAldeaBuffer::ClearInstance

CAldeaBuffer::Clone

CAldeaBuffer::GetBuffer

CAldeaBuffer::GetSize

Member operators

CAldeaBuffer::operator=

CAldeaBuffer::operator+=


CAldeaBuffer::CAldeaBuffer

Constructor

CAldeaBuffer::CAldeaBuffer();
CAldeaBuffer::CAldeaBuffer(	const void *	pBuffer,
const long	nSize);
CAldeaBuffer::CAldeaBuffer(	const CAldeaBuffer&	oBuffer);

Paramètres

pBuffer	A memory area pointer.

nSize	The number of bytes to copy from the memory area pointed by pBuffer.

oBuffer	An existing CAldeaBuffer object to copy out in the object in construction.

Description

The three constructors initialised a new object CAldeaBuffer :

•	The first constructor creates a new memory area of empty size.

•	The second constructor creates a new memory area of size nSize in copying the nSize first buffer bytes pointed by pBuffer. Warning, the CAldeaBuffer object does not tale down the area pointed by pBuffer. This is not destroyed during the construction.

•	The third constructor does not make a copy of the memory area referenced by oBuffer. This only increases the number of references in this area.

Example

CAldeaBuffer oAldeaBuffer1;
CAldeaBuffer oAldeaBuffer2("A little string",10);	//	Only the 10 first characters
//	are copied
CAldeaBuffer oAldeaBuffer3(oAldeaBuffer2);	//	the buffer of oAldeaBuffer2
//	is not copied out

See also

CAldeaBuffer::~CAldeaBuffer, CAldeaBuffer::operator=


CAldeaBuffer::~CAldeaBuffer

Destructor

CAldeaBuffer::~CAldeaBuffer();

Description

The CAldeaBuffer destructor decreased the reference counter on the pointed memory area. When this counter reaches zero, the memory area is destroyed (released).

See also

CAldeaBuffer::CAldeaBuffer, CAldeaBuffer::operator=


CAldeaBuffer::CearInstance
CAldeaBuffer::ClearInstance

Buffer initialisation

void CAldeaBuffer::ClearInstance();

Description

This function empties the CAldeaBuffer object. The pointed area is unallocated only if the object was the only CAldeaBuffer to reference it. The object points on a new area of null size.

If other CAldeaBuffer objects was referenced on the same memory area as the current object, they remain unchanged.

Example

CAldeaBuffer oAldeaBuffer1("Un petit texte",10);
CAldeaBuffer oAldeaBuffer2(oAldeaBuffer1);
long nBufferSize ;
nBufferSize = oAldeaBuffer1.GetSize();	//	nBufferSize == 10
oAldeaBuffer.ClearInstance();
nBufferSize = oAldeaBuffer1.GetSize();	//	nBufferSize == 0
nBufferSize = oAldeaBuffer2.GetSize();	//	nBufferSize == 10

See also

CAldeaBuffer::CAldeaBuffer, CAldeaBuffer::operator=


CAldeaBuffer::Clone

Duplication of a buffer

CAldeaBuffer CAldeaBuffer::Clone();

Return value

A CAldeaBuffer object referencing a copy of the memory area referenced by the current object.

Description

Returns a new buffer containing the copy of the memory are referenced by the current CAldeaBuffer object. Unlike a CAldeaBuffer standard copy, the new CAldeaBuffer object does not reference the same memory area, but a new copy of this area.

Example

CAldeaBuffer oAldeaBuffer1("Un petit texte",10);
CAldeaBuffer oAldeaBuffer2(oAldeaBuffer1);
CAldeaBuffer oAldeaBuffer3(oAldeaBuffer1.Clone());
// oAldeaBuffer1 and oAldeaBuffer2 reference the same memory buffer
// oAldeaBuffer3 reference another memory buffer (which contains
// actually a copy of the buffer eferenced by oAldeaBuffer1).

See also

CAldeaBuffer::CAldeaBuffer, CAldeaBuffer::operator=


CAldeaBuffer::GetBuffer

Pointer on the buffer encapsulated by the CAldeaBuffer object

const void * CAldeaBuffer::GetBuffer() const;

Return value

The address of the memory area referenced by this object.

Description

Returns the address of the memory area (the buffer) referenced by the CAldeaBuffer object.

Warning

We advise you against directly modifying the contents of this memory area as it may be shared with other CAldeaBuffer object.  If you need to modify the memory area, do not change its size as the CAldeaBuffer object will not be able to know the size of this memory area that it is referencing.  Do not destroy this memory area which is being modified as this will generate a critical error when destroying (releasing) the CAldeaBuffer object.

Example

CAldeaBuffer oAldeaBuffer;
const void * pBuffer = oAldeaBuffer.GetBuffer();	//	Pointer on the buffer
//	which is of size 0 (zero) !

See also

CAldeaBuffer::GetSize


CAldeaBuffer::GetSize

Size of the buffer

long CAldeaBuffer::GetSize() const;

Return value

A long integer containing the size of the memory area referenced by the object.

Description

Returns the size of the memory area referenced by the CAldeaBuffer object.

Example

CAldeaBuffer oAldeaBuffer1;
CAldeaBuffer oAldeaBuffer2("Un texte",8);
long nBufferSize;
nBufferSize = oAldeaBuffer1.GetSize();	//	returns 0 (zero)
nBufferSize = oAldeaBuffer2.GetSize();	//	returns 8

Voir aussi

CAldeaBuffer::GetBuffer


CAldeaBuffer::operator=

Copy out of an CAldeaBuffer object

const CAldeaBuffer& operator=(	const CAldeaBuffer&	oBuffer);

Return value

A reference on the current CAldeaBuffer object.

Description

Warning, this function does not copy the memory area referenced by the oBuffer object. It only increases the reference counter on this area.

Example

CAldeaBuffer oAldeaBuffer1("A small text",10);
CAldeaBuffer oAldeaBuffer2;
oAldeaBuffer2 = oAldeaBuffer1;
//	oAldeaBuffer1 and oAldeaBuffer2 reference the same memory area


CAldeaBuffer::operator+=

Concatenation of buffers

const CAldeaBuffer& CAldeaBuffer::operator+=( const CAldeaBuffer& oBuff);

Return value

A reference on the current CAldeaBuffer object.

Description

This funtion allocates a new memory area and added the area memory referenced by the current buffer with those referenced by oBuff. This new area is referenced by the current CAldeaBuffer object and also by all the other CAldeaBuffers which share the same reference with it.

Example

CAldeaBuffer oAldeaBuffer1("A small text",10);
CAldeaBuffer oAldeaBuffer2(oAldeaBuffer1);
CAldeaBuffer oAldeaBuffer3("Another small text",12);
oAldeaBuffer1 += oAldeaBuffer3;
//	oAldeaBuffer1 and oAldeaBuffer2 always reference a unique memory buffer
//	which contaiins the string "A small teAnother smal"


CAldeaBaseFrame

CAldeaBaseFrame inherits from CAldeaObject.

The CAldeaBaseFrame class must not be directly used. It is an abstract class which is used as a base by the CAldeaArray and CAldeaFrame class.

See also

Hierarchy Chart


CAldeaBaseFrame members

Member functions

CAldeaBaseFrame::AddSlot

CAldeaBaseFrame::ConvertFromBuffer

CAldeaBaseFrame::ConvertToBuffer

CAldeaBaseFrame::Dump

CAldeaBaseFrame::GetFileFromSlot

CAldeaBaseFrame::HasSlot

CAldeaBaseFrame::Is<type>

CAldeaBaseFrame::Length

CAldeaBaseFrame::PutFileIntoSlot

CAldeaBaseFrame::RemoveSlot

CAldeaBaseFrame::Reset

CAldeaBaseFrame::SetSlotEmptyArray

CAldeaBaseFrame::SetSlotEmptyFrame

CAldeaBaseFrame::SetSlotNil

CAldeaBaseFrame::SetSlotTrue

Member operators

CAldeaBaseFrame::operator[ ]

Member data

CAldeaBaseFrame::m_pFrameData


CAldeaBaseFrame::AddSlot

To add a slot if it does not exist and assign it a new value

AldeaError CAldeaBaseFrame::AddSlot(LPCTSTR pPath, LPCTSTR pValue);
AldeaError CAldeaBaseFrame::AddSlot(LPCTSTR pPath, BOOL boolValue);
AldeaError CAldeaBaseFrame::AddSlot(LPCTSTR pPath, const CAldeaString &sValue);
AldeaError CAldeaBaseFrame::AddSlot(LPCTSTR pPath, unsigned char bValue);
AldeaError CAldeaBaseFrame::AddSlot(LPCTSTR pPath, short iValue);
AldeaError CAldeaBaseFrame::AddSlot(LPCTSTR pPath, long lValue);
AldeaError CAldeaBaseFrame::AddSlot(LPCTSTR pPath, float fltValue);
AldeaError CAldeaBaseFrame::AddSlot(LPCTSTR pPath, double dblValue);
AldeaError CAldeaBaseFrame::AddSlot(LPCTSTR pPath, const CAldeaBaseFrame& oFrameValue);
AldeaError CAldeaBaseFrame::AddSlot(LPCTSTR pPath, const CAldeaDateTime& oSystemTimeValue);
AldeaError CAldeaBaseFrame::AddSlot(LPCTSTR pPath, const CAldeaArray &oArrayValue);
AldeaError CAldeaBaseFrame::AddSlot(LPCTSTR pPath, const CAldeaSlot &oAldeaVariantValue);
AldeaError CAldeaBaseFrame::AddSlot(LPCTSTR pPath, const CAldeaBuffer &oBuffValue);
AldeaError CAldeaBaseFrame::AddSlot(LPCTSTR pPath, const VARIANT &oVariantValue);

Parameters

pPath	The access path to a slot of the object. The names of the slots must not contain accentuated characters (ASCII codes greater than 127). The point (.) allows to separate the slots. The apostrophe (') and space are prohibited. The path does not differentiate between uppercase and lowercase characters.

pValue	The slot value of type string.

boolValue	The slot value of type boolean.

svalue	The slot value of type string

Return value

A value of type AldeaError

aeNoError	 If the was no error.

Description

Allows you to add a slot to current frame. The CAldeaBaseFrame::operator[ ] operator can be also used to add a slot.

Example

// Example for CAldeaBaseFrame::AddSlot
CAldeaFrame oFrame;	// We don't manipulate a CAldeaBaseFrame
oFrame.AddSlot("identity.first_name", "loic"); // Adding of a slot "first_name" in the
// subframe "identity"
oFrame.AddSlot("identity.name", "martin");	// Adding of a slot "name" in the subframe
// "identity"
oFrame.AddSlot("identity.age", 35);	// Adding of a slot "age" in the subframe
// "identity"

The result frame is :
{
identity :
{
first_name : "loic"
name : "martin"
age : 35
}
}

See also

CAldeaBaseFrame::operator[ ], CAldeaBaseFrame::RemoveSlot


CAldeaBaseFrame::ConvertFromBuffer

Conversion of a buffer into frame

AldeaError CAldeaBaseFrame::ConvertFromBuffer(const CAldeaBuffer &oBuff);

Parameters

oBuff	  An existing CAldeaBuffer object returned by the ConvertToBuffer function.

Return value

A value of type AldeaError

aeNoError	 If the was no error.

Description

Allows you to build the current frame from a buffer returned by the ConvertToBuffer function.

Example

// Example for CAldeaBaseFrame::ConvertFromBuffer
CAldeaFrame oFrame;	// We don't manipulate CAldeaBaseFrame
CAldeaBuffer oBuff;	// An empty buffer
oFrame["nom.first_name"] = "loic";	// Adding of a slot
oFrame.ConvertToBuffer(oBuff);	// Conversion of the frame into buffer
/* ... */
CAldeaBaseFrame oNewFrame;	// An empty frame
oNewFrame.ConvertFromBuffer(oBuff);	// Building of the frame from the buffer

See also

CAldeaBaseFrame::ConvertToBuffer


CAldeaBaseFrame::ConvertToBuffer

Conversion of a frame into buffer

AldeaError CAldeaBaseFrame::ConvertToBuffer(CAldeaBuffer &oBuff) const;

Parameters

oBuff	An existing CAldeaBuffer object returned by the function.

Return value

A value of type AldeaError

aeNoError	 If the was no error.

Description

Allows you to build a buffer (bytes suite) from the current frame. If the buffer passed in the parameter is not empty, its contents are destroyed.

Example

// Exemple pour CAldeaBaseFrame::ConvertToBuffer
CAldeaFrame oFrame;	// We don't manipulate CAldeaBaseFrame
CAldeaBuffer oBuff;	// An empty buffer
oFrame["nom.first_name"] = "Jean";	// Adding of a slot
oFrame.ConvertToBuffer(oBuff);	// Conversion of the frame into buffer

See also

CAldeaBaseFrame::ConvertFromBuffer, CAldeaBuffer


CAldeaBaseFrame::Dump

Converts the object into a string

virtual CAldeaString CAldeaBaseFrame::Dump(BOOL bToDebugger = FALSE) const;

Parameters

bToDebugger	If this parameter is TRUE, under Win32, the string is sent to the debugger.

Return value

A string, representation of the object.

Description

This function allows you to recuperate a string containing the representation of the frame.

String example :

{ frame at 0x120060
first_name : "Jean" (String),
name : "Martin" (String),
age : 30 (Long),
address : { frame at 0120180
streeet : "Lafayette" (String),
city : "New York" (String),
},
}

CAldeaBaseFrame::Dump is a help to applications development. It is recommended not to use it out of debugging phase because the bigger frame is, the longer the processing time is. This process and the time required for using the result string, may require a lot of memory.


CAldeaBaseFrame::GetFileFromSlot

Saving of a file stored in a slot

AldeaError CAldeaBaseFrame::GetFileFromSlot(LPCTSTR pPath, LPCTSTR pFileName);

Parameters

pPath	The access path to a slot of the object. The names of the slots must not contain accentuated characters (ASCII codes greater than 127). The point (.) allows to separate the slots. The apostrophe (') and space are prohibited. The path does not differentiate between uppercase and lowercase characters.

pFileName	File path.

Return value

A value of type AldeaError

aeNoError	 If the was no error.

Description

This method allows you to save a file put in a frame slot with the CAldeaBaseFrame::PutFileIntoSlot method.

This function is for transmitting a file of any type. For example, if a client A wants to transmit a file to client B, he puts the file to transmit into a slot of a frame with the CAldeaBaseFrame::PutFileIntoSlot method, then he tramsmits the frame to the client B who can get the file from the slot with the CAldeaBaseFrame::GetFileFromSlot method.

Example

CAldeaFrame oAldeaFrame;	//	We don't manipulate CAldeaBaseFrame
oAldeaFrame.PutFileIntoSlot(	_T("Slot1"),
_T("C:\Temp\ MyWordFile.doc "));
oAldeaFrame.GetFileFromSlot(	_T("Slot1"),
_T("C:\Mes Documents\ MyNewWordFile.doc "));
// The file MyWordFile.doc was transmitted into the "Slot1"
// then saving into the file MyNewWordFile.doc

See Also

CAldeaBaseFrame::PutFileIntoSlot


CAldeaBaseFrame::HasSlot

Test of a slot presence

BOOL CAldeaBaseFrame::HasSlot(LPCTSTR pPath) const;

Parameter

pPath	The access path to a slot of the object. The names of the slots must not contain accentuated characters (ASCII codes greater than 127). The point (.) allows to separate the slots. The apostrophe (') and space are prohibited. The path does not differentiate between uppercase and lowercase characters.

Return values

TRUE if the slot exists, FALSE if the slot does not exist..

Description

This function test if the slot pointed by the pPath path exists in the frame.

See also

CAldeaBaseFrame::Is<type>


CAldeaBaseFrame::Is<type>

Test of a slot type

BOOL CAldeaBaseFrame::IsArray(LPCTSTR	pPath)	const;
BOOL CAldeaBaseFrame::IsBool(LPCTSTR	pPath)	const;
BOOL CAldeaBaseFrame::IsBuff(LPCTSTR	pPath)	const;
BOOL CAldeaBaseFrame::IsByte(LPCTSTR	pPath)	const;
BOOL CAldeaBaseFrame::IsDateTime(LPCTSTR	pPath)	const;
BOOL CAldeaBaseFrame::IsDouble(LPCTSTR	pPath)	const;
BOOL CAldeaBaseFrame::IsFloat(LPCTSTR	pPath)	const;
BOOL CAldeaBaseFrame::IsFrame(LPCTSTR	pPath)	const;
BOOL CAldeaBaseFrame::IsLong(LPCTSTR	pPath)	const;
BOOL CAldeaBaseFrame::IsNil(LPCTSTR	pPath)	const;
BOOL CAldeaBaseFrame::IsShort(LPCTSTR	pPath)	const;
BOOL CAldeaBaseFrame::IsString(LPCTSTR	pPath)	const;
BOOL CAldeaBaseFrame::IsSymbol(LPCTSTR	pPath)	const;
BOOL CAldeaBaseFrame::IsTrue(LPCTSTR	pPath)	const;

Parameter

pPath	The access path to a slot of the object. The names of the slots must not contain accentuated characters (ASCII codes greater than 127). The point (.) allows to separate the slots. The apostrophe (') and space are prohibited. The path does not differentiate between uppercase and lowercase characters.

Return values

TRUE if the condition was verified, FALSE if the condition was not verified.

Description

This function tests the slot type. If the slot does not exists, the condition is not verified. You have to use CAldeaBaseFrame::HasSlot to test the existence of the slot.

See also

CAldeaBaseFrame::HasSlot, asType


CAldeaBaseFrame::Length

slot number of the object

long CAldeaBaseFrame::Length() const;

Return value

A long integer containing the slot number (or elements for the array) of this object.

Description

Returns the slot number (or elements) of the object.


CAldeaBaseFrame::PutFileIntoSlot

Storage of a file into a slot

AldeaError CAldeaBaseFrame::PutFileIntoSlot(LPCTSTR pPath, LPCTSTR pFileName);

Parameters

pPath	The access path to a slot of the object. The names of the slots must not contain accentuated characters (ASCII codes greater than 127). The point (.) allows to separate the slots. The apostrophe (') and space are prohibited. The path does not differentiate between uppercase and lowercase characters.

pFileName	File path.

Return value

A value of type AldeaError

aeNoError	 If the was no error.

Description

This method allows you to insert a file whose path is specified by sFileName in the frame . If the path is wrong or if the file is not accessible in reading, an error is generated. The string sPath designates the slot in which the file would be placed. If the slot does not exist, it is created.

This function works on any kind of file. When the peer receives the frame, he can recuperate the file with the method CAldeaBaseFrame::GetFileFromSlot.

Warning Do not use this procedure on large files.  If the size of the file exceeds the memory capacity of your computer, there can be problems with memory and the time needed for transmission.

Example

CAldeaFrame oAldeaFrame;	//	We don't manipulate CAldeaBaseFrame
oAldeaFrame.PutFileIntoSlot(	_T("Slot1"),
_T("C:\Temp\ MyWordFile.doc "));
oAldeaFrame.GetFileFromSlot(	_T("Slot1"),
_T("C:\Mes Documents\ MyNewWordFile.doc "));
// The file MyWordFile.doc was transmitted into the "Slot1"
// then saving into the file MyNewWordFile.doc

See also

CAldeaBaseFrame::GetFileFromSlot


CAldeaBaseFrame::RemoveSlot

Destruction of a slot

AldeaError CAldeaBaseFrame::RemoveSlot(LPCTSTR pPath);

Parameter

pPath	The access path to a slot of the object. The names of the slots must not contain accentuated characters (ASCII codes greater than 127). The point (.) allows to separate the slots. The apostrophe (') and space are prohibited. The path does not differentiate between uppercase and lowercase characters.

Return value

A value of type AldeaError

aeNoError	 If the was no error.

Description

This method allows you to destroy a slot from the frame .

Example

CAldeaFrame oFrame;	//	We don't manipulate CAldeaBaseFrame
oFrame.AddSlot("identity.first_name", "John");	//	Adding of a slot "first_name" in the
//	subframe "identity"
oFrame.AddSlot("identity.name", "Smith"); 	//	Adding of a slot "name" in the subframe
//	subframe "identity"
oFrame.RemoveSlot("identity.first_name");	//	Deletion of the slot "first_name" in the 	//	subframe "identity"

The result frame is :
{
identity :
{
name : "Smith"
}
}

See also

CAldeaBaseFrame::AddSlot


CAldeaBaseFrame::Reset

Destruction of all the slots of the object

void CAldeaBaseFrame::Reset();

Return value

A value of type AldeaError

aeNoError	 If the was no error.

Description

Deletes all the slot from the data referenced by the CAldeaBaseFrame object. If another CAldeaBaseFrame object shares the same data (via the CAldeaBaseFrame::m_pFrameData member data), it does not have any slot anymore.

Example

CAldeaFrame oAldeaFrame1;	//	We don't amnipulate CAldeaBaseFrame
CAldeaFrame oAldeaFrame2(oAldeaFrame1);	//	The frames oAldeaFrame1 and oAldeaFrame2
//	reference the same frame data
oAldeaFrame1[_T("Slot1")] = (long)128;	//	add a slot to the sharing frame
//	oAldeaFrame1 and oAldeaFrame2
oAldeaFrame2.Reset();	//	We delete the oAldeaFrame2 slots
long nLength = oAldeaFrame1.Length();	//	nLength == 0, there is not any slot left
//	oAldeaFrame1 neither.

See also

CAldeaBaseFrame::m_pFrameData


CAldeaBaseFrame::SetSlotEmptyArray

Creation/modification of an empty slot of array type

AldeaError CAldeaBaseFrame::SetSlotEmptyArray(LPCTSTR pPath);

Parameter

pPath	The access path to a slot of the object. The names of the slots must not contain accentuated characters (ASCII codes greater than 127). The point (.) allows to separate the slots. The apostrophe (') and space are prohibited. The path does not differentiate between uppercase and lowercase characters.

Return value

A value of type AldeaError

aeNoError	 If the was no error.

Description

This function creates an empty array and put it in the slot pointed by the pPath path to nil (boolean FALSE). If the slot does not exist, it is created.

Example

CAldeaFrame oAldeaFrame;	//	We don't manipulate CAldeaBaseFrame
oAldeaFrame.SetSlotEmptyArray(_T("Slot1"));

See also

CAldeaBaseFrame::IsArray, CAldeaBaseFrame::IsFrame, CAldeaBaseFrame::SetSlotEmptyFrame


CAldeaBaseFrame::SetSlotEmptyFrame

Creation/modification of an empty slot of frame type

AldeaError CAldeaBaseFrame::SetSlotEmptyFrame(LPCTSTR pPath);

Parameter

pPath	The access path to a slot of the object. The names of the slots must not contain accentuated characters (ASCII codes greater than 127). The point (.) allows to separate the slots. The apostrophe (') and space are prohibited. The path does not differentiate between uppercase and lowercase characters.

Return value

A value of AldeaError type, aeNoError	 If the was no error.

Description

This function creates an empty frame and puts it in the slot pointed by the pPath path to nil (boolean FALSE). If the slot does not exist, it is created.

Example

CAldeaFrame oAldeaFrame;	//	We don't manipulate CAldeaBaseFrame
oAldeaFrame.SetSlotEmptyFrame(_T("Slot1"));

See also

CAldeaBaseFrame::IsArray, CAldeaBaseFrame::IsFrame, CAldeaBaseFrame::SetSlotEmptyArray


CAldeaBaseFrame::SetSlotNil

Creation/modification of a slot to Nil

AldeaError CAldeaBaseFrame::SetSlotNil(LPCTSTR pPath);

Parameter

pPath	The access path to a slot of the object. The names of the slots must not contain accentuated characters (ASCII codes greater than 127). The point (.) allows to separate the slots. The apostrophe (') and space are prohibited. The path does not differentiate between uppercase and lowercase characters.

Return values

A value of type AldeaError

aeNoError	 If the was no error.

Description

This function puts the slot pointed by the pPath path to nil (boolean FALSE). If the slot does not exist, it is created.

Example

CAldeaFrame oAldeaFrame;	//	We don't manipulate CAldeaBaseFrame
oAldeaFrame.SetSlotNil(_T("Slot1"));

See also

CAldeaBaseFrame::IsTrue, CAldeaBaseFrame::IsNil, CAldeaBaseFrame::SetSlotTrue


CAldeaBaseFrame::SetSlotTrue

Creation/modification of a slot to True

AldeaError CAldeaBaseFrame::SetSlotTrue(LPCTSTR pPath);

Parameter

pPath	The access path to a slot of the object. The names of the slots must not contain accentuated characters (ASCII codes greater than 127). The point (.) allows to separate the slots. The apostrophe (') and space are prohibited. The path does not differentiate between uppercase and lowercase characters.

Return values

A value of type AldeaError

aeNoError	 If the was no error.

Description

This function puts the slot pointed by the pPath path to true (boolean TRUE). If the slot does not exist, it is created.

Example

CAldeaFrame oAldeaFrame;	//	We don't manipulate CAldeaBaseFrame
oAldeaFrame.SetSlotTrue(_T("Slot1"));

See also

CAldeaBaseFrame::IsTrue, CAldeaBaseFrame::IsNil, CAldeaBaseFrame::SetSlotNil


CAldeaBaseFrame::operator[ ]

Access operator to slots

CAldeaSlot& CAldeaBaseFrame::operator[ ](LPCTSTR	pPath);
CAldeaSlot& CAldeaBaseFrame::operator[ ](CAldeaArray&	oPathArray);

Parameters

pPath	The access path to a slot of the object. The names of the slots must not contain accentuated characters (ASCII codes greater than 127). The point (.) allows to separate the slots. The apostrophe (') and space are prohibited. The path does not differentiate between uppercase and lowercase characters.

oPathArray	Path to slot of type array. array elements must be symbols (asSymbol type) or long integers (asLong type).

Return value

A reference on a CAldeaSlot object.

Description

These operators allow you to access to object slots.

Warning, if you use this operators to manipulate CAldeaSlot objects, it is helpful to check with the CAldeaBaseFrame::HasSlot function that the slot designated by the path (in string or array form) exist. In the case of it does not exist, it is created in the CAldeaBaseFrame object and its type is asUndefined.

Example

CAldeaFrame oAldeaFrame;	//	We don't manipulate CAldeaBaseFrame
oAldeaFrame[_T("Slot1")] = (long)128;
CAldeaSlot oAldeaSlot1(oAldeaFrame[_T("Slot1")]);	//	oAldeaSlot1 is correctly
//	initialised because it was existing
//	in the frame (asLong type).
CAldeaSlot oAldeaSlot2(oAldeaFrame[_T("Slot2")]);	//	oAldeaSlot2 is of asUndefined type
//	because it was just created in the 	//  frame

See also

CAldeaBaseFrame::HasSlot


CAldeaDateTime::m_pFrameData
CAldeaBaseFrame::m_pFrameData

Pointer on the internal data of the frame object

CAldeaBaseFrameData* CAldeaBaseFrame::m_pFrameData;

Description

Warning , this pointer must not be manipulated. The internal format of the CAldeaBaseFrame object data is private and subject to change.

This member data is documented only to help you to understand the copy-out mechanism of the frame (CAldeaFrame object) and array(CAldeaArray object).

The copy-out constructor and the copy operator of the CAldeaFrame are the same as for the CAldeaArray.

1.	When the oFrame1 object (CAldeaFrame type) is created, the CAldeaBaseFrame constructor is called. In this constructor, a new CAldeaBaseFrameData object is allocated in memory and the m_pFrameData member data of oFrame1 points on this.

2.	When oFrame2 (same CAldeaFrame type) is copied (copy constructor or copy by assignment) from the oFrame1 object, the m_pFrameData data member of oFrame1 and oFrame2 points on the same object which reference counter is increased by one unit.

3.	When we add, delete or modify a oFrame1 slot, the oFrame1 and oFrame2 objects share data via m_pFrameData, the changing affect oFrame2 . Example : if we add a "Slot1" slot to oFrame1 , we can access to this same slot by oFrame2 . If we delete "Slot1" from oFrame2, itis also deleted in oFrame1.

4.	When the oFrame2 object is deleted, it no longer references the object pointed by m_pFrameData, but this last object is not deleted because the oFrame1 m_pFrameData always points on it. The reference counter is decreased by one unit.

1.	When oFrame1 is deleted, the reference counter reaches zero (any object reference it), the object pointed by deletes itself.

Copy Constructor CAldeaFrame * A = new CAldeaFrame(); CAldeaFrame * B = new CAldeaFrame(A); delete B; delete A;	Assignment Operator CaldeaFrame * A = new CAldeaFrame(); CaldeaFrame * B = new CAldeaFrame(); B = A; delete B; delete A;
See also

CAldeaArray, CAldeaFrame


CAldeaDateTime

CAldeaDateTime haven't a base class.

The CAldeaDateTime class allows you to manipulate the dates, to put it in the frame or to convert it into types like COleDateTime or SYSTEMTIME.

This class does not allow you to do calculation operations on dates. The dates are not checked. For examples, the CAldeaDateTime::m_nDayOfWeek data member (day of the week) is not used. If you put a date with a wrong day of the week, this will not be corrected and this may provoke conversion problems to a SYSTEMTIME structure. If you put a correct day of the week, it will be stored . You will not lose it during the explicit or implicit manipulation (in a frame or a array) of a CAldeaDateTime.

See also

Hierarchy Chart


Les membres de CAldeaDateTime
CAldeaDateTime members

Member functions

CAldeaDateTime::CAldeaDateTime

CAldeaDateTime::Compare

CAldeaDateTime::SetDateTime

Member operators

CAldeaDateTime::operateur =

CAldeaDateTime::operateur <type>()

Member data

CAldeaDateTime::m_nYear

CAldeaDateTime::m_nMonth

CAldeaDateTime::m_nDay

CAldeaDateTime::m_nHour

CAldeaDateTime::m_nMinute

CAldeaDateTime::m_nSecond

CAldeaDateTime::m_nDayOfWeek


CAldeaDateTime::CAldeaDateTime

Creation of a CAldeaDateTime object

CAldeaDateTime::CAldeaDateTime();
CAldeaDateTime::CAldeaDateTime(	short nYear,
short nMonth,
short nDay,
short nHour,
short nMinute,
short nSecond);
CAldeaDateTime::CAldeaDateTime(	short nYear,
short nMonth,
short nDayOfWeek,
short nDay,
short nHour,
short nMinute,
short nSecond);
CAldeaDateTime::CAldeaDateTime(	const CAldeaDateTime& oAldeaDateTime);
CAldeaDateTime::CAldeaDateTime(	const COleDateTime& oOleDateTime);
CAldeaDateTime::CAldeaDateTime(	const SYSTEMTIME& oSysTimeVal);

Parameters

nYear	Year of the created date.

nMonth	Month of the created date.

nDay	Day of the created date.

nHour	Hour of the created date.

nMinute	Minute of the created date.

nSecond	Second of the created date.

nDayOfWeek	Day of the week of the created date. Warning , this value is not used. If you modify anything at the CAldeaDateTime object, the CAldeaDateTime::m_nDayOfWeek data member will not be calculated again.

oAldeaDateTime	An existing CAldeaDateTime object which is copied in this new CAldeaDateTime object.

oOleDateTime	An existing COleDateTime object which must is copied in this new CAldeaDateTime object.

oSysTimeVal	An existing SYSTEMTIME structure which must is copied in this new CAldeaDateTime object.

Description

The first constructor creates a CAldeaDateTime object on the date of the day.

The two other constructors initialise the data members directly without a value check (if you put the equivalent of 30/02/19996, the value are accepted). Notes that the day of the week (0 = Sunday, 1 = Monday, ...) is not managed but only stored in the m_nDayOfWeek member.

Example

CAldeaDateTime oAldeaDateTime1;

CAldeaDateTime oAldeaDateTime2(1997,12,31,23,59,59);	//	The 31/12/1997
//	at 23h59 and 59 seconds

CAldeaDateTime oAldeaDateTime3(1997,12,3,31,23,59,59);	//	The Wednesday (= 3) 31/12/1997
//	at 23h59 and 59 seconds

CAldeaDateTime oOleDateTime;	//	Today

CAldeaDateTime oAldeaDateTime4(oOleDateTime);	//

SYSTEMTIME	oSystemTime = {1997,12,3,31,23,59,59,999);

CAldeaDateTime oAldeaDateTime5(oSystemTime);	/	The Wednesday (= 3) 31/12/1997
//	at 23h59 and 59 seconds. The 999
//	thousandths of a second are lost.

See also

CAldeaDateTime::operator=, CAldeaDateTime::operator <type>, CAldeaDateTime::SetDateTime


CAldeaDateTime::Compare

Comparison of dates

long CAldeaDateTime::Compare(const CAldeaDateTime& oAldeaDateTime);

Parameters

oAldeaDateTime	another CAldeaDateTime to compare with the current object

Return values

A long integer equal to :
0, if the dates are equal;
-1, if the date is less than the oAldeaDateTime parameter;
1, if the date is greater than the oAldeaDateTime parameter.

Description

Compare the CAldeaDateTime object with abother CAldeaDateTime object.

Example

{
if (oAldeaDateTime1.Compare(oAldeaDateTime2) < 0)
return _T("Date 1 is less than Date 2");
if (oAldeaDateTime1.Compare(oAldeaDateTime2) > 0)
return _T("Date 1 is greater than Date 2");
return _T("Date 1 is identical to Date 2");
}


CAldeaDateTime::SetDateTime

Changing of the date value

void CAldeaDateTime::SetDateTime(	short nYear,
short nMonth,
short nDay,
short nHour,
short nMinute,
short nSecond);

Parameters

nYear	New year of the date.

nMonth	New month of the date.

nDay	New day of the date.

nHour	New hour of the date.

nMinute	New minute of the date.

nSecond	New second of the date.

Description

This function puts a new date and a new time in the CAldeaDateTime object.

Warning, the parameter value are not checked.

Example

CAldeaDateTime oAldeaDateTime;	//	Current date and time

oAldeaDateTime.SetDateTime(1997,12,31,23,59,59);	//	the 31/12/1997
//	at 23h59 and 59 seconds

See also

CAldeaDateTime::CAldeaDateTime


CAldeaDateTime::operator =

Assignment

CAldeaDateTime& CAldeaDateTime::operator=(const CAldeaDateTime& oAldeaDateTime);

CAldeaDateTime& CAldeaDateTime::operator=(const COleDateTime& oOleDateTime);

CAldeaDateTime& CAldeaDateTime::operator=(const SYSTEMTIME& oSysTimeVal);

Parameters

oAldeaDateTime	An existing CAldeaDateTime object which must be copied in this CAldeaDateTime object.

oOleDateTime	An existing COleDateTime object which must be copied in this CAldeaDateTime object.

oSysTimeVal	An existing SYSTIME structure which must be copied in this CAldeaDateTime object.

Description

These assignment operators copy the date and time passed in parameters in the CAldeaDateTime object.

Warning, the parameter values are not checked.

Example

CAldeaDateTime oAldeaDateTime;	//	Current Date and time

oAldeaDateTime.SetDateTime(1997,12,31,23,59,59);	//	the 31/12/1997
//	at 23h59 and 59 seconds

See also

CAldeaDateTime::CAldeaDateTime


CAldeaDateTime::operator <type>()

Explicit conversion of type

CAldeaDateTime::operator CAldeaString() const;
CAldeaDateTime::operator COleDateTime() const;
CAldeaDateTime::operator SYSTEMTIME() const;

Return value

CAldeaString	The first conversion operator returns a CAldeaString object containing a representation in American form (MM/JJ/AA HH:MM:SS with hours in 24 hours form) of the contents of the CAldeaDateTime object.

COleDateTime	A COleDateTime object containing the same date and same time as the CAldeaDateTime object.

SYSTEMTIME	A SYSTEMTIME structure containing the same date and same time as the CAldeaDateTime object.

Description

These explicit conversion operators return a copy of the CAldeaDateTime object in different formats.

Example

CAldeaDateTime oAldeaDateTime(1997,12,31,23,59,59);	//	Current Date and time

CAldeaString sDateTime = (CAldeaString)oAldeaDateTime;	//	"12/31/1997 23:59:59"

COleDateTime oOleDateTime = (COleDateTime)oAldeaDateTime;

SYSTEMTIME oSystemTime = (SYSTEMTIME)oAldeaDateTime;

See also

CAldeaDateTime::CAldeaDateTime


CAldeaDateTime::m_nYear

Year

short CAldeaDateTime::m_nYear;

Description

Year of the CAldeaDateTime object.


CAldeaDateTime::m_nMonth

Month

short CAldeaDateTime::m_nMonth;

Description

Month of the CAldeaDateTime object.


CAldeaDateTime::m_nDay

Day

short CAldeaDateTime::m_nDay;

Description

Day of the CAldeaDateTime object.


CAldeaDateTime::m_nHour

Hour

short CAldeaDateTime::m_nHour;

Description

Hour of the CAldeaDateTime object.


CAldeaDateTime::m_nMinute

Minute

short CAldeaDateTime::m_nMinute;

Description

Minute of the CAldeaDateTime object.


CAldeaDateTime::m_nSecond

Second

short CAldeaDateTime::m_nSecond;

Description

Second of the CAldeaDateTime object.


CAldeaDateTime::m_nDayOfWeek

Day of the week

short CAldeaDateTime::m_nDayOfWeek;

Description

Day of the week of the CAldeaDateTime object. (0 = sunday, 1 = monday, ...).

Warning, this value is not always used. If an object is built with the constructor not using the day of the week, this member is initialised to 0 by default.

See also

CAldeaDateTime::CAldeaDateTime


CAldeaException

CAldeaString does not have a base class.

The CAldeaException class is used to handle the exceptions processing.

This class is made to be used with the standard exceptions processing operators try, catch and throw. Many of the frame and array operators can throw exceptions. Your application must be ready to catch them or the system may end your application (unhandled exception error).

To handle CAldeaException exceptions, a set of macros are provided. This set of macros allows you to ensure the compatibility of your code with the future release of AGcAPI. These macros are :

CATCH_ALDEA_EXCEPTION, DELETE_ALDEA_EXCEPTION, RETHROW_ALDEA_EXCEPTION, GET_ALDEA_EXCEPTION_ERROR, GET_ALDEA_EXCEPTION_ERROR_MESSAGE, and GET_ALDEA_EXCEPTION_ERROR_REASON.

Rather than creating exception objects and then throwing them, use the AldeaThrowException function.

The following code shows the exception using :

CAldeaFrame oAldeaFrame;
oAldeaFrame[_T("LongInteger")] = (long)123;
BOOL bRethrow = TRUE;
try
{
// The following line throws an exception because it demands a double real
// to a slot which contain a long integer.
double dDouble = (double)oAldeaFrame[_T("LongInteger")];
}
CATCH_ALDEA_EXCEPTION
{
afxDump << "Code: "	<< GET_ALDEA_EXCEPTION_ERROR << "\n";
afxDump << "Message: "	<< GET_ALDEA_EXCEPTION_ERROR_MESSAGE << "\n";
afxDump << "Reason: "	<< GET_ALDEA_EXCEPTION_ERROR_REASON << "\n";
if (bRethrow)
{
RETHROW_ALDEA_EXCEPTION;	//	rethrow, don't
//	destroy the exception
}
else
{
DELETE_ALDEA_EXCEPTION;	//	Needed to destroy the exception
}
}

See also

Hierarchy Chart


Les membres de CAldeaException
CAldeaException members

Member Functions

CAldeaException::CAldeaException

CAldeaException::~CAldeaException

CAldeaException::Delete

Member Data

CAldeaException::m_nError

CAldeaException::m_sError

CAldeaException::m_sReason


CAldeaException::CAldeaException

Create an exception object

CAldeaException::CAldeaException();
CAldeaException(	const AldeaError	nError,
const CAldeaString&	sError = NULL,
const CAldeaString&	sReason = NULL);

Parameters

nError	Exception Error.

sError	String indicating the exception error.

sReason	String completing the string on the exception error.

Description

The first constructor creates a CAldeaException object for a generic error (aeGenericError).

The second one, initializes the exception by indicating the error number (of the type AldeaError), an error message string and a string explaining the reason of the error.

It is recommend not to build CAldeaException objects but to use the AldeaThrowException function. This run in the best way with the CATCH_ALDEA_EXCEPTION, DELETE_ALDEA_EXCEPTION, RETHROW_ALDEA_EXCEPTION, GET_ALDEA_EXCEPTION_ERROR, GET_ALDEA_EXCEPTION_ERROR_MESSAGE, and GET_ALDEA_EXCEPTION_ERROR_REASON macros. Using this function and these macros ensures you that your code will be compatible with the future release of the AGcAPI exceptions.

Example

if (bTypeMismatch == TRUE)
{
throw new CAldeaException(	aeTypeMismatch,
_T("Type mismatch when reading a slot"),
_T("Expected an long integer go a double"));
}
else
{
throw new CAldeaException;
}

//	It is recommended to use AldeaThrowException
if (bTypeMismatch == TRUE)
{
AldeaThrowException(	aeTypeMismatch,
_T("Type mismatch when reading a slot"),
_T("Expected an long integer go a double"));
}
else
{
AldeaThrowException();
}

See also

CAldeaException::m_nError, CAldeaException::m_sError, CAldeaException::m_sReason, AldeaThrowException


CAldeaException::~CAldeaException

Destructor

virtual CAldeaException::~CAldeaException();

Description

Virtual destructor of the CAldeaException object.


CAldeaException::Delete

Deletion of a CAldeaException object (when it is pointed)

void CAldeaException::Delete();

Description

The CAldeaException exceptions have been to be thrown as pointers to an object. To catch them, you must create exception handlers which parameter will be a pointer to a CAldeaException object. In these handlers, you must not destroy the exceptions with the delete standard operator. If you don't throw the exception again (with throw) you will have to destroy the exception with the CAldeaException::Delete() member function.

Warning, to ensure the compatibility of your code with the future release of AGcAPI, it is recommended to use the predefined CATCH_ALDEA_EXCEPTION and DELETE_ALDEA_EXCEPTION macros.

Example

catch (CAldeaException * pAldeaException)
{
/*	... */
pAldeaException-Delete();
}

//	It is recommended to use
CATCH_ALDEA_EXCEPTION
{
DELETE_ALDEA_EXCEPTION
}

See also

CATCH_ALDEA_EXCEPTION, DELETE_ALDEA_EXCEPTION


CAldeaException::m_nError

Error Code

AldeaError CAldeaException::m_nError;

Description

Error code of the CAldeaException object.

See also

AldeaError, GET_ALDEA_EXCEPTION_ERROR


CAldeaException::m_sError

Error message

CAldeaString CAldeaException::m_sError;

Description

Error message of the CAldeaException object.

See also

GET_ALDEA_EXCEPTION_ERROR_MESSAGE


CAldeaException::m_sReason

Error reason

CAldeaString CAldeaException::m_sReason;

Description

Error reason of the CAldeaException object. The reason completes the error message. This can be the explanation of what caused the error.

See also

GET_ALDEA_EXCEPTION_ERROR_REASON.


CAldeaFrame

CAldeaFrame inherits from CAldeaBaseFrame.

A CAldeaFrame object is a reference to a frame by the intermediary of the CAldeaBaseFrame::m_pFrameData inherited member data. The frame slots  are generated by CAldeaSlot object that we add in the CAldeaFrame object.

It is important to note that a CAldeaFrame object is a reference to frame data (CAldeaSlot object) that it can share with another CAldeaSlot objects.

The CAldeaFrame objects use a reference counter:

•	When an object is created, it references frame data. If it is copied (by the copy constructor), the reference counter on this data is increased. The data are not copied out, they are only referenced one more time.

•	When the CAldeaFrame object is destroyed the reference counter is decreased. When the counter reaches the zero value, the frame data are automatically destroyed.

See also

Hierarchy Chart


Les membres de CAldeaFrame
CAldeaFrame Members

Member functions

CAldeaFrame::CAldeaFrame

CAldeaFrame::~CAldeaFrame

CAldeaFrame::Clone

CAldeaFrame::DeepClone

CAldeaFrame::MakeSlotArray


CAldeaFrame::CAldeaFrame

Constructor

CAldeaFrame::CAldeaFrame();
CAldeaFrame::CAldeaFrame(const CAldeaFrame&	oAldeaFrame);

Parameters

oAldeaFrame	An existing CAldeaFrame object.

Description

Creates a new CAldeaFrame object.

The second constructor (copy constructor) creates a new CAldeaFrame object from an existing oAldeaFrame object. The oAldeaFrame object data (pointed by CAldeaBaseFrame::m_pFrameData) are not copied, they are only shared between the two CAldeaFrame objects.  A reference counter is increased during the creation. In each deletion of a CAldeaFrame object referencing the same frame data, the counter is decreased. When it reaches the zero value, the frame data are deleted because any CAldeaFrame object referenced it any more.

Example

CAldeaFrame oAldeaFrame1;
oAldeaFrame1[_T("Slot")] = _T("Hello");
CAldeaFrame oAldeaFrame2(oAldeaFrame1);	//	oAldeaFrame2 reference the same
//	frame data as oAldeaFrame1.
//	Then, the "Slot" slot exist in oAldeaFrame2.

See also

CAldeaFrame::~CAldeaFrame, CAldeaBaseFrame::m_pFrameData


CAldeaFrame::~CAldeaFrame

Destructor

virtual CAldeaFrame::~CAldeaFrame();

Description

The CAldeaFrame destructor decreases the reference counter on the frame data (CAldeaBaseFrame::m_pFrameData). When this counter reaches the zero value, data are deleted because this indicates that no CAldeaFrame object references this data.

See also

CAldeaFrame::CAldeaFrame, CAldeaBaseFrame::m_pFrameData


CAldeaFrame::Clone

Duplication of a frame

CAldeaFrame CAldeaFrame::Clone();

Return value

A CAldeaFrame object, superficial copy of the current object.

Description

This functions performs a superficial copy of a frame. It enumerates all the slots of the object and then copies each of them into the returned CAldeaFrame object. In other words, if one of the slots  contains a CAldeaArray, CAldeaBuffer or CAldeaFrame object, this object will be copied and not its contents. Then, the original and copy  object slots will reference the same frame data.

To make a complete copy, use the CAldeaFrame::DeepClone member function.

Example

CAldeaFrame oAldeaFrame1;
CAldeaArray oAldeaSubArray1;
CAldeaBuffer oAldeaSubBuffer1;
CAldeaFrame oAldeaSubFrame1;
oAldeaFrame1[_T("Integer")] = (long)12;
oAldeaFrame1[_T("AldeaSubArray1")] = oAldeaSubArray1;
oAldeaFrame1[_T("AldeaSubBuffer1")] = oAldeaSubBuffer1;
oAldeaFrame1[_T("AldeaSubFrame1")] = oAldeaSubFrame1;
CAldeaFrame oAldeaFrame2 = oAldeaFrame1.Clone();
//	oAldeaFrame2 have four slots of same name as those of
//	oAldeaFrame1. Except the slot "Integer", the others slots
//	share their data with the slots of same name in oAldeaFrame1

See also

CAldeaFrame::DeepClone


CAldeaFrame::DeepClone

Complete duplication of a frame and all its slots

CAldeaFrame CAldeaFrame::DeepClone();

Return value

A CAldeaFrame object complete copy of the current object.

Description

This function performs a complete copy of a frame. All the frame slots are copied, the simples types (asLong, asString,...) like the complex types (asBuffer, asFrame and asArray). For example, if a slot contains a CAldeaFrame object , its copy does not contain the same frame data, but an integral copy of the frame data.

To make a superficial copy, use the CAldeaFrame::Clone member function.

Example

CAldeaFrame oAldeaFrame1;
CAldeaArray oAldeaSubArray1;
CAldeaBuffer oAldeaSubBuffer1;
CAldeaFrame oAldeaSubFrame1;
oAldeaFrame1[_T("Integer")] = (long)12;
oAldeaFrame1[_T("AldeaSubArray1")] = oAldeaSubArray1;
oAldeaFrame1[_T("AldeaSubBuffer1")] = oAldeaSubBuffer1;
oAldeaFrame1[_T("AldeaSubFrame1")] = oAldeaSubFrame1;
CAldeaFrame oAldeaFrame2 = oAldeaFrame1.DeepClone();
//	oAldeaFrame2 have four slots of same name as those from
//	oAldeaFrame1, the slots are totally copied, they do not
//	share their data with the slots of same name in oAldeaFrame1

See also

CAldeaFrame::Clone


CAldeaFrame::MakeSlotArray

Padding of an array with the frame slot names

AldeaError CAldeaFrame::MakeSlotArray(CAldeaArray &oArray);

Parameters

oArray	An array in which are put the frame slots.

Return value

An error code of AldeaError type.

Description

This function empties the oArray parameter array. Then, it adds the strings containing the names of the slot of the  frame in oArray. It is helpful when you want to make a loop on all the frame elements.


CAldeaObject
CAldeaObject class

The CAldeaObject class is the base class of most objects of the AGcAPI programming interface.

Its principal function is to incorporate an error management mechanism during the construction of a derived class with the member functions CAldeaObject::GetError, CAldeaObject::HasNoError and CAldeaObject::SetError.

See also

Hierarchy Chart


CAldeaObject::CAldeaObject

Constructor

CAldeaObject::CAldeaObject();

Description

This constructor is called by default by all the derived objects.

During the construction, the internal error variable (m_nError) is initialized to aeNoError.

See also

CAldeaObject::GetError, CAldeaObject::HasNoError, CAldeaObject::SetError


CAldeaObject::~CAldeaObject

Destructor

virtual CAldeaObject::~CAldeaObject();

Description

As the CAldeaObject destructor is virtual, the destructor of each CAldeaObject derived class will also be virtual.


CAldeaObject::GetError

Returns the object error

AldeaError GetError();

Return value

An error code of type AldeaError

aeNoError	if there is no error in the object.

Description

Returns the error value. This can be of any value of type AldeaError. At the construction of a CAldeaObject, the error is initialized to aeNoError. The function CAldeaObject::SetError allows you to change the error value.

Example

CAldeaObject oAldeaObject;
if (oAldeaObject.HasNoError())
return oAldeaObject.GetError();

See also

CAldeaObject::HasNoError, CAldeaObject::SetError


CAldeaObject::HasNoError

Indicating if the object has an error

BOOL HasNoError() const;

Return values

TRUE if there was no error, FALSE if there was an error.

Description

Indicates if the internal error variable is at aeNoError or not.

Example

CAldeaObject oAldeaObject(NULL);
if (oAldeaObject.HasNoError())
return;

See also

CAldeaObject::GetError, CAldeaObject::SetError


CAldeaObject::SetError

Positioning the internal error variable

void SetError(AldeaError nError) ;

Parameters

nError	an error value (or of state) of the type AldeaError  to put in the internal error variable.

Description

Change the internal error variable value. This function is principally used with the functions CAldeaObject::GetError and CAldeaObject::HasNoError to know if the object construction was correctly made.

Example

class CDerivedAldeaObject : public CAldeaObject
{
public :
CDerivedAldeaObject(void pPtr)
:	m_pPtr(pPtr)
{
if (pPtr == NULL)
SetError(aeGenericError) ;	//	After le constructor,
//	we interrogate the object with HasNoError or GetError
}
};

See also

CAldeaObject::GetError, CAldeaObject::HasNoError


CAldeaProtocol

You not need to use the class directly. The only useful class is CAldeaProtocolClientPC.

See also

Hierarchy Chart


CAldeaProtocol members

Member functions

CAldeaProtocol::GetHostAddress

CAldeaProtocol::GetHostName

CAldeaProtocolClient::GetPeer

CAldeaProtocol::GetPort

CAldeaProtocol::GetTimeout

CAldeaProtocol::IsOpen

CAldeaProtocolClient::SetPeer

CAldeaProtocol::SetPort

CAldeaProtocol::SetServer

CAldeaProtocol::SetTimeout


CAldeaProtocol::GetHostAddress

Returns the IP address of the TCP/IP host

CAldeaString CAldeaProtocol::GetHostAddress();

Return value

A string containing the IP address of the machine.

Description

Returns the IP address of the machine on which the program is running in a string forms. The address is in "aaa.bbb.ccc.ddd" forms. Warning, in the case of a machine with several IP addresses, it is not possible to know which address will be returned. If the machine is connected temporarily to the Internet by RAS (Remote Access Service), the returned address is usually the address attributed by the RAS server.

Example

CAldeaString sAdresseMachine = oProtocolClientPC.GetHostAddress();

See also

CAldeaProtocol::GetHostName


CAldeaProtocol::GetHostName

Returns the TCP/IP host DNS name

CAldeaString CAldeaProtocol::GetHostName();

Return value

A string containing the DNS name of the machine.

Description

Return the DNS name of the machine which is running the program in a string forms.

Example

CAldeaString sHostName = oProtocolClientPC.GetHostName();

See also

CAldeaProtocol::GetHostAddress


CAldeaProtocol::GetPeer

Returns the peer(s) name(s)

CAldeaString CAldeaProtocol::GetPeer();

Return value

A string containing the peer(s) name.

Description

Allow to know the ID of the peer(s). If there are several peers (asynchronous mode), they are divided by ";".

Example

CAldeaString sPeer = oAldeaProtocolClientPC.GetPeer();

See also

CAldeaProtocol::SetPeer


CAldeaProtocol::GetPort

Returns the port number

CAldeaString CAldeaProtocol::GetPort();

Return value

A string containing the TCP/IP port number.

Description

To return the TCP/IP port number chosen for the next connection. If a call was made to CAldeaProtocol::SetPort  after the beginning of the current connection, the returned port number will not necessarily be the port number of the connection.

Example

CAldeaString sPort = oProtocolClientPC.GetPort();

See also

CAldeaProtocol::SetPort, CAldeaProtocol::SetServer


CAldeaProtocol::GetTimeout

Returns the timeout value

long CAldeaProtocol::GetTimeout() const;

Return value

A long integer equal to the timeout value or -1 if an error occurred during the access to this value.

Description

Return the timeout value.

If an error occurred during the timeout access, the function returns the -1 value.

Example

long nCurrentTimeout = oProtocolClientPC.GetTimeout();

See also

CAldeaProtocol::SetTimeout


CAldeaProtocol::IsOpen

Testing if the connection is opened

BOOL CAldeaProtocol::IsOpen(BOOL bCheck);

Parameters

bCheck	Test the connection with the server if bcheck is at TRUE,  does not test if it is at FALSE.

Return value

A value of AldeaError type :

aeNoError	the connection is opened.

aeChannelBroken	the connection is closed.

Description

To test if the connection is opened. If bCheck is at FALSE, the state is tested in local, or otherwise the connection with the server is tested. Please note that in the last case the running time is longer, especially when communicating over the Internet.

Example

if (oProtocolClientPC.IsOpen(FALSE))
{
/* CONNECTION OPENED IN OUR SIDE (CLIENT) */
if (oProtocolClientPC.IsOpen(TRUE))
{
/* CONNECTION OPENDED AND TESTED TO PEER */
}
else
{
/* CONNECTION WAS CLOSED WITH THE SERVER */
}
}
else
{
/* CONNECTION IS CLOSED */
}

See also

CAldeaProtocolClientPC::Ping


CAldeaProtocol::SetPeer

Changing the peer (asynchronous mode only)

AldeaError SetPeer(const CAldeaString& sPeer);

Return value

A value of the type AldeaError:

aeNoError	The change is done.

aeModeIsNotAsync	The change cannot be done because the connection is not in asynchronous mode.

Parameters

sPeer	String containing the name(s) of the peer(s) with whom you want to communicate.

Description

When the connection is in asynchronous mode, it is possible to change the peer with this function. It is also possible to specify several peers. Those must be separate by ";". The star character (*) to specify several peers (the string "*" indicates we want to communicate with all the peers, "A*" indicates we want to communicate with all the peers whose name begin by A). To send or receive data to peers whose name begin by Client and to peer Application, the "Client*;Application" string must be provided (without putting a space before and after the ";").

In the case of a synchronous connection, to change the peer, you must close the current connection and to open another. The peer is designated in the call to CAldeaProtocolClientPC::Open.

Example

oAldeaProtocolClientPC.SetPeer("Client*;Application");

See also

CAldeaProtocol::GetPeer


CAldeaProtocol::SetPort

Defining the port to use for the connection

void CAldeaProtocol::SetPort(CAldeaString sPort);

Parameters

sPort	A string containing the TCP/IP port number to use for the connection.

Description

This function allows you to specify another port other than the default port.

Warning, it is possible to change the port while a connection is opening. This cause any change on the current connection, but if you call the GetPort function, the returned port number will be different from that of the connection.

Example

oProtocolClientPC.SetPort("23789");

See also

CAldeaProtocol::GetPort


CAldeaProtocol::SetServer

Changing the Active Gateway Server Address

CAldeaProtocol::SetServer(CAldeaString sServer);

Parameters

sServer	The IP address or DNS name of the server to contact for the next connection.

Description

This function changes the Active Gateway server address to contact for the next connection. The call to this function causes no changes to an established connection.

Example

oProtocolClientPC1.SetServer("activegateway.aldea-interactive.com");
oProtocolClientPC1.SetServer("127.0.0.1");

See also

CAldeaProtocol::SetPort


CAldeaProtocol::SetTimeout

Set the Timeout Value

long CAldeaProtocol::SetTimeout( const long nTimeout);

Parameters

nTimeout	The new timeout value in milliseconds.

Return value

A long integer equal to the old timeout value or -1 if the timeout can't be changed.

Description

This function changes the timeout value and returns its old value. The timeout value must be a positive or null number. If the nTimeout parameter is negative, the timeout value is not modified.

If an error occurred during the change of the timeout value, the function returns -1.

Example

long nOldTimeout = oProtocolClientPC.SetTimeout(60000);
/* OPERATIONS DE COMMUNICATION */
/* ... */
oProtocolClientPC.SetTimeout(nOldTimeout);

See also

CAldeaProtocol::GetTimeout


CAldeaProtocolClient

CAldeaProtocolClient inherits from CAldeaProtocol.

You do not need directly to use this class. Only the CAldeaProtocolClientPC class is useful.

See also

Hierarchy Chart


CAldeaProtocolClientPC

CAldeaProtocolClientPC inherits from CAldeaProtocolClient.

It is the only communication class you need. The CAldeaProtocol and CAldeaProtocolClient base class are abstract classes you must not use. If some member functions of these classes are documented, it is because the CAldeaProtocolClientPC class inherits from it.

In the general case of a synchronous connection, the CAldeaProtocolClientPC object is very easy to use. To make a connection with a peer, it is enough to :

•	create a CAldeaProtocolClientPC object;

•	call the CAldeaProtocolClientPC::Open opening connection function ;

•	exchange CAldeaFrame objects with the peer with the CAldeaProtocolClientPC::Send and CAldeaProtocolClientPC::Recv functions;

•	close the connection with the CAldeaProtocolClientPC::Close function;

•	and destroy the CAldeaProtocolClientPC object.

See also

Hierarchy Chart


CAldeaProtocolClientPC members

Member functions

CAldeaProtocolClientPC::CAldeaProtocolClientPC

CAldeaProtocolClientPC::~CAldeaProtocolClientPC

CAldeaProtocolClientPC::Close

CAldeaProtocolClientPC::Open

CAldeaProtocolClientPC::Ping

CAldeaProtocolClientPC::Recv

CAldeaProtocolClientPC::Send


CAldeaProtocolClientPC::CAldeaProtocolClientPC

Constructor

CAldeaProtocolClientPC::CAldeaProtocolClientPC(	LPCTSTR	pServerName,
LPCTSTR	pPortName,
LPCTSTR	pClientName,
LPCTSTR	pPeerName,
acChannelType	eChannelType,
acLinkMode	eLinkMode = ac_lmSyncWithoutConf);

Parameters

pServerName	Active Gateway server address ( IP address or DNS name).

pPortName	TCP/IP port to use for the connection.

pClientName	Your name for the client.

pPeerName	Name of the peer (there can be several during an asynchronous connection.  See CAldeaProtocol::SetPeer).

eChannelType	Communication channel type, a value of acChannelType type, actually only the ac_ctTCPIPSocket type is used.

eLinkMode	Connection type, a value of acLinkMode type, by default ac_lmSyncWithoutConf.

Description

Creates a CAldeaProtocolClientPC object. This object allows to communicate with peers (pPeerName) by the intermediary of a server (pServerName).

Example

CAldeaProtocolClientPC oAldeaProtocolClientPC(	"127.0.0.1",
"23789",
"MyName",
"Client*;MyFriend",
ac_ctTCPIPSocket,
ac_lmAsync);

See also

CAldeaProtocolClientPC::~CAldeaProtocolClientPC, CAldeaProtocolClientPC::Open


CAldeaProtocolClientPC::~CAldeaProtocolClientPC

Destructor

CAldeaProtocolClientPC::~CAldeaProtocolClientPC();

Description

Delete the CAldeaProtocolClientPC object. If a connection is still opened, it is automatically closed by a call to CAldeaProtocolClientPC::Close.

See also

CAldeaProtocolClientPC::CAldeaProtocolClientPC


CAldeaProtocolClientPC::Close

Closing a connection

virtual void Close();

Description

To close a connection opened with CAldeaProtocolClientPC::Open. This function is automatically called by the destructor of the object, if the connection is still opened.

See also

CAldeaProtocolClientPC::~CAldeaProtocolClientPC, CAldeaProtocolClientPC::Open


CAldeaProtocolClientPC::Open

Opening a connection

virtual AldeaError CAldeaProtocolClientPC::Open(	long	nTimeout,
LPCTSTR	pClientName	= NULL,
LPCTSTR	pServer	= NULL,
LPCTSTR	pPort	= NULL,
acLinkMode *pLinkMode 	= NULL);

Return value

The aeNoError value if the opening is correct or another value of type AldeaError in case of error.

Parameters

nTimeout	Maximum waiting delay value during an operation. Expressed in milliseconds.

pClientName	(optional) Your Name for the client .

pServer	(optional) String containing the server address. It can be a standard IP address (ex. : 127.0.0.1) or a DNS name (ex. : activegateway.aldea-interactive.com).

pPort	(optional) connection port (TCP/IP port in the case of a ac_ctTCPIPSocket connection).

pLinkMode	(optional) Connection type, acLinkMode value.

Description

Opening of a connection via Active Gateway Server.

It is possible to specify the Active Gateway server address (pServer) from which you want to pass to establish the communication. In this case, the address known by the creation of this object is ignored.

This makes it possible to specify again your name (pClientName), the server address (pServer), the port (pPort) and the connection type (pLinkMode) allow to have a new connection without having to destroy and create again a CAldeaProtocolClientPC object.

Example

CAldeaProtocolClientPC oAldeaProtocolClientPC(	"127.0.0.1",
"23789",
"MyName",
"Client*;MyFriend",
ac_ctTCPIPSocket,
ac_lmAsync);

oAldeaProtocolClientPC.Open(10000);

...

oAldeaProtocolClientPC.Close();

oAldeaProtocolClientPC.Open(	10000,
"MyOtherName",
"activegateway.aldea-interactive.com");

See also

CAldeaProtocolClientPC::CAldeaProtocolClientPC, CAldeaProtocolClientPC::Close


CAldeaProtocolClientPC::Ping

Communication test

AldeaError Ping( long *pTime);

Return value

A value of the type AldeaError.

Parameter

pTime	Pointer to a long integer. Will contain the time of the test realization in milliseconds if there was no error.

Description

This function tests the communication with the peer like the ping utility of the TCP/IP protocol. If the connection is still open between the client and its peer (return value equal to aeNoError), the long integer pointed by pTime contains the above time of the test.

Example

long nDelay;
AldeaError nError = oAldeaProtocolClientPC.Ping(&nDelay);
if (nError == aeNoError)
{
// the connection is open and the test takes nDelay milliseconds.
}

See also

CAldeaProtocol::IsOpen


CAldeaProtocolClientPC::Recv

Receiving a frame

virtual AldeaError CAldeaProtocolClientPC::Recv(	CAldeaFrame &	oFrame,
LPCTSTR	pPeerPath = NULL);

Parameters

oFrame	The CAldeaFrame object in which the frame is received.

pPeerPath	Name of the peer(s) from who the frame is waiting, in the case of a synchronous connection.

Return value

A value of AldeaError type :

aeNoError	a frame was received.

aeTimeout	No frame was received during the wanted time.

Or another value in the error case.

Description

Receive a frame.

Only in the asynchronous communication case, it is possible to specify the peer(s) from which a frame is expected. Even if you specify several peer(s), you receive only one frame in maximum.

If at the end of the timeout specified at the creation of the object or with the CProtocol::SetTimout function, no frame was received, the function returns the  aeTimeout error.

Example

AldeaError nError;
CAldeaFrame oAldeaFrame;
//	waiting loop of frame from any peer
//	warning you escape from this loop when receiving a frame
do
{

nError = oAldeaProtocolClientPC.Recv(oAldeaFrame,"*");

} while (nError == aeTimeout)

See also

CAldeaProtocolClientPC::Send


CAldeaProtocolClientPC::Send

Sending a frame

virtual AldeaError CAldeaProtocolClientPC::Send(	const CAldeaFrame &	oFrame,
LPCTSTR	pPeerPath = NULL);

Return value

A value of the type AldeaError.

aeNoError	the frame is correctly sent.

Parameters

oFrame	A CAldeaFrame object to send.

pPeerPath	name of the peer(s) to who the frame is destined in the case of asynchronous communication.

Description

This function send a frame.

Only, in the case of an asynchronous communication, it is possible to specify the peer(s) which will receive of a frame. If you specify several peers, each will receive a copy of the frame, but the frame is sent only once.

Example

//	Sending of a frame for all the peers whose names begin by Aldea
oAldeaProtocolClientPC.Send(oAldeaFrame,"Aldea*");

see also

CAldeaProtocolClientPC::Recv


CAldeaSlot

CAldeaSlot inherits from CAldeaObject. You cannot create CAldeaSlot objects. But, it is possible to handle CaldeaSlot objects created in frames or arrays.

In the following example, we access directly to one of the frame slots to modify it :

CAldeaFrame oAldeaFrame;
CAldeaArray oAldeaArray;
oAldeaArray.AddArraySlot(_T("Premier élément"))
oAldeaFrame[_T("Slot1")].SetNil();
//	the Slot1 of the frame oAldeaFrame contains a boolean at Nil (FALSE).

In the following example, the CAldeaSlot object is not handled directly. It is copied by reference. Then, when we change its value, those of the frame slot is not modified.

CAldeaFrame oAldeaFrame;
oAldeaFrame[_T("Slot1")] = (long)123;
CAldeaSlot& oAldeaSlot = oAldeaFrame[_T("Slot1")];
oAldeaSlot.SetNil();
//	the slot Slot1 of the frame oAldeaFrame contains always the value 123.
//	The oAldeaSlot object contains a boolean at Nil (FALSE).

When a CAldeaSlot receives a CAldeaBuffer, CAldeaFrame or CAldeaArray object, it runs exactly as if it were one of these objects as it increases the reference counter and shares the data of these objects.

CAldeaFrame oAldeaFrame1;
CAldeaFrame oAldeaFrame2;
oAldeaFrame1[_T("Slot1")] = oAldeaFrame2;
CAldeaSlot& oAldeaSlot = oAldeaFrame[_T("Slot1")];
CAldeaFrame oAldeaFrame3 = oAldeaSlot;	//	oAldeaFrame2 and oAldeaFrame3 share
//	the same frame data (slot and values)
oAldeaFrame3[_T("Slot2")]= (long)12;
long nValue = (long)oAldeaFrame2[_T("Slot2")];	//	nValue have a value of 12
//	the slot Slot2 exist in oAldeaFrame2
//	because oAldeaFrame2 and oAldeaFrame3
//	represent the same frame.

For more details, refer to the CAldeaBaseFrame and CAldeaBuffer introductions.

See also

Hierarchy Chart


CAldeaSlot members

Member functions

CAldeaSlot::CAldeaSlot

CAldeaSlot::~CAldeaSlot

CAldeaSlot::Compare

CAldeaSlot::ClassOf

CAldeaSlot::GetClassStr

CAldeaSlot::GetValueStr

CAldeaSlot::GetTypeStr

CAldeaSlot::Is<type>

CAldeaSlot::SetEmptyArray

CAldeaSlot::SetEmptyFrame

CAldeaSlot::SetNil

CAldeaSlot::SetTrue

Member operators

CAldeaSlot::operator=

CAldeaSlot::operator <comp>

CAldeaSlot::operator <type>()


CAldeaSlot::CAldeaSlot

Constructor by reference.

CAldeaSlot::CAldeaSlot(const CAldeaSlot& oAldeaSlot);

Description

You cannot create CAldeaSlot object in any other way, other than by reference.

See also

CAldeaSlot, CAldeaBaseFrame::operator[ ]


CAldeaSlot::~CAldeaSlot

Destructor (protected)

CAldeaSlot::~CAldeaSlot();

Description

Destructor of the CAldeaSlot object. You do not need to use it because you handle the object only by reference.

See also

CAldeaSlot::CAldeaSlot


CAldeaSlot::ClassOf

Returns the slot type

asType ClassOf() const;

Return value

One value from the asType enumeration.

Description

Returns the CAldeaSlot type. This can be any value from the asType enumeration.

Example

oAldeaFrame[_T("Slot1")] = (long)123;
CAldeaSlot& oAldeaSlot = oAldeaFrame[_T("Slot1")];
asType nType = oAldeaSlot.ClassOf();
//	nType contains the fiLong value

See also

asType


CAldeaSlot::Compare

Comparison of slots

long Compare( const CAldeaSlot& oValue);

Parameters

oValue	A CAldeaSlot object with which the current object is compared.

Return value

A long integer equal to  :
-1 if the current object is inferior to oValue,
0 if the current object is equal to oValue,
1 if the current object is superior to oValue.

Description

This function compares two CAldeaSlot objects. Warning, the objects must have the same type, otherwise a CAldeaException exception is thrown with aeTypeMismatch value.

By using this function, you can use overloaded comparison operators for CAldeaSlot objects.

Example

oAldeaFrame[_T("Slot1")] = (long)123;
oAldeaFrame[_T("Slot2")] = (long)124;
oAldeaFrame[_T("Slot3")] = (long)123;
oAldeaFrame[_T("Slot4")] = (long)122;
oAldeaFrame[_T("Slot5")] = _T("Hello");
CAldeaSlot& oAldeaSlot1 = oAldeaFrame[_T("Slot1")];
CAldeaSlot& oAldeaSlot2 = oAldeaFrame[_T("Slot2")];
CAldeaSlot& oAldeaSlot3 = oAldeaFrame[_T("Slot3")];
CAldeaSlot& oAldeaSlot4 = oAldeaFrame[_T("Slot4")];
CAldeaSlot& oAldeaSlot5 = oAldeaFrame[_T("Slot5")];
long nResult;
nResult = oAldeaSlot1.Compare(oAldeaSlot2)	//	nResult equal to -1
nResult = oAldeaSlot1.Compare(oAldeaSlot3)	//	nResult equal to 0
nResult = oAldeaSlot1.Compare(oAldeaSlot4)	//	nResult equal to 1
nResult = oAldeaSlot1.Compare(oAldeaSlot5)	//	An exception is thrown

See also

CAldeaSlot::operator <comp>


CAldeaSlot::GetClassStr

Representation of a slot type in string forms

CAldeaString GetClassStr() const;

Return value

A string containing the name of the slot type.

Description

This function returns the slot type in string forms. This name is built from the asType enumeration values, from which the "as" prefix is removed.

Warning, this function is an aid to application development using AGcAPI. These values are not significant for the final user.

See also

asType, GetTypeStr


CAldeaSlot::GetValueStr

Representation of the value in string forms

void GetValueStr(CAldeaString& sValeur) const;

Parameters

sValeur	CAldeaString object which will contain the slot value.

Description

Returns a representation of the slot value. This representation is not localised in a local language. For example, if the slot contains a date, the returned value will be in the American form "12/31/97" (for 31 December 1997).

Warning, this function is an aid to application development using AGcAPI. These values are not significant for the final user.


CAldeaSlot::GetTypeStr

Short representation of a type slot in string forms

LPCTSTR GetTypeStr() const;

Return value

A string containing the abbreviation of the slot type.

Description

This function returns an abbreviation of the slot type in string forms. The return values are defined in the include file AGCore.h by types representation macros prefixed by kStr (ex. : kStrString).

Warning, this function is an aid to application development using AGcAPI. These values are not significant for the final user.

Example

oAldeaFrame[_T("Slot1")] = (long)123;
CAldeaSlot& oAldeaSlot1 = oAldeaFrame[_T("Slot1")];
LPCTSTR sType = oAldeaSlot1.GetTypeStr();
//	sType contains a value of kStrLong : "LNG"

See also

asType, GetClassStr


CAldeaSlot::Is<type>

Test of the slot type

BOOL CAldeaSlot::IsArray()	const;
BOOL CAldeaSlot::IsBool()	const;
BOOL CAldeaSlot::IsBuff()	const;
BOOL CAldeaSlot::IsByte()	const;
BOOL CAldeaSlot::IsDateTime()	const;
BOOL CAldeaSlot::IsDouble()	const;
BOOL CAldeaSlot::IsFloat()	const;
BOOL CAldeaSlot::IsFrame()	const;
BOOL CAldeaSlot::IsLong()	const;
BOOL CAldeaSlot::IsNil()	const;
BOOL CAldeaSlot::IsShort()	const;
BOOL CAldeaSlot::IsString()	const;
BOOL CAldeaSlot::IsSymbol()	const;
BOOL CAldeaSlot::IsTrue()	const;

Return value

A boolean is equal to :
   TRUE if the slot is of the correct type,
   FALSE if the slot of the incorrect type.

Description

This function allows you to test the CAldeaSlot object type.

Example

oAldeaFrame[_T("Slot1")] = (long)123;
CAldeaSlot& oAldeaSlot1 = oAldeaFrame[_T("Slot1")];
oAldeaSlot1.IsLong();	//	Return TRUE
oAldeaSlot1.IsString();	//	Return FALSE

See also

CAldeaSlot::SetNil, CAldeaSlot::SetTrue, asType


CAldeaSlot::SetEmptyArray

The slot takes the value of an empty array

void CAldeaSlot::SetEmptyArray();

Description

An empty array is assigned to the slot.

Example

oAldeaFrame[_T("Slot1")] = (long)123;
oAldeaFrame[_T("Slot2")] = oAldeaArray2;
CAldeaSlot& oAldeaSlot1 = oAldeaFrame[_T("Slot1")];
CAldeaSlot& oAldeaSlot2 = oAldeaFrame[_T("Slot2")];
oAldeaSlot1.SetEmptyArray();
oAldeaSlot2.SetEmptyArray();	//	oAldeaArray2 keep unchanged,
//	but is not referenced by the slot

See also

CAldeaSlot::SetEmptyFrame


CAldeaSlot::SetEmptyFrame

the slot takes the value of an empty frame

void CAldeaSlot::SetEmptyFrame();

Description

An empty frame is assigned to the slot.

Example

oAldeaFrame[_T("Slot1")] = (long)123;
oAldeaFrame[_T("Slot2")] = oAldeaFrame2;
CAldeaSlot& oAldeaSlot1 = oAldeaFrame[_T("Slot1")];
CAldeaSlot& oAldeaSlot2 = oAldeaFrame[_T("Slot2")];
oAldeaSlot1.SetEmptyFrame();
oAldeaSlot2.SetEmptyFrame();	//	oAldeaFrame2 keep unchanged,
//	but is not referenced by the slot

See also

CAldeaSlot::SetEmptyArray


CAldeaSlot::SetNil

The slot takes the Nil (FALSE) value

void CAldeaSlot::SetNil();

Description

To change the slot value into the Nil (asBool type) value.

Example

oAldeaFrame[_T("Slot1")] = (long)123;
CAldeaSlot& oAldeaSlot1 = oAldeaFrame[_T("Slot1")];
oAldeaSlot1.SetNil();

See also

CAldeaSlot::IsNil, CAldeaSlot::IsTrue, CAldeaSlot::SetTrue


CAldeaSlot::SetTrue

The slot takes the True (TRUE) value

void CAldeaSlot::SetTrue();

Description

To change the slot value into the True (asBool type) value.

Example

oAldeaFrame[_T("Slot1")] = (long)123;
CAldeaSlot& oAldeaSlot1 = oAldeaFrame[_T("Slot1")];
oAldeaSlot1.SetTrue();

See also

CAldeaSlot::IsNil, CAldeaSlot::IsTrue, CAldeaSlot::SetNil


CAldeaSlot::operator=

Assignment

const CAldeaSlot& CAldeaSlot::operator=(LPCTSTR	pValue);
const CAldeaSlot& CAldeaSlot::operator=(const CAldeaString&	sValue);
const CAldeaSlot& CAldeaSlot::operator=(BOOL	bValue);
const CAldeaSlot& CAldeaSlot::operator=(unsigned char	nValue);
const CAldeaSlot& CAldeaSlot::operator=(short	nValue);
const CAldeaSlot& CAldeaSlot::operator=(long	nValue);
const CAldeaSlot& CAldeaSlot::operator=(float	fValue);
const CAldeaSlot& CAldeaSlot::operator=(double	fValue);
const CAldeaSlot& CAldeaSlot::operator=(const CAldeaFrame&	oValue);
const CAldeaSlot& CAldeaSlot::operator=(const CAldeaArray&	oValue);
const CAldeaSlot& CAldeaSlot::operator=(const COleDateTime&	oValue);
const CAldeaSlot& CAldeaSlot::operator=(const SYSTEMTIME&	oValue);
const CAldeaSlot& CAldeaSlot::operator=(const CAldeaDateTime&	oValue);
const CAldeaSlot& CAldeaSlot::operator=(const CAldeaBuffer&	oValue);
const CAldeaSlot& CAldeaSlot::operator=(const VARIANT&	oValue);
const CAldeaSlot& CAldeaSlot::operator=(const CAldeaSlot&	oValue);

Parameters

The new slot value.

Return value

A reference on the CAldeaSlot object itself.

Description

This operator allows you to assign the new value passed in parameter to the CAldeaSlot object.

Warning

When you handle numerical types, do not forget to add explicit conversion operators to be sure of the operation you want to perform.When you want to recuperate the slot value, if the slot type is not the wanted type, a CAldeaException exception is thrown with the aeTypeMismatch value (see CAldeaSlot::operator <type>()).

Example

oAldeaFrame[_T("Slot1")] = (long)123;	//	First assignment
CAldeaSlot& oAldeaSlot1 = oAldeaFrame[_T("Slot1")];
oAldeaSlot1 = (long)124;	//	Second assignment
short nShortValue = oAldeaFrame[_T("Slot1")];	//	Throw an exception: the wanted type
//	is asShort and the slot type is asLong.

See also

CAldeaSlot::operator <type>


CAldeaSlot::operator <comp>

Comparison of slots

BOOL operator==(	const CAldeaSlot& oValue);
BOOL operator!=(	const CAldeaSlot& oValue);
BOOL operator<(	const CAldeaSlot& oValue);
BOOL operator<=(	const CAldeaSlot& oValue);
BOOL operator>(	const CAldeaSlot& oValue);
BOOL operator>=(	const CAldeaSlot& oValue);

Parameters

oValue	A CAldeaSlot object with which the current object is compared.

Return value

A boolean isequal to  :
     TRUE: the comparison with oValue is true,
     FALSE: the comparison with the oValue is false.

Description

These operators allow you to facilitate the comparison operations between slots.

Warning, they are based on the CAldeaSlot::Compare function. This is why they throw a CAldeaException exception if oValue does not have the same type as the current object.

See also

CAldeaSlot::Compare, CAldeaException


CAldeaSlot::operator <type>()

Explicit conversion of type

CAldeaSlot::operator CAldeaString()	const;
CAldeaSlot::operator unsigned char()	const;
CAldeaSlot::operator short()	const;
CAldeaSlot::operator BOOL()	const;
CAldeaSlot::operator long()	const;
CAldeaSlot::operator float()	const;
CAldeaSlot::operator double()	const;
CAldeaSlot::operator CAldeaBuffer()	const;
CAldeaSlot::operator CAldeaFrame()	const;
CAldeaSlot::operator CAldeaArray()	const;
CAldeaSlot::operator COleDateTime()	const;
CAldeaSlot::operator SYSTEMTIME()	const;
CAldeaSlot::operator CAldeaDateTime()	const;
CAldeaSlot::operator VARIANT()	const;

Return value

The slot value in the chosen type.

Description

These functions return the slot value in the chosen type.

Warning

If the slot type is not the chosen type (for example CAldeaSlot::operator CAldeaString() on an asFrame slot type or CAldeaSlot::operator short() on an asLong slot type) a CAldeaException exception is thrown with the aeTypeMismatch value.

Example

oAldeaFrame[_T("Slot1")] = (long)123;
CAldeaSlot& oAldeaSlot1 = oAldeaFrame[_T("Slot1")];
long nValue = (long)oAldeaSlot1;
double fValue = (long)oAldeaSlot1;	// Assignment via a long to double conversion
// No exception
double fValue = oAldeaSlot1;	// Assignment via a conversion to double by default
// THROW AN EXCEPTION

See also

CAldeaSlot::operator=, CAldeaException


CAldeaString

CAldeaString does not have a base class.

The CAldeaString class allows you to handle strings and put them into frames.

If you use the Microsoft Foundation Classes or any other Class Library, this object is not intended to replace the main string management object (CString for the MFC). It is useful when performing basic operations with string or when retrieving strings from frames.


CAldeaString members

Member Functions

CAldeaString::CAldeaString

CAldeaString::~CAldeaString

CAldeaString::Mid

CAldeaString::GetLength

CAldeaString::IsEmpty

CAldeaString::Empty

CAldeaString::Compare

Member operators

CAldeaString::operator =

CAldeaString::operator +=

CAldeaString::operator LPCTSTR


CAldeaString::CAldeaString

Constructor

CAldeaString::CAldeaString();
CAldeaString::CAldeaString(const CAldeaString&	oAldeaString);
CAldeaString::CAldeaString(LPCTSTR	sStringT);
CAldeaString::CAldeaString(LPCWSTR	sStringW);

Parameters

oAldeaString	An existing CAldeaString object.

sStringT	An existing LPCTSTR string.

sStringW	An existing LPCWSTR string.

Description

Creates a new CAldeaString object.

The first constructor creates an empty CAldeaString object.

The others constructors (copy constructors) create a new CAldeaString object from the data of the existing object passed in parameter. It can be another CAldeaString object or a string of type LPCTSTR or LPCWSTR.

Example

CAldeaString oAldeaString1(_T("Hello"));
CAldeaString oAldeaString2(oAldeaString1);

See Also

CAldeaString::~CAldeaString


CAldeaString::~CAldeaString

Destructor

virtual CAldeaString::~CAldeaString();

Description

Virtual destructor of the CAldeaString class.

See also

CAldeaString::CAldeaString


CAldeaString::Mid

Extract of characters from the object

CAldeaString CAldeaString::Mid(int nFirst, int nCount) const;

Parameters

nFirst	Index of the first character in the object from which the string is to be extracted.

nCount	Number of characters you want to extract from the object beginning in nFirst.

Return value

A CAldeaString object, partial copy of the current object.

Description

This function returns a partial copy of a CAldeaString. The returned object will contain a string beginning by the character at nFirst position and having nCount characters.

Example

CAldeaString oAldeaString1(_T("abcdef"));
CAldeaString oAldeaString2 = oAldeaString1.Mid( 2, 3 );
// oAldeaString2 contains "cde"


CAldeaString::GetLength

Returns the length of the object string

long CAldeaString::GetLength();

Return Value

A long integer containing the length of the object string.

Description

This function returns the length of the object string.

Example

CAldeaString oString(_T("abcdef"));
long nLength = oString.GetLength();	//	nLength is equal to 6


CAldeaString::IsEmpty

To test if the object is empty

BOOL CAldeaString::IsEmpty() const;

Return values

TRUE if the object contains an empty string; otherwise FALSE.

Description

This function allows you to test if the object contains an empty string (length = 0).


CAldeaString::Empty

Emptying the object

void CAldeaString::Empty();

Description

This function empties the CAldeaString object.  It frees memory as needed.

Example

CAldeaString oString(_T("abcdef"));
oString.Empty();


CAldeaString::Compare

Comparing the object with a LPCTSTR string

int CAldeaString::Compare(LPCTSTR pString) const;

Parameters

pString	String to compare with the object.

Return values

An integer taking three different values :

< 0 if the CAldeaString object is less than pString;

0 if the strings are identical;

> 0 if the CAldeaString object is greater than pString.

Description

This function compares a CAldeaString object with a LPCTSTR string. The function returns an integer. It takes the value 0 if the strings are identical, a value <0 if the CAldeaString object is less than pString and a value >0 if the object is greater than pString.

Example

CAldeaString oString( _T("abcdef") );
oString.Compare((LPCTSTR) _T("abcdef"));	// True


CAldeaString::Operator =

Assignment operator

const CAldeaString & operator = (const CAldeaString & oAldeaString);
const CAldeaString & operator = (LPCTSTR pStringT);
const CAldeaString & operator = (LPCWSTR pStringW);

Parameters

oAldeaString	CAldeaString object to be assigned to the object.

pString	LPCTSTR string to be assigned to the object.

pString	LPCWSTR string to be assigned to the object.

Description

These operators are assignment operators. They allow you to change the value of the string referenced by the object..

Example

CAldeaString oString(_T("AString"));
oString =_T("AnotherString");


CAldeaString::Operator +=

Concatenation operator

const CAldeaString & operator += (const CAldeaString & oAldeaString);
const CAldeaString & operator += (LPCTSTR pStringT);
const CAldeaString & operator += (LPCWSTR pStringW);

Parameters

oAldeaString	CAldeaString object to add to the object.

pString	LPCTSTR string to add to the object.

pString	LPCwSTR string to add to the object.

Description

These operators allow you to concatenate the CAldeaString object string with the string passed in parameter. These operators add the string passed in parameter at the end of the string containing in CAldeaString.

Example

CAldeaString oString(_T("abcdef") );
oString +=_T("ghijkl");	// oString = "abcdefghijkl"


CAldeaString::Operator LPCTSTR()

Conversion operator to LPCTSTR

const CAldeaString & operator LPCTSTR() const;

Return value

A character pointer (of type LPCTSTR) to the string.

Description

This operator allows you access the string contained by the CAldeaString object.