CWE-ou-minkata/MOULOpenSourceClientPlugin/Plasma20/Sources/Plasma/PubUtilLib/plVault/plVaultClientApi.h

/*==LICENSE==*

CyanWorlds.com Engine - MMOG client, server and tools
Copyright (C) 2011  Cyan Worlds, Inc.

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.

You can contact Cyan Worlds, Inc. by email legal@cyan.com
 or by snail mail at:
      Cyan Worlds, Inc.
      14617 N Newport Hwy
      Mead, WA   99021

*==LICENSE==*/
/*****************************************************************************
*
*   $/Plasma20/Sources/Plasma/PubUtilLib/plVault/plVaultClientApi.h
*   
***/

#ifdef CLIENT

#ifdef PLASMA20_SOURCES_PLASMA_PUBUTILLIB_PLVAULT_PLVAULTCLIENTAPI_H
#error "Header $/Plasma20/Sources/Plasma/PubUtilLib/plVault/plVaultClientApi.h included more than once"
#endif
#define PLASMA20_SOURCES_PLASMA_PUBUTILLIB_PLVAULT_PLVAULTCLIENTAPI_H


/*****************************************************************************
*
*   VaultCallback
*
***/

struct RelVaultNode;

struct VaultCallback {
	struct IVaultCallback *	internal;
	
	virtual void AddedChildNode (
		RelVaultNode *	parent,
		RelVaultNode *	child
	) = 0;

	virtual void RemovingChildNode (
		RelVaultNode *	parent,
		RelVaultNode *	child
	) = 0;

	virtual void ChangedNode (
		RelVaultNode * changedNode
	) = 0;
};

void VaultRegisterCallback (VaultCallback * cb);
void VaultUnregisterCallback (VaultCallback * cb);


/*****************************************************************************
*
*   RelVaultNode
*	A "relational" vault node (contains child and parent node linkage)
*
*	NOTE:	This API is not thread-safe and therefore not suitable for use
*			in server applications.
*
***/
struct RelVaultNode : NetVaultNode {
	struct IRelVaultNode *	state;

	RelVaultNode ();
	~RelVaultNode ();
	
	bool IsParentOf (unsigned nodeId, unsigned maxDepth);
	bool IsChildOf (unsigned nodeId, unsigned maxDepth);
	
	void GetRootIds (ARRAY(unsigned) * nodeIds);
	
	unsigned RemoveChildNodes (unsigned maxDepth);	// returns # of nodes removed

	void GetChildNodeIds (
		ARRAY(unsigned) *	nodeIds,
		unsigned			maxDepth
	);
	void GetParentNodeIds (
		ARRAY(unsigned) *	nodeIds,
		unsigned			maxDepth
	);
	
	void GetMatchingChildNodeIds (
		NetVaultNode *		templateNode,
		ARRAY(unsigned) *	nodeIds,
		unsigned			maxDepth
	);
	void GetMatchingParentNodeIds (
		NetVaultNode *		templateNode,
		ARRAY(unsigned) *	nodeIds,
		unsigned			maxDepth
	);

	// returns first matching node found	
	RelVaultNode * GetParentNodeIncRef (
		NetVaultNode *		templateNode,
		unsigned			maxDepth
	);
	RelVaultNode * GetChildNodeIncRef (
		NetVaultNode *		templateNode,
		unsigned			maxDepth
	);
	RelVaultNode * GetChildNodeIncRef (
		unsigned			nodeType,
		unsigned			maxDepth
	);
	RelVaultNode * GetChildFolderNodeIncRef (
		unsigned			folderType,
		unsigned			maxDepth
	);
	RelVaultNode * GetChildPlayerInfoListNodeIncRef (
		unsigned			folderType,
		unsigned			maxDepth
	);
	RelVaultNode * GetChildAgeInfoListNodeIncRef (
		unsigned			folderType,
		unsigned			maxDepth
	);

