

//_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/
//_/_/
//_/_/  This file is part of CMSDK version 2.1.1.260726 (26 July 2026)
//_/_/  
//_/_/  developed by
//_/_/  
//_/_/  Communicative Machines Ltd. 
//_/_/    http://cmlabs.com/
//_/_/  Copyright (c) 2026
//_/_/  
//_/_/  in collaboration with 
//_/_/  
//_/_/  Icelandic Institute for Intelligent Machines ses
//_/_/    Menntavegur 1
//_/_/    101 Reykjavik
//_/_/    ICELAND
//_/_/    http://www.iiim.is/
//_/_/
//_/_/  and is released under the following
//_/_/  
//_/_/  EXTENDED BSD License
//_/_/
//_/_/  Redistribution and use in source and binary forms, with or without
//_/_/  modification, is permitted provided that the following conditions 
//_/_/  are met:
//_/_/
//_/_/  - Redistributions of source code must retain the above copyright 
//_/_/    and collaboration notice, this list of conditions and the following 
//_/_/    disclaimer.
//_/_/
//_/_/  - Redistributions in binary form must reproduce the above copyright 
//_/_/    notice, this list of conditions and the following disclaimer in the 
//_/_/    documentation and/or other materials provided with the distribution.
//_/_/
//_/_/  - Neither the name of its copyright holders nor the names of its 
//_/_/    contributors may be used to endorse or promote products derived from 
//_/_/    this software without specific prior written permission.
//_/_/
//_/_/  - CADIA Clause: The license granted in and to the software under this 
//_/_/    agreement is a limited-use license. The software may not be used in 
//_/_/    furtherance of: (i) intentionally causing bodily injury or severe 
//_/_/    emotional harm to any person; (ii) invading the personal privacy or 
//_/_/    violating the human rights of any person; or (iii) committing or 
//_/_/    preparing for any act of war. 
//_/_/
//_/_/  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 
//_/_/  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 
//_/_/  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A 
//_/_/  PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER 
//_/_/  OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 
//_/_/  EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 
//_/_/  PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 
//_/_/  PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 
//_/_/  LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 
//_/_/  NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 
//_/_/  SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
//_/_/
//_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/
/*! @file PsyInternal.h
	@brief Built-in internal cranks and message-script playback structures.

	Declares the CMSDK's built-in component entry functions (Internal_*), each a
	CrankFunction registered under a well-known name by PsySpace for system
	services, diagnostics and testing (ping/pong, shutdown, scripted message
	playback, stats logging, etc.), plus the TrackPlayerMessage structures used by
	the message-script player.
*/
#if !defined(_PSYINTERNAL_H_)
#define _PSYINTERNAL_H_

#include "Utils.h"
#include "PsyAPI.h"
#include "Bitmap.h"

namespace cmlabs {

/*! @brief One key/value entry of a scripted TrackPlayerMessage. */
struct TrackPlayerMessageEntry {
	enum EntryType { TEXT, INT, FLOAT } entryType; //!< Data type of the value string.
	std::string key;   //!< Entry key placed in the generated message.
	std::string value; //!< Entry value (textual; converted per entryType).
};

/*! @brief One scripted post/signal action for the message-script player (Internal_MessageScript).

	Describes what to send (post or signal, by name, with entries) and when
	(immediately on trigger, after a delay, or repeatedly on a timed interval).
*/
struct TrackPlayerMessage {
	enum PostType { MESSAGE, SIGNAL } postType;          //!< Send as a posted message or as a signal.
	enum TriggerType { TRIGGER, TIME, NONE } triggerType; //!< What causes the send: incoming trigger, timer, or nothing.
	std::string postName;  //!< Post/signal name to use.
	uint32 delayMS;        //!< Delay in ms before sending (after the trigger).
	uint64 nextTime;       //!< Next scheduled send time (PsyTime µs), maintained by the player.
	uint32 timeMS;         //!< Time offset in ms for time-triggered sends.
	uint32 intervalMS;     //!< Repeat interval in ms; 0 for one-shot.
	std::map<std::string, TrackPlayerMessageEntry> entryMap; //!< Entries copied into each generated message.
	/*! Add an entry to the message.
		@param key Entry key. @param value Entry value (text form).
		@param keytype Optional type name ("text", "int", "float"); NULL defaults to text.
		@return true if added.
	*/
	bool addEntry(const char* key, const char* value, const char* keytype = NULL);
};

/*! @name Built-in internal cranks
	CrankFunction implementations registered by PsySpace under reserved names.
	Each takes the component's PsyAPI handle and returns an int8 status.
	@{ */
int8 Internal_Simple(PsyAPI* api);        //!< Pass-through test crank: copies each incoming message to its posts.
int8 Internal_Ping(PsyAPI* api);          //!< Latency test: posts pings, expects pongs.
int8 Internal_Pong(PsyAPI* api);          //!< Latency test counterpart: answers pings.
int8 Internal_Shutdown(PsyAPI* api);      //!< Initiates system shutdown when triggered.
int8 Internal_Print(PsyAPI* api);         //!< Prints incoming messages to the console/log.
int8 Internal_Time(PsyAPI* api);          //!< Posts time information/timestamps.
int8 Internal_SignalPing(PsyAPI* api);    //!< Signal-based ping test.
int8 Internal_SignalPong(PsyAPI* api);    //!< Signal-based pong counterpart.
int8 Internal_RetrieveTest(PsyAPI* api);  //!< Exercises whiteboard retrieve calls.
int8 Internal_MessageScript(PsyAPI* api); //!< Plays back scripted TrackPlayerMessage sequences.
int8 Internal_QueryTest(PsyAPI* api);     //!< Exercises query/queryReply round-trips.
int8 Internal_StatsLog(PsyAPI* api);      //!< Periodically logs system statistics.
int8 Internal_BitmapPoster(PsyAPI* api);  //!< Posts test bitmap/image messages.
int8 Internal_MessageToggler(PsyAPI* api);       //!< Alternates/toggles message output for testing.
int8 Internal_MessageTypeConverter(PsyAPI* api); //!< Converts incoming messages to another type before reposting.
/*! @} */

} // namespace cmlabs

#endif //_PSYINTERNAL_H_