	// returns all matching nodes found	
	void GetChildNodesIncRef (
		unsigned				maxDepth,
		ARRAY(RelVaultNode*) *	nodes
	);
	void GetChildNodesIncRef (
		NetVaultNode *			templateNode,
		unsigned				maxDepth,
		ARRAY(RelVaultNode*) *	nodes
	);
	void GetChildNodesIncRef (
		unsigned				nodeType,
		unsigned				maxDepth,
		ARRAY(RelVaultNode*) *	nodes
	);
	void GetChildFolderNodesIncRef (
		unsigned				folderType,
		unsigned				maxDepth,
		ARRAY(RelVaultNode*) *	nodes
	);
	
	unsigned GetRefOwnerId (unsigned parentId);

	bool BeenSeen (unsigned parentId) const;
	void SetSeen (unsigned parentId, bool seen);
	
	// logging
	void Print (const wchar tag[], FStateDump dumpProc, unsigned level);
	void PrintTree (FStateDump dumpProc, unsigned level);
	
	// AgeInfoNode-specific (and it checks!)
	RelVaultNode * GetParentAgeLinkIncRef ();
};


/*****************************************************************************
*
*   Vault Initialize
*
***/

void VaultInitialize ();
void VaultDestroy ();
void VaultUpdate ();


/*****************************************************************************
*
*   Generic vault access
*
***/

RelVaultNode * VaultGetNodeIncRef (
	unsigned	nodeId
);
RelVaultNode * VaultGetNodeIncRef (
	NetVaultNode *	templateNode
);
// VaultAddChildNode will download the child node if necessary
// the parent exists locally before making the callback.
typedef void (*FVaultAddChildNodeCallback)(
	ENetError		result,
	void *			param
);
void VaultAddChildNode (
	unsigned					parentId,
	unsigned					childId,
	unsigned					ownerId,
	FVaultAddChildNodeCallback	callback,	// optional
	void *						param		// optional
);
void VaultAddChildNodeAndWait (
	unsigned					parentId,
	unsigned					childId,
	unsigned					ownerId
);
typedef void (*FVaultRemoveChildNodeCallback)(
	ENetError		result,
	void *			param
);
void VaultRemoveChildNode (
	unsigned						parentId,
	unsigned						childId,
	FVaultRemoveChildNodeCallback	callback,
	void *							param
);
void VaultSetNodeSeen (
	unsigned	nodeId,
	bool		seen
);
void VaultDeleteNode (
	unsigned	nodeId
);
void VaultPublishNode (
	unsigned		nodeId,
	const wchar		deviceName[]
);
void VaultSendNode (
	RelVaultNode*	srcNode,
	unsigned		dstPlayerId
);

typedef void (*FVaultCreateNodeCallback)(
	ENetError		result,
	void *			state,
	void *			param,
	RelVaultNode *	node
);
void VaultCreateNode (			// non-blocking
	plVault::NodeTypes			nodeType,
	FVaultCreateNodeCallback	callback,
	void *						state,
	void *						param
);
void VaultCreateNode (			// non-blocking
	NetVaultNode *				templateNode,
	FVaultCreateNodeCallback	callback,
	void *						state,
	void *						param
);
RelVaultNode * VaultCreateNodeAndWaitIncRef (	// block until completion. returns node. nil --> failure
	plVault::NodeTypes			nodeType,
	ENetError *					result
);
RelVaultNode * VaultCreateNodeAndWaitIncRef (	// block until completion. returns node. nil --> failure
	NetVaultNode *				templateNode,
	ENetError *					result
);
void VaultForceSaveNodeAndWait (
	NetVaultNode *		node
);

typedef void (*FVaultFindNodeCallback)(
	ENetError			result,
	void *				param,
	unsigned			nodeIdCount,
	const unsigned		nodeIds[]
);
void VaultFindNodes (
	NetVaultNode *			templateNode,
	FVaultFindNodeCallback	callback,
	void *					param
);
void VaultFindNodesAndWait (
	NetVaultNode *			templateNode,
	ARRAY(unsigned) *		nodeIds
);
void VaultLocalFindNodes (
	NetVaultNode *			templateNode,
	ARRAY(unsigned) *		nodeIds
);
void VaultFetchNodesAndWait (	// Use VaultGetNodeIncRef to access the fetched nodes
	const unsigned			nodeIds[],
	unsigned				count,
	bool					force = false
);
typedef void (*FVaultInitAgeCallback)(
	ENetError		result,
	void *			state,
	void *			param,
	unsigned		ageVaultId,
	unsigned		ageInfoVaultId
);
void VaultInitAge (
	const class plAgeInfoStruct *	info,
	const Uuid &					parentAgeInstId,
	FVaultInitAgeCallback			callback,
	void *							state,
	void *							param
);


/*****************************************************************************
*
*   Player Vault Access
*
***/

unsigned		VaultGetPlayerId ();
RelVaultNode *	VaultGetPlayerNodeIncRef ();
RelVaultNode *	VaultGetPlayerInfoNodeIncRef ();
RelVaultNode *	VaultGetAvatarOutfitFolderIncRef ();
RelVaultNode *	VaultGetAvatarClosetFolderIncRef ();
bool			VaultGetLinkToMyNeighborhood (plAgeLinkStruct * link);
bool			VaultGetLinkToMyPersonalAge (plAgeLinkStruct * link);
bool			VaultGetLinkToCity (plAgeLinkStruct * link);
RelVaultNode *	VaultGetAgesIOwnFolderIncRef ();
RelVaultNode *	VaultGetAgesICanVisitFolderIncRef ();
RelVaultNode *	VaultGetPlayerInboxFolderIncRef ();
RelVaultNode *	VaultGetOwnedAgeLinkIncRef (const plAgeInfoStruct * info);
RelVaultNode *	VaultGetOwnedAgeInfoIncRef (const plAgeInfoStruct * info);
bool			VaultGetOwnedAgeLink (const plAgeInfoStruct * info, plAgeLinkStruct * link);
bool			VaultAddOwnedAgeSpawnPoint (const Uuid & ageInstId, const plSpawnPointInfo & spawnPt);
bool			VaultSetOwnedAgePublicAndWait (const plAgeInfoStruct * info, bool publicOrNot);
RelVaultNode *	VaultGetVisitAgeLinkIncRef (const plAgeInfoStruct * info);
bool			VaultGetVisitAgeLink (const plAgeInfoStruct * info, class plAgeLinkStruct * link);
bool			VaultRegisterOwnedAgeAndWait (const plAgeLinkStruct * link);
bool			VaultRegisterVisitAgeAndWait (const plAgeLinkStruct * link);
bool			VaultUnregisterOwnedAgeAndWait (const plAgeInfoStruct * info);
bool			VaultUnregisterVisitAgeAndWait (const plAgeInfoStruct * info);
RelVaultNode *	VaultFindChronicleEntryIncRef (const wchar entryName[], int entryType = -1);
bool			VaultHasChronicleEntry (const wchar entryName[], int entryType = -1);
// if entry of same name and type already exists, value is updated
void			VaultAddChronicleEntryAndWait (
	const wchar entryName[],
	int			entryType,
	const wchar entryValue[]
);
bool		VaultAmIgnoringPlayer (unsigned playerId);
unsigned	VaultGetKILevel ();
bool		VaultGetCCRStatus ();				// true=online, false=away
bool		VaultSetCCRStatus (bool online);	// true=online, false=away
void		VaultDump (const wchar tag[], unsigned vaultId, FStateDump dumpProc);
void		VaultDump (const wchar tag[], unsigned vaultId);

bool VaultAmInMyPersonalAge ();
bool VaultAmInMyNeighborhoodAge ();
bool VaultAmOwnerOfCurrentAge ();
bool VaultAmCzarOfCurrentAge ();
bool VaultAmOwnerOfAge (const Uuid & ageInstId);
bool VaultAmCzarOfAge (const Uuid & ageInstId);
bool VaultRegisterMTStationAndWait (
	const wchar	stationName[],
	const wchar	linkBackSpawnPtObjName[]
);
void VaultProcessPlayerInbox ();


/*****************************************************************************
*
*   Age Vault Access
*
***/

#define DEFAULT_DEVICE_INBOX L"DevInbox"

RelVaultNode * VaultGetAgeNodeIncRef ();
RelVaultNode * VaultGetAgeInfoNodeIncRef ();
RelVaultNode * VaultGetAgeChronicleFolderIncRef ();
RelVaultNode * VaultGetAgeDevicesFolderIncRef ();
RelVaultNode * VaultGetAgeSubAgesFolderIncRef ();
RelVaultNode * VaultGetAgeChildAgesFolderIncRef ();
RelVaultNode * VaultGetAgeAgeOwnersFolderIncRef ();
RelVaultNode * VaultGetAgeCanVisitFolderIncRef ();
RelVaultNode * VaultGetAgePeopleIKnowAboutFolderIncRef ();
RelVaultNode * VaultGetAgePublicAgesFolderIncRef ();
RelVaultNode * VaultAgeGetBookshelfFolderIncRef ();
RelVaultNode * VaultFindAgeSubAgeLinkIncRef (const plAgeInfoStruct * info);
RelVaultNode * VaultFindAgeChildAgeLinkIncRef (const plAgeInfoStruct * info);
RelVaultNode * VaultFindAgeChronicleEntryIncRef (const wchar entryName[], int entryType = -1);
// if entry of same name and type already exists, value is updated
void		   VaultAddAgeChronicleEntry (
	const wchar entryName[],
	int			entryType,
	const wchar entryValue[]
);
RelVaultNode * VaultAgeAddDeviceAndWaitIncRef (const wchar deviceName[]);	// blocks until completion
void VaultAgeRemoveDevice (const wchar deviceName[]);
bool VaultAgeHasDevice (const wchar deviceName[]);
RelVaultNode * VaultAgeGetDeviceIncRef (const wchar deviceName[]);
RelVaultNode * VaultAgeSetDeviceInboxAndWaitIncRef (const wchar deviceName[], const wchar inboxName[]);	// blocks until completion
RelVaultNode * VaultAgeGetDeviceInboxIncRef (const wchar deviceName[]);
void VaultClearDeviceInboxMap ();

bool VaultAgeGetAgeSDL (class plStateDataRecord * out);
void VaultAgeUpdateAgeSDL (const class plStateDataRecord * rec);

unsigned VaultAgeGetAgeTime ();

bool VaultAgeGetSubAgeLink (
	const plAgeInfoStruct * info,
	plAgeLinkStruct *		link
);
bool VaultAgeFindOrCreateSubAgeLinkAndWait (
	const plAgeInfoStruct * info,
	plAgeLinkStruct *		link,
	const Uuid &			parentAgeInstId
);
bool VaultAgeFindOrCreateChildAgeLinkAndWait (
	const wchar				parentAgeName[],	// nil --> current age, non-nil --> owned age by given name
	const plAgeInfoStruct * info,
	plAgeLinkStruct *		link
);



/*****************************************************************************
*
*   CCR Vault Access
*
***/

void VaultCCRDumpPlayers();



/*****************************************************************************
*
*   Vault download
*
***/

typedef void (*FVaultDownloadCallback)(
	ENetError					result,
	void *						param
);
typedef void (*FVaultProgressCallback)(
	unsigned					total,
	unsigned					curr,
	void *						param
);

void VaultDownload (
	const wchar					tag[],
	unsigned					vaultId,
	FVaultDownloadCallback		callback,
	void *						cbParam,
	FVaultProgressCallback		progressCallback,
	void *						cbProgressParam
);
void VaultDownloadAndWait (
	const wchar					tag[],
	unsigned					vaultId,
	FVaultProgressCallback		progressCallback,
	void *						cbProgressParam
);

void VaultCull (
	unsigned					vaultId
);

/*****************************************************************************
*
*   Vault global node handling
*
***/

RelVaultNode * VaultGetSystemNodeIncRef ();
RelVaultNode * VaultGetGlobalInboxIncRef ();

#endif // def CLIENT