PichatCore documentation, generated with mkdocument

Last update 31/Mar/2011 by Mark Seuffert

1. Introduction

This is a documentation about the PichatCore library. Pichat is a chat platform to communicate and exchange information, the core classes provide basic communication functionality. Shared libraries are available for C++ on Linux, BSD and Windows.
Feature highlights:
  • plugin support
  • chat bots, chat actions such as users joining and leaving a chatroom
  • HTTP and SMTP classes for data exchange via web and email
  • not binary dependent on a specific version of STL or Boost
PichatCore is included in the Pichat SDK, available at http://www.pichat.net

2.1. CContainerText

Description: Container for text strings, multiple languages
Header file: PichatCore_ContainerText.h, namespace PichatCore
Comments: This class provides loading text strings and multi language support. Instead of using hardcoded text in your application you can load text strings from resources, files or memory. A resource or stream consists of newline separated text lines and may have multiple sections. This container is intended for sections with the same number of text strings.
Construction
Syntax:CContainerText();
Constants
DATA_NOT_FOUNDsection not found
DATA_DEFAULTdefault section
Create - Create text container
Notes: Initialises the container with text strings from a resource. You can optionally specify a reference section, then the container stays empty and the reference section is used to verify new sections and to make sure that text formatting arguments (sprintf style) are correct.
Syntax:bool Create(HMODULE hResourceModule, int nResourceID, const char* szSectionFilter, const char* szSectionReference = NULL);
Destroy - Destroy text container
Syntax:void Destroy();
Clear - Clear text container and remove all text strings
Syntax:void Clear();
Add - Load section from stream
Notes: This method can be used to load text strings from file or memory. Adding a section can fail for three reasons, the section was not found, the section does already exist or the verification with the optional reference section failed.
Syntax:bool Add(SharkEngine::CFileStream& file, const char* szSectionName);
Scan - Scan stream and return list of available sections
Syntax:CString8 Scan(SharkEngine::CFileStream& file) const;
FindSectionName - Return section name from ID
Notes: Returns section name or empty string if not found.
Syntax:CString8 FindSectionName(int nSectionID) const;
FindSectionID - Return ID from section name
Notes: Returns section ID or DATA_NOT_FOUND if not found.
Syntax:int FindSectionID(const char* szSectionName) const;
GetString - Return text string
Syntax:const char* GetString(int nTextID, int nSectionID) const;
GetSectionSize - Return number of text strings per section
Syntax:int GetSectionSize() const;
GetSize - Return number of sections
Syntax:int GetSize() const;
GetLastVerificationError - Return text ID where last verification with reference section failed
Syntax:int GetLastVerificationError() const;
IsCreated - Check if text container is created
Syntax:bool IsCreated() const;
IsEmpty - Check if text container is empty
Syntax:bool IsEmpty() const;
IsValidTextID - Check if text ID is valid
Syntax:bool IsValidTextID(int nTextID) const;
IsValidSectionID - Check if section ID is valid
Syntax:bool IsValidSectionID(int nSectionID) const;
IsLastVerificationError - Check if last verification with reference section failed
Syntax:bool IsLastVerificationError() const;

2.2. CContainerTextMap

Description: Associative container for text strings, multiple languages
Header file: PichatCore_ContainerTextMap.h, namespace PichatCore
Comments: This class provides loading text strings and multi language support. Instead of using hardcoded text in your application you can load text strings from resources, files or memory. A resource or stream consists of newline separated text lines and may have multiple sections. This container can handle sections with a variable number of text strings, each section contains text lines in the format key=value.
Construction
Syntax:CContainerTextMap();
Constants
DATA_NOT_FOUNDsection not found
DATA_DEFAULTdefault section
Create - Create text container
Notes: Initialises the container with text strings from a resource. You can optionally specify a reference section, then the container stays empty and the reference section is used to verify new sections and to make sure that text formatting arguments (sprintf style) are correct.
Syntax:bool Create(HMODULE hResourceModule, int nResourceID, const char* szSectionFilter, const char* szSectionReference = NULL);
Destroy - Destroy text container
Syntax:void Destroy();
Clear - Clear text container and remove all text strings
Syntax:void Clear();
Add - Load section from stream
Notes: This method can be used to load text strings from file or memory. Adding a section can fail for three reasons, the section was not found, the section does already exist or the verification with the optional reference section failed.
Syntax:bool Add(SharkEngine::CFileStream& file, const char* szSectionName);
Scan - Scan stream and return list of available sections
Syntax:CString8 Scan(SharkEngine::CFileStream& file) const;
FindSectionName - Return section name from ID
Notes: Returns section name or empty string if not found.
Syntax:CString8 FindSectionName(int nSectionID) const;
FindSectionID - Return ID from section name
Notes: Returns section ID or DATA_NOT_FOUND if not found.
Syntax:int FindSectionID(const char* szSectionName) const;
GetString - Return text string
Syntax:const char* GetString(const char* szKeyName, int nSectionID) const;
bool GetString(int nTextID, int nSectionID, const char** ppKeyName, const char** ppKeyValue) const;
GetSectionSize - Return number of text strings in section
Syntax:int GetSectionSize(int nSectionID) const;
GetSize - Return number of sections
Syntax:int GetSize() const;
GetLastVerificationError - Return key where last verification with reference section failed
Syntax:CString8 GetLastVerificationError() const;
IsCreated - Check if text container is created
Syntax:bool IsCreated() const;
IsEmpty - Check if text container is empty
Syntax:bool IsEmpty() const;
IsExisting - Check if key exists in section
Syntax:bool IsExisting(const char* szKeyName, int nSectionID) const;
IsValidTextID - Check if text ID is valid
Syntax:bool IsValidTextID(int nTextID, int nSectionID) const;
IsValidSectionID - Check if section ID is valid
Syntax:bool IsValidSectionID(int nSectionID) const;
IsLastVerificationError - Check if last verification with reference section failed
Syntax:bool IsLastVerificationError() const;
IsValidKeyName - Check if key name is valid
Notes: Key names must contain alphanumeric characters and underscore only.
Syntax:static bool IsValidKeyName(const char* szKeyName);

2.3. ChatActions

Description: Namespace with chat actions
Header file: PichatCore_ChatActions.h, namespace PichatCore::ChatActions
Constants
chat actions (* = for chat admins only):
CHAT_NONEnone or invalid
CHAT_NOTICEgeneric notice information
CHAT_DEBUGgeneric debug information
CHAT_ERRORgeneric error information
CHAT_TEXTchat text
CHAT_CLEARclear text
CHAT_PRIVMESSAGEprivate message text
CHAT_INSTMESSAGEinstant message text
CHAT_UNKNOWNunknown server action
CHAT_LANGUAGElanguage was set
CHAT_NICKnickname was set
CHAT_NICKCHANGEnickname of chatroom user has changed
CHAT_USERMODEuser mode was set
CHAT_USERMODECHANGEuser mode of chatroom user has changed
CHAT_AWAYaway status was set
CHAT_AWAYCHANGEaway status of chatroom users has changed
CHAT_CHATROOMchatroom was set
CHAT_CHATROOMMODEchatroom mode has changed
CHAT_CHATROOMTOPICchatroom topic has changed
CHAT_CHATROOMLISTchatroom list has changed
CHAT_USERLISTchatroom user list has changed
CHAT_USERNUMBERchatroom user number has changed
CHAT_JOINuser has joined chatroom
CHAT_LEAVEuser has left chatroom
CHAT_PINGping from user
CHAT_PONGpong from user, just 4 fun
CHAT_PINGREPLYping reply from user
CHAT_DEBUGMODEdebug mode has changed
CHAT_NETWORKnetwork status has changed
CHAT_SERVER_STATUSserver status has changed
CHAT_SERVER_PINGserver connection test
CHAT_SERVER_USERNUMBERserver user number has changed
CHAT_SERVER_USERADD* server has one user more
CHAT_SERVER_USERREMOVE* server has one user less
CHAT_SERVER_CHATROOMADD* server has one chatroom more
CHAT_SERVER_CHATROOMREMOVE* server has one chatroom less
CHAT_SERVER_USERLOGIN* registered user has logged in
CHAT_SERVER_USERLOGOUT* registered user has logged out
CHAT_SERVER_ADMINCOMMAND* chat admin has issued a command
CHAT_SERVER_READY* server and plugins are loaded (own chat server)
CHAT_SERVER_LOGFILES* reopen logfiles (own chat server)
CHAT_SERVER_ONLINE* server goes online (own chat server)
CHAT_SERVER_OFFLINE* server goes offline (own chat server)
CHAT_SERVER_AWAYCHANGE* server away status has changed (own chat server)
CHAT_PEER_ONLINE* peer goes online (local network)
CHAT_PEER_OFFLINE* peer goes offline (local network)
CHAT_PEER_AWAYCHANGE* peer away status has changed (local network)
CHAT_CLIENT_COMMANDclient has issued a command
CHAT_ACTION_CUSTOMcustom actions, free for use
 
chat text color codes:
TEXT_COLOR_NONEno special text color
TEXT_COLOR_1text color one, negative emphasis or warning (e.g. red)
TEXT_COLOR_2text color two, positive emphasis (e.g. green)
TEXT_COLOR_3text color three, neutral emphasis (e.g. blue)
TEXT_COLOR_4text color four, alternative emphasis (e.g. yellow)
TEXT_COLOR_CUSTOMcustom colors, free for use
 
generic chat actions types:
SERVER_NONEno special type
SERVER_CHAT_LOGFILEaction for chat server logfile (if available)
SERVER_HTTP_LOGFILEaction for web server logfile (if available)
SERVER_TYPE_CUSTOMcustom types, free for use

2.4. ChatActions::Network

Description: Namespace with chat network status
Header file: PichatCore_ChatActions.h, namespace PichatCore::ChatActions::Network
Constants
chat network status:
STATUS_CLOSEDclient closed
STATUS_CLOSED_RECONNECTclient closed, waiting for reconnect
STATUS_UNCONNECTEDclient not connected
STATUS_CLOSINGclient closing/disconnecting
STATUS_CONNECTING_STARTclient starting new connection
STATUS_CONNECTING_LOOKUPclient resolving hostname
STATUS_CONNECTINGclient connecting
STATUS_CONNECTEDclient connected to other peer
STATUS_CONNECTED_SESSION_STARTclient connected, starting handshake
STATUS_CONNECTED_SESSION_OKclient connected, session established
STATUS_CONNECTED_SESSIONclient connected, user is logged in
STATUS_SERVER_OFFLINElocal server offline
STATUS_SERVER_ONLINElocal server online
STATUS_TYPE_CUSTOMcustom types, free for use

2.5. ChatActions::Server

Description: Namespace with chat server status codes
Header file: PichatCore_ChatActions.h, namespace PichatCore::ChatActions::Server
Constants
STATUS_CODE_NONEchat status codes
STATUS_CODE_CONNECTED_BINARY
STATUS_CODE_CONNECTED_TEXT
STATUS_CODE_ACCEPTED
STATUS_CODE_DONE
STATUS_CODE_NEXT_REQUEST
STATUS_CODE_BAD_REQUESTchat client errors
STATUS_CODE_UNAUTHORISED
STATUS_CODE_AUTHENTICATION_REQUIRED
STATUS_CODE_BANNED
STATUS_CODE_NICKNAME_REQUIRED
STATUS_CODE_NICKNAME_INVALID
STATUS_CODE_NICKNAME_NOT_POSSIBLE
STATUS_CODE_ARGUMENTS_NOT_ACCEPTABLE
STATUS_CODE_HANDSHAKE_TIMEOUT
STATUS_CODE_HANDSHAKE_FAILED
STATUS_CODE_INTERNAL_SERVER_ERRORchat server errors
STATUS_CODE_CHAT_SERVER_CLOSED
STATUS_CODE_CHAT_SERVER_FULL
STATUS_CODE_CHAT_LOGIN_FAILED
 
chat modes:
CHAT_NONEno valid chat mode
CHAT_OPENany user can enter the chat
CHAT_MEMBERSonly registered users can enter the chat
CHAT_CLOSEDno new users can enter the chat
 
chatroom types:
CHATROOM_NONEno valid chatroom type
CHATROOM_NORMALnormal chatroom, any user can join and talk
CHATROOM_MODERATEDmoderated chatroom, restricted talking
CHATROOM_CONFERENCEconference chatroom, restricted joining

2.6. ChatActions::User

Description: Namespace with chat user status
Header file: PichatCore_ChatActions.h, namespace PichatCore::ChatActions::User
Constants
user away status:
STATUS_OFFLINEuser is offline
STATUS_ONLINEuser is online
STATUS_ONLINE_UNUSED2unused
STATUS_ONLINE_UNUSED3unused
STATUS_AWAYuser is away
STATUS_AWAY_UNUSED5unused
STATUS_AWAY_UNUSED6unused
STATUS_AWAY_UNUSED7unused
STATUS_AWAY_DNDuser is away, do not disturb
STATUS_TYPE_CUSTOMcustom types, free for use
 
user connect/reconnect status:
STATUS_CONNECTINGuser is connecting
STATUS_RECONNECTINGuser is reconencting
 
user authentication status:
AUTHENTICATION_NONEuser not found
AUTHENTICATION_OKuser authenticated
AUTHENTICATION_USERNAME_FAILEDuser disabled
AUTHENTICATION_PASSWORD_FAILEDpassword mismatch
AUTHENTICATION_ADDRESS_FAILEDaddress mismatch
AUTHENTICATION_SAFEGUARD_FAILEDsafeguard on user
AUTHENTICATION_TYPE_CUSTOMcustom types, free for use
 
chat user types:
USER_NONEno valid user type
USER_ZOMBIEuser with many restrictions
USER_VISITORuser with some restrictions
USER_NORMALuser without restrictions
USER_MODERATORuser with moderation rights
USER_ADMINuser with administration rights

2.7. ChatAlgorithms

Description: Namespace with common chat and networking algorithms
Header file: PichatCore_ChatAlgorithms.h, namespace PichatCore::ChatAlgorithms
GetChatActionName - Return human readable chat action
Syntax:const char* GetChatActionName(int nChatAction);
FindChatAction - Identify chat action
Syntax:int FindChatAction(const char* szChatActionName);
FindColorCode - Identify text color code
Syntax:int FindColorCode(const char* pText, int* pnLength);
GetStatusPrefix - Return status line text prefix
Syntax:CString8 GetStatusPrefix();
GetTextPrefix - Return text prefix for given type
Syntax:CString8 GetTextPrefix(int nTextType);
GetNetworkStatusFormated - Return human readable chat network status
Syntax:CString8 GetNetworkStatusFormated(int nStatus);
GetServerStatusFormated - Return human readable chat server status
Syntax:CString8 GetServerStatusFormated(int nStatusCode);
GetChatModeFormated - Return human readable chat mode
Syntax:CString8 GetChatModeFormated(int nChatMode);
CString8 GetChatModeFormatedSimple(int nChatMode);
GetChatroomTypeFormated - Return human readable chatroom type
Syntax:CString8 GetChatroomTypeFormated(int nChatroomType);
CString8 GetChatroomTypeFormatedSimple(int nChatroomType);
GetUserTypeFormated - Return human readable chat user type
Syntax:CString8 GetUserTypeFormated(int nUserType);
CString8 GetUserTypeFormatedSimple(int nUserType);
GetAddressFormated - Return human readable IP address
Syntax:CString8 GetAddressFormated(unsigned long lAddr);
GetBufferFormated - Return human readable buffer in hex format
Syntax:CString8 GetBufferFormated(const void* pBuffer, int nBufferLen);
GetBytesFormated - Return human readable byte number, GB/MB/KB
Syntax:CString8 GetBytesFormated(DWORD dwBytes, bool bRounded = false);
GetLevelFormated - Return human readable level, low/medium/high
Syntax:CString8 GetLevelFormated(int nValue, const char* szLanguageTokens = NULL);
GetTimeFormated - Return human readable time
Syntax:CString8 GetTimeFormated(DWORD dwSeconds, const char* szLanguageTokens = NULL, int nSkipDetails = 0);
CString8 GetTimeSimpleFormated(DWORD dwSeconds, const char* szLanguageTokens = NULL);
HtmlEncodeString - HTML encode text string
Syntax:CString8 HtmlEncodeString(const char* szText);
UrlEncodeString - URL encode or decode text string
Syntax:CString8 UrlEncodeString(const char* szText);
void UrlDecodeString(char* szText);
Base64EncodeString - Base64 encode or decode text string
Syntax:CString8 Base64EncodeString(const char* szText);
void Base64DecodeString(char* szText);
Base64Encode - Base64 encode or decode given buffer
Notes: Returns length of output or 0 if output buffer is too small. For encoding the output length needs to be at least input length * 4 / 3 + 3.
Syntax:int Base64Encode(const void* pBuffer, int nBufferLen, void* pOutput, int nOutputLen);
int Base64Decode(void* pBuffer, int nBufferLen);
EscapeString - Escape text string, encode special characters with backslash and octal number
Syntax:CString8 EscapeString(const char* szText, char cEncode = ',');
UnescapeString - Unescape text string, convert backslashes followed by octal number
Syntax:void UnescapeString(char* szText);
NormaliseLocationTokens - Normalise location, remove incorrect path tokens
Syntax:void NormaliseLocationTokens(char* szText);
NormaliseName - Normalise name, for nickname or chatroom
Syntax:void NormaliseName(char* szText);
CheckNameValid - Check if name is in valid format, for nickname or chatroom
Syntax:bool CheckNameValid(const char* szText);
CheckChatroomCodeValid - Check if chatroom code is in valid format
Syntax:bool CheckChatroomCodeValid(const char* szText);
CheckUserIdentificationValid - Check if user identification is in valid format
Syntax:bool CheckUserIdentificationValid(const char* szText);
CheckAddressValid - Check if IP address is in valid format
Syntax:bool CheckAddressValid(const char* szText);
CheckFileNameValid - Check if file name has no relative path tokens
Syntax:bool CheckFileNameValid(const char* szFileName);
CheckKeyNameValid - Check if key name contains alphanumeric characters and underscore only
Syntax:bool CheckKeyNameValid(const char* szKeyName);
CheckCommandMatch - Check if command matches one in a list
Syntax:bool CheckCommandMatch(const char* szCommand, int nCommandLen, const char* szCommandList, char cSeparator = ',');
CreateIdentification - Create unique identification string
Syntax:CString8 CreateIdentification(const char* szIdentificationBase, int nLengthMin);
RemoveDuplicates - Remove duplicate tokens from a text string
Syntax:void RemoveDuplicates(CString8& sText, char cSeparator = ' ');
RemoveTextFormatting - Remove text formatting codes from a text string
Syntax:void RemoveTextFormatting(CString8& sText);
void RemoveTextFormatting(char* szText);
ConvertWikiTextFormatting - Convert wiki text formatting into normal chat formatting style
Syntax:void ConvertWikiTextFormatting(CString8& sText);
void ConvertWikiTextFormatting(char* szText);
ConvertTimeString - Convert time string of format hh:mm or hh:mm:ss (GMT)
Notes: There is no local time conversion and no daylight saving.
Syntax:time_t ConvertTimeString(const char* szTime);
TrimTextEllipsis - Trim length of text, shorten with ellipsis
Syntax:int TrimTextEllipsis(CString8& sText, int nLengthMax);
TrimTextLine - Trim length of text line, keep ending newline
Syntax:int TrimTextLine(CString8& sText);
ChangeBitValue - Perform boolean operation on variable
Notes: Available operations are 0 = NONE, 1 = AND, 2 = OR, 3 = EXCLUSIVE OR.
Syntax:void ChangeBitValue(int& nVariable, int nBits, int nOperation);
void ChangeBoolValue(bool& nVariable, int nOperation);
CheckCondition - Check a numerical condition
Notes: Available comparisons are 0 = NONE, 1 = LESS, 2 = GREATER, 3 = EQUAL, 4 = NOT EQUAL.
Syntax:bool CheckCondition(int nValue1, int nComparison, int nValue2);
GetConditionFormated - Return human readable condition
Syntax:CString8 GetConditionFormated(int nComparison, int nValue);
FindCondition - Identify condition, one of the comparison characters <>=!
Syntax:int FindCondition(const char* szText);
AwayConvert - Convert string into away status and away text
Syntax:int AwayConvert(const char** ppText);
NameConvert - Convert string into name and status, for nickname or chatroom
Syntax:int NameConvert(const char** ppText);
TextConvert - Convert string into text and type
Syntax:int TextConvert(const char** ppText);
SplitAddress - Split chat server address
Notes: This method splits chat server address into authentication, hostname, port number and further arguments.
Syntax:void SplitAddress(const char* szText, CString8& sAuthentication, CString8& sHostname, CString8& sHostPort, CString8& sArguments, int nDefaultPort);
SplitUrl - Split absolute URL
Notes: This method splits absolute URL into authentication, hostname, port number and location.
Syntax:void SplitUrl(const char* szText, CString8& sAuthentication, CString8& sHostname, CString8& sHostPort, CString8& sLocation);
SplitMultipleLines - Split multiple text lines
Notes: This method splits newline terminated text lines (CRLF and LF). OnReceiveLine() will be called for each line, see IDataReceiveInterface.
Syntax:void SplitMultipleLines(char* szText, IDataReceiveInterface* pReceiveHandler);
ParseStream - Parse web page stream
Notes: This method gives access to the built-in web page parser, you can supply text arguments and chat server information (via an application interface). Fur further information please see IApplicationInterface.
Syntax:void ParseStream(SharkEngine::CFileStream& fileIn, SharkEngine::CFileStream& fileOut, const char* szArgumentsReceived = NULL, const char* szArgumentsExtra = NULL, const char* szAcceptLanguage = NULL, IApplicationInterface* pApi = NULL, bool bExtended = false, int nParserBufferSize = CORE_PARSER_BUFFER_SIZE);
DetectStreamLanguage - Detect language ID of web page stream
Notes: This method detects language from user agent (Accept-Language header) or optional location argument.
Syntax:int DetectStreamLanguage(const char* szAcceptLanguage, const char* szArgumentsReceived, IApplicationInterface* pApi);
int DetectStreamLanguage(const char* szAcceptLanguage, const char* szLanguageOverride, IApplicationInterface* pApi, bool bOverride);
CompressBinaryData - Compress binary data
Syntax:bool CompressBinaryData(SharkEngine::CDataCompression& data, const char* pText, int nTextLen);
bool CompressBinaryDataSimple(SharkEngine::CDataCompression& data, const char* pText, int nTextLen);
DecompressBinaryData - Decompress and split binary data
Notes: This method decompresses binary packages and splits them into text. OnReceiveLine() will be called for each line, see IDataReceiveInterface.
Syntax:bool DecompressBinaryData(SharkEngine::CDataCompression& data, BYTE* pBuffer, int* pnBufferLen, DWORD* pBytesUncompressed, IDataReceiveInterface* pReceiveHandler);
CalcCompressionRatio - Calculate compression ratio in percent
Notes: Requires a minimum of 1KB uncompressed data, with less the returned compression ratio will be 0%.
Syntax:int CalcCompressionRatio(DWORD dwBytesCompressed, DWORD dwBytesUncompressed);
CalcSha256Hash - Calculate SHA256 hash from text string
Syntax:CString8 CalcSha256Hash(const char* szText);
AsText - Return value as text string
Syntax:CString8 AsText(int nValue)
CString8 AsText(DWORD dwValue)

2.8. CParserServerAuthentication

Description: File parser for reading and writing server authentication
Header file: PichatCore_ParserServerAuthentication.h, namespace PichatCore
Comments: This class provides reading and writing a server authentications file.
Construction
Syntax:CParserServerAuthentication();
Constants
PARSER_BUFFER_SIZE = CORE_PARSER_BUFFER_SIZE
Create - Create parser
Notes: Creates a server authentications file if write access is requested.
Syntax:bool Create(const char* szFileName, const char* szSectionName, bool bReadWrite = true, int nParserBufferSize = PARSER_BUFFER_SIZE);
Destroy - Destroy parser
Syntax:void Destroy();
SetSection - Set current section
Syntax:void SetSection(const char* szSectionName);
Find - Check if server authentication exists
Syntax:bool Find(const char* szServerAddress);
GetNext - Get next server authentication
Notes: This method can be used to iterate through all server authentications in a section. To start at the beginning of a section call SetSection().
Syntax:bool GetNext(CString8& sServerAddress, CString8& sUserName, CString8& sPassword);
Get - Get server authentication
Syntax:bool Get(const char* szServerAddress, CString8& sUserName, CString8& sPassword);
Update - Update or add server authentication
Notes: Updates server authentication or adds it to the end of the section if not found. All server authentications are limited to a maximum length and are not written to disk if they exceed parser buffer size.
Syntax:bool Update(const char* szServerAddress, const char* szServerAddressNew, const char* szUserName, const char* szPassword);
Remove - Remove server authentication
Syntax:bool Remove(const char* szServerAddress);
RemoveAll - Remove all server authentications
Syntax:bool RemoveAll();
GetFileName - Return name of file
Syntax:CString8 GetFileName() const;
GetSectionName - Return name of current section
Syntax:CString8 GetSectionName() const;
GetServerAddress - Return current server address
Syntax:CString8 GetServerAddress() const;
IsSectionExisting - Check if section exists
Syntax:bool IsSectionExisting();
IsCreated - Check if parser is created
Syntax:bool IsCreated() const;
IsError - Check if error has happened while reading/writing file
Syntax:bool IsError() const;

2.9. CParserUserAuthentication

Description: File parser for reading and writing user authentications
Header file: PichatCore_ParserUserAuthentication.h, namespace PichatCore
Comments: This class provides reading and writing a user authentications file.
Construction
Syntax:CParserUserAuthentication();
Constants
PARSER_BUFFER_SIZE = CORE_PARSER_BUFFER_SIZE
Create - Create parser
Notes: Creates a user authentications file if write access is requested.
Syntax:bool Create(const char* szFileName, const char* szSectionName, bool bReadWrite = true, int nParserBufferSize = PARSER_BUFFER_SIZE);
Destroy - Destroy parser
Syntax:void Destroy();
SetSection - Set current section
Syntax:void SetSection(const char* szSectionName);
Find - Check if user authentication exists
Syntax:bool Find(const char* szUserName);
GetNext - Get next user authentication
Notes: This method can be used to iterate through all user authentications in a section. To start at the beginning of a section call SetSection().
Syntax:bool GetNext(CString8& sUserName, CString8& sPassword, int& nUserType, CString8& sAddress, CString8& sMetaData);
Get - Get user authentication
Notes: Passwords have prefix 'sha256:' or 'plaintext:', meta data is a comma separated list in the format 'key=value,key=value'.
Syntax:bool Get(const char* szUserName, CString8& sPassword, int& nUserType, CString8& sAddress, CString8& sMetaData);
Update - Update or add user authentication
Notes: Updates user authentication or adds it to the end of the section if not found. All user authentications are limited to a maximum length and are not written to disk if they exceed parser buffer size.
Syntax:bool Update(const char* szUserName, const char* szUserNameNew, const char* szPassword, int nUserType, const char* szAddress, const char* szMetaData);
Remove - Remove user authentication
Syntax:bool Remove(const char* szUserName);
RemoveAll - Remove all user authentications
Syntax:bool RemoveAll();
GetFileName - Return name of file
Syntax:CString8 GetFileName() const;
GetSectionName - Return name of current section
Syntax:CString8 GetSectionName() const;
GetUserName - Return current user name
Syntax:CString8 GetUserName() const;
GetMetaDataSize - Return allowed meta data size
Notes: The maximum allowed meta data size depends on the parser buffer size (ca 8000 bytes with default buffer size).
Syntax:int GetMetaDataSize() const;
IsSectionExisting - Check if section exists
Syntax:bool IsSectionExisting();
IsCreated - Check if parser is created
Syntax:bool IsCreated() const;
IsError - Check if error has happened while reading/writing file
Syntax:bool IsError() const;

2.10. CPluginHandler

Description: Plugin handler for loading shared libraries
Header file: PichatCore_PluginHandler.h, namespace PichatCore
Comments: This class is used to load shared libraries on runtime. Plugins are shared libraries that implement a specific C++ interface. When a handler creates a plugin it may provide chat functionality in form of an application interface, see IApplicationInterface.
Construction
Syntax:CPluginHandler();
Create - Create plugin
Syntax:bool Create(const char* szFileName, IApplicationInterface* pApi = NULL);
Destroy - Destroy plugin
Syntax:void Destroy();
GetVersionName - Return plugin version name
Syntax:const char* GetVersionName() const;
GetVersionDescription - Return plugin version description
Syntax:const char* GetVersionDescription() const;
GetVersionNumber - Return plugin version number
Syntax:int GetVersionNumber() const;
GetAuthor - Return plugin author or copyright information
Syntax:const char* GetAuthor() const;
GetPtr - Return pointer to plugin
Syntax:void* GetPtr() const;
IsCreated - Check if plugin instance is created
Syntax:bool IsCreated() const;

2.11. CSocketClientHttp

Description: HTTP client to access data on a web server
Header file: PichatCore_SocketClientHttp.h, namespace PichatCore
Comments: This class implements a HTTP 1.1 client as defined in RFC 1945, RFC 2616, RFC 2617. It supports persistent connection, compression, traffic limitation, authentication, partial file transfer and connection via a HTTP proxy. It's possible to download data into memory or store as file. Derive your own class from this and overload the virtual methods you need. Generally, if you overload a virtual method call the base class method first. For further information please see network classes in the SharkEngine library.
Limitations on Windows platform: Downloads from a HTTP 1.0 web server with unknown content length are always reported as "not complete". Winsock does not report if a connection was closed before all data has been received.
These virtual methods exist:
  • OnRequest() informs when request has been completed or failed
  • OnDownloadStart() informs when data download has started
  • OnDownloadStop() informs when data download has stopped
  • OnClientClose() informs when client is disconnected from server
Construction
Syntax:CSocketClientHttp();
Constants
socket status:
SOCKET_NONEserver not connected
SOCKET_HANDSHAKE_REQUESTsending request and headers
SOCKET_HANDSHAKE_DATAsending additional content data
SOCKET_HANDSHAKE_RESPONSEwaiting for response
SOCKET_HANDSHAKE_HEADERSreceiving headers
SOCKET_DATA_TRANSFERreceiving content data
SOCKET_KEEP_ALIVEwaiting for next request
 
output stream modes:
STREAM_OVERWRITEexisting download is overwritten
STREAM_RESUMEexisting download is continued if possible
 
custom error codes:
ERROR_EINPUTSTREAMreading input stream failed
ERROR_EOUTPUTSTREAMwriting output stream failed
ERROR_EDECOMPRESSIONdecompression failed
ERROR_EBADENCODINGbad transfer encoding
 
MEMORY_STREAM_SIZE_MAX = 32768
SetRequestHeaders - Set HTTP request headers
Notes: This method can be used to send additional headers with each request, the standard headers include a default 'User-Agent', 'Accept' and 'Accept-Encoding' header. Each header must be '\r\n' terminated.
Syntax:void SetRequestHeaders(const char* szHeaders = NULL, bool bStandardHeaders = true);
SetInputStream - Set input stream from file or memory
Notes: This method can be used to send additional content data with a request, e.g. a POST request. The first version sets a local file, the second version a buffer memory. Per default no input stream is used.
Syntax:bool SetInputStream(const char* szFileName, const char* szContentType);
bool SetInputStream(const MEMBLOCK memory, const char* szContentType);
SetOutputStream - Set output stream to file or memory
Notes: The first version directs download into a local file, the second version into a buffer memory (allocated memory is reused for subsequent requests). In any case a maximum size for a download can be set, 0 means unlimited. Per default download goes into a buffer memory.
Syntax:bool SetOutputStream(const char* szFileName, int nStreamMode = STREAM_OVERWRITE, int nSizeMax = 0);
bool SetOutputStream(int nStreamMode = STREAM_OVERWRITE, int nSizeMax = MEMORY_STREAM_SIZE_MAX);
SetDataTransferRateLimit - Set traffic limitations
Notes: Data transfer rate can be set to an upper limit (bytes per second), 0 means unlimited transfer rate.
Syntax:void SetDataTransferRateLimit(int nDataTransferRateLimit);
SetDataTransferBufferSize - Set buffer size for data transfer
Notes: Buffer size can NOT be changed while client is connected! With a bigger buffer size you can achieve higher data transfer rates, usually you don't need to adjust this setting.
Syntax:void SetDataTransferBufferSize(int nDataTransferBufferSize);
SetTimeout - Set timeout settings for connecting and data transfer
Syntax:void SetTimeout(int nConnectTimeout, int nConnectHandshakeTimeout, int nDataTransferTimeout);
SetProxy - Set proxy settings
Notes: Where available a connection is optionally done via a HTTP proxy.
Syntax:void SetProxy(const char* szProxyAddress, int nProxyPort, bool bUseProxy = true);
void SetProxyAdvanced(const char* szProxyBypassList, bool bProxyResolveDns);
Get - Send GET request to web server
Syntax:bool Get(const char* szUrl);
Head - Send HEAD request to web server
Syntax:bool Head(const char* szUrl);
Post - Send POST request to web server
Syntax:bool Post(const char* szUrl);
Request - Send abitrary request to web server
Notes: The request will fail if the last one is still running. URL should be in the format 'http://user:pass@hostname:port/location', authentication and port number are optional.
Syntax:bool Request(const char* szMethod, const char* szUrl);
DisconnectServer - Disconnect from web server, force immediate disconnect
Notes: Open files and used resources will be released.
Syntax:void DisconnectServer();
GetResponseProtocol - Return HTTP protocol version number from web server
Notes: High byte major version, low byte minor version.
Syntax:int GetResponseProtocol() const;
GetResponseStatusCode - Return HTTP status code from web server
Notes: For a list of common status codes see class CSocketServerHttp.
Syntax:int GetResponseStatusCode() const;
GetResponseHeaders - Return all HTTP headers from web server
Syntax:CString8 GetResponseHeaders() const;
GetResponseHeader - Return HTTP response header
Notes: Returns header value or empty string if not found.
Syntax:const MEMBLOCK GetResponseHeader(const char* szKeyName, int nKeyLen = -1) const;
GetContentData - Return pointer to content data, memory streams only
Syntax:BYTE* GetContentData();
GetContentDataSize - Return size of available content data
Notes: Returns the current size of content data in the output stream. In case of a partial file transfer with mode STREAM_RESUME this is the size counting from the beginning of the stream.
Syntax:int GetContentDataSize() const;
GetContentDataReceived - Return size of downloaded content data
Syntax:int GetContentDataReceived() const;
GetContentLength - Return size of expected content data, NOT downloaded data
Notes: Returns 0 if the content length is unknown or the expected content data actually has a size of 0 bytes.
Syntax:int GetContentLength() const;
IsContentLengthKnown - Check if content length is known
Notes: Content length can be unknown if the web server is unable to predict it, e.g. for compressed or dynamically generated content.
Syntax:bool IsContentLengthKnown() const;
IsRequesting - Check if a request is running
Syntax:bool IsRequesting() const;
IsOnline - Check if socket is online
Syntax:bool IsOnline() const;
GetSocketStatus - Return socket status
Syntax:int GetSocketStatus() const;

2.12. CSocketClientSmtp

Description: SMTP client to send email to a mail server
Header file: PichatCore_SocketClientSmtp.h, namespace PichatCore
Comments: This class implements a SMTP client as defined in RFC 5321, RFC 4954. It supports persistent connection, traffic limitation, authentication and connection via a HTTP proxy. It is possible to send emails to one or multiple recipients. Derive your own class from this and overload the virtual methods you need. Generally, if you overload a virtual method call the base class method first. For further information please see network classes in the SharkEngine library.
These virtual methods exist:
  • OnRequest() informs when request has been completed or failed
  • OnClientClose() informs when client is disconnected from server
Construction
Syntax:CSocketClientSmtp();
Constants
socket status:
SOCKET_NONEserver not connected
SOCKET_HANDSHAKE_WAITwaiting for welcome
SOCKET_HANDSHAKE_HELOsending initialisation
SOCKET_HANDSHAKE_AUTHsending authentication
SOCKET_HANDSHAKE_SENDERsending envelope sender
SOCKET_HANDSHAKE_RECIPIENTsending envelope recipient
SOCKET_HANDSHAKE_REQUESTsending request
SOCKET_DATA_TRANSFERsending content data
SOCKET_DATA_RESPONSEwaiting for response
SOCKET_KEEP_ALIVEwaiting for next request
 
SMTP authentication types:
SMTP_AUTH_NONEno authentication used
SMTP_AUTH_PLAINPLAIN authentication, Base64 encoded
SMTP_AUTH_LOGINLOGIN authentication, Base64 encoded
SetRequestServer - Set SMTP server, email domain and authentication
Syntax:void SetRequestServer(const char* szHostAddress, int nHostPort, const char* szDomain, const char* szUsername = "", const char* szPassword = "");
SetRequestEnvelope - Set sender and recipient email addresses
Notes: It's possible to configure multiple recipients with comma separated text. A SMTP server will accept at least 100 recipients in a single request, for more you should send multiple requests.
Syntax:void SetRequestEnvelope(const char* szSender, const char* szRecipients);
SetRequestData - Set email headers and body
Notes: Email headers and body must be separated by double newline. Any newline in text will be converted to SMTP specific newline format (CRLF).
Syntax:void SetRequestData(const void* pBuffer, int nBufferLen = -1);
SetDataTransferRateLimit - Set traffic limitations
Notes: Data transfer rate can be set to an upper limit (bytes per second), 0 means unlimited transfer rate.
Syntax:void SetDataTransferRateLimit(int nDataTransferRateLimit);
SetDataTransferBufferSize - Set buffer size for data transfer
Notes: Buffer size can NOT be changed while client is connected! With a bigger buffer size you can achieve higher data transfer rates, usually you don't need to adjust this setting.
Syntax:void SetDataTransferBufferSize(int nDataTransferBufferSize);
SetTimeout - Set timeout settings for connecting and data transfer
Syntax:void SetTimeout(int nConnectTimeout, int nConnectHandshakeTimeout, int nDataTransferTimeout);
SetProxy - Set proxy settings
Notes: Where available a connection is optionally done via a HTTP proxy.
Syntax:void SetProxy(const char* szProxyAddress, int nProxyPort, bool bUseProxy = true);
void SetProxyAdvanced(const char* szProxyBypassList, bool bProxyResolveDns);
Request - Send email request to mail server
Notes: The request will fail if the last one is still running.
Syntax:bool Request(bool bPersistentConnection = true);
DisconnectServer - Disconnect from mail server, force immediate disconnect
Notes: Configured email addresses, headers and body will be reset.
Syntax:void DisconnectServer();
GetResponseStatusCode - Return SMTP status code from mail server
Notes: For a list of common status codes see class CSocketServerSmtp.
Syntax:int GetResponseStatusCode() const;
GetAuthenticationType - Return authentication type used with mail server
Syntax:int GetAuthenticationType() const;
IsRequesting - Check if a request is running
Syntax:bool IsRequesting() const;
IsOnline - Check if socket is online
Syntax:bool IsOnline() const;
GetSocketStatus - Return socket status
Syntax:int GetSocketStatus() const;

2.13. CSocketServerHttp

Description: Web server handling incoming HTTP requests
Header file: PichatCore_SocketServerHttp.h, namespace PichatCore
Comments: This class implements a basic HTTP 1.1 server as defined in RFC 1945, RFC 2616, RFC 2617. It supports persistent connections, on the fly compression, basic authentication, partial file transfer and directory browsing. Derive your own class from this and overload the virtual methods you need. Generally, if you overload a virtual method call the base class method first. For further information please see network classes in the SharkEngine library.
These virtual methods exist:
  • OnUserAuthentication() called when user authentication is required
  • OnServerLocation() called when request has been received
  • OnServerDirectoryResponse() called when directory content is sent
  • OnServerStatusResponse() called when HTTP status response is sent
  • OnServerOutput() called for logging and debugging output
Construction
Syntax:CSocketServerHttp();
Constants
STATUS_HTTP_NONEHTTP status codes
STATUS_HTTP_OK
STATUS_HTTP_NO_CONTENT
STATUS_HTTP_PARTIAL_CONTENT
STATUS_HTTP_MOVED_PERMANENTLY
STATUS_HTTP_MOVED_TEMPORARILY
STATUS_HTTP_NOT_MODIFIED
STATUS_HTTP_TEMPORARY_REDIRECT
STATUS_HTTP_BAD_REQUESTHTTP client errors
STATUS_HTTP_UNAUTHORISED
STATUS_HTTP_FORBIDDEN
STATUS_HTTP_FILE_NOT_FOUND
STATUS_HTTP_METHOD_NOT_ALLOWED
STATUS_HTTP_REQUEST_TIMEOUT
STATUS_HTTP_CONFLICT
STATUS_HTTP_REQUEST_URI_TOO_LONG
STATUS_HTTP_INTERNAL_SERVER_ERRORHTTP server errors
STATUS_HTTP_NOT_IMPLEMENTED
STATUS_HTTP_SERVICE_UNAVAILABLE
 
request type:
HTTP_NONEno request
HTTP_GETrequest for data
HTTP_HEADrequest for headers only
HTTP_POSTrequest with additional data
HTTP_OPTIONSrequest for communication options
HTTP_TRACErequest for diagnostic information
HTTP_UNKNOWNunknown request
HTTP_BADbad request
HTTP_CUSTOMcustom types, free for use
 
EVENT_MASK_DEFAULT = FD_READ | FD_WRITE | FD_ACCEPT | FD_CLOSE
LISTEN_BACKLOG_DEFAULT = 250
Open - Open server socket
Syntax:bool Open(int nSocketPort, int nSocketType = SOCK_STREAM, int nEventMask = EVENT_MASK_DEFAULT, const char* szSocketAddress = NULL);
Close - Close server socket, force immediate close
Syntax:void Close(int nErrorCode = ERROR_ECLOSE);
Listen - Listen on port
Syntax:void Listen(int nConnectionBacklog = LISTEN_BACKLOG_DEFAULT);
SetServerRoot - Set web server root directory
Syntax:void SetServerRoot(CString8 sServerHttpRoot);
SetServerLocationProtected - Set web server location for password protected files
Syntax:void SetServerLocationProtected(CString8 sServerHttpLocation);
SetServerMimeFile - Set server MIME file, none for built-in
Syntax:void SetServerMimeFile(CString8 sServerHttpMimeFile);
SetServerDirectoryBrowsing - Specify if server shows directory contents
Syntax:void SetServerDirectoryBrowsing(bool bServerDirectoryBrowsing);
SetDebugMode - Specify if server logs debug information
Syntax:void SetDebugMode(bool bDebugMode);
SetMaxSocket - Set maximum number of incoming sockets
Syntax:void SetMaxSocket(int nMaxSockets);
SetTimeout - Set timeout settings
Syntax:void SetTimeout(int nHandshakeTimeout, int nDisconnectTimeout, int nDataTransferTimeout);
SetDataTransferKeepAlive - Set keep alive settings
Syntax:void SetDataTransferKeepAlive(int nDataTransferKeepAlive, int nDataTransferPersistentMax);
SetDataTransferBufferSize - Set buffer size for data transfer
Notes: Buffer size can NOT be changed while server is online! With a bigger buffer size you can achieve higher data transfer rates, you might want to adjust this setting for very fast data transfer.
Syntax:void SetDataTransferBufferSize(int nDataTransferBufferSize);
SetDataCompression - Set file compression settings
Notes: Set file size max to 0 to disable on the fly file compression.
Syntax:void SetDataCompression(int nDataCompressionFileSizeMin, int nDataCompressionFileSizeMax, CString8 sDataCompressionFilesExclude);
SetOutputFilter - Set IP address filter for logging output
Notes: This method allows to control the generated logging output. A netmask can be between 0-32, where 32 means that IP addresses are unfiltered.
Syntax:void SetOutputFilter(int nFilterIpNetmask);
SetForwarderAddress - Set IP address of SSL accelerator or reverse HTTP proxy for incoming traffic
Notes: This method allows to evaluate 'X-Forwarded-For' and 'X-Forwarded-Proto' headers from a trustworthy SSL accelerator or reverse HTTP proxy, i.e. to determine the external IP address and protocol of a request. The second argument defines a proxy that forwards only HTTPS connections.
Syntax:void SetForwarderAddress(CString8 sFollowXForwardedFor, CString8 sAlwaysXForwardedSecure);
SetWebPageGenerated - Set settings for server generated web and error pages
Syntax:void SetWebPageGenerated(CString8 sShortcutIcon, CString8 sStyleSheet, CString8 sWebPageHeader, CString8 sWebPageFooter);
GetServerStartTime - Return server start time
Syntax:time_t GetServerStartTime() const;
GetTrafficReceived - Return number of bytes received
Notes: The first version returns the total number of bytes received, the second version returns the number of bytes before compression. However, both numbers are the same for a web server due to protocol limitations.
Syntax:DWORD GetTrafficReceived() const;
DWORD GetTrafficReceivedUncompressed() const;
GetTrafficSent - Return number of bytes sent
Notes: The first version returns the total number of bytes sent, the second version returns the number of bytes before compression.
Syntax:DWORD GetTrafficSent() const;
DWORD GetTrafficSentUncompressed() const;
IsDebugMode - Check if server runs in debug mode
Syntax:bool IsDebugMode() const;
IsStartError - Check if start error has happened
Syntax:bool IsStartError() const;
IsOnline - Check if server is online
Syntax:bool IsOnline() const;
CheckLocation - Check if location matches
Syntax:static bool CheckLocation(const char* szLocationRequest, const char* szLocation, bool* pbMatchCase = NULL);
CheckNotModified - Check if data was modified since last time
Syntax:static bool CheckNotModified(const CString8& sIfModifiedSince, time_t tLastModified);

2.14. CSocketServerSmtp

Description: Mail server status codes
Header file: PichatCore_SocketClientSmtp.h, namespace PichatCore
Constants
STATUS_SMTP_NONESMTP status codes
STATUS_SMTP_STATUS
STATUS_SMTP_HELP
STATUS_SMTP_WELCOME
STATUS_SMTP_QUIT
STATUS_SMTP_AUTHENTICATED
STATUS_SMTP_OK
STATUS_SMTP_OK_USER_NOT_LOCAL
STATUS_SMTP_OK_UNVERIFIED
STATUS_SMTP_CONTINUE
STATUS_SMTP_DATA
STATUS_SMTP_ERRORSMTP temporary errors
STATUS_SMTP_SERVICE_NOT_AVAILABLE
STATUS_SMTP_MAILBOX_NOT_AVAILABLE
STATUS_SMTP_REQUEST_NOT_POSSIBLE
STATUS_SMTP_STORAGE_NOT_AVAILABLE
STATUS_SMTP_AUTHENTICATION_NOT_POSSIBLE
STATUS_SMTP_ARGUMENT_NOT_POSSIBLE
STATUS_SMTP_BAD_REQUESTSMTP permanent errors
STATUS_SMTP_BAD_ARGUMENT
STATUS_SMTP_COMMAND_NOT_IMPLEMENTED
STATUS_SMTP_BAD_SEQUENCE
STATUS_SMTP_ARGUMENT_NOT_IMPLEMENTED
STATUS_SMTP_AUTHENTICATION_REJECTED
STATUS_SMTP_AUTHENTICATION_FAILED
STATUS_SMTP_MAILBOX_FAILED
STATUS_SMTP_USER_NOT_LOCAL
STATUS_SMTP_STORAGE_FAILED
STATUS_SMTP_MAILBOX_INVALID
STATUS_SMTP_TRANSACTION_FAILED
STATUS_SMTP_BAD_ADDRESS

3.1. IApplicationInterface

Description: Application interface (Pichat API) with access to chat functionality
Header file: PichatCore_ChatInterfaces.h, namespace PichatCore
Comments: Application and plugins run in the same thread context. API methods must be called from this thread context only, an exception is AsyncNotify() which can be called from any thread. Many things in the chat happen dynamically and you can register handlers to react on such chat actions. For further information about the chat please see Pichat user handbook and chat configuration.
These server information are available in the API:
(Information marked with * are available both as text string and numerical value)
chat_chatroom_defaultname of default chatroom, chat server entrance
chat_chatroom_bannedname of chatroom for banned users
chat_interestskeywords with interests
chat_languagerequested language, ISO639
chat_language_charsetcharset of language (e.g. ISO-8859-1)
chat_languages_preferredlanguages preferred
chat_location_chatweb server location for webchat
chat_location_mediaweb server location for graphics and sounds
chat_location_statusweb server location for status page
chat_location_protectedweb server location for password protected files
chat_server_http_rootweb server root directory
chat_server_namechat server name
chat_server_versionchat server version
chat_server_welcomechat server welcome message
chat_web_page_headerheader for web pages
chat_web_page_footerfooter for web pages
There are even more information with an extended query:
chat_activity*chat activity of last hour (percent)
chat_chatroom_number*permanent chatroom number
chat_chatroom_nameXchatroom name (X = number of permanent chatroom)
chat_chatroom_topicXchatroom topic (")
chat_chatroom_user_listXchatroom users (")
chat_chatroom_user_numberX*chatroom user number (")
chat_port_chat*listening port of chat server (TCP/UDP)
chat_port_http*listening port of built-in web server (TCP)
chat_server_dedicated*chat is running as dedicated server?
chat_server_modechat server mode (open/members/closed)
chat_server_uptime*time chat server is running (seconds)
chat_user_nicknameXnickname of user (X = number of user)
chat_user_number*current user number
chat_user_peak*highest user number since server was started
chat_user_max*maximum number of users in chat
chat_user_served*number of users served
ProcessChatCommand - Process chat command
Syntax:virtual void ProcessChatCommand(const char* szText, bool bAutomaticCreated = false, bool bMyChat = false) = 0;
SetCoreCommandHandler - Set command handler for chat plugin
Notes: For plugins interested in commands, see ICoreCommandInterface. You can optionally specify a help index and a menu. The help index is shown when someone sends 'help' to a plugin, it's a space separated list with available plugin commands. The menu is shown in the user interface, it consists of menu text with type (0=disabled, 1=enabled, 2=checked) and chat commands, comma separated text. Menu text '----' stands for a separator, '$' in text will be replaced with plugin name, special characters can be escaped with backslash (e.g. '\54' or '\44') and multiple menu entries are separated by newline character.
Syntax:virtual void SetCoreCommandHandler(IPluginInterface* pPlugin, ICoreCommandInterface* pCommandHandler, const char* szHelpIndex = NULL, const char* szMenuCommands = NULL) = 0;
SetCoreServerHandler - Set server handler for chat plugin
Notes: For plugins interested in actions, see ICoreServerInterface.
Syntax:virtual void SetCoreServerHandler(IPluginInterface* pPlugin, ICoreServerInterface* pServerHandler) = 0;
SetCoreAuthenticationHandler - Set authentication handler for chat plugin
Notes: For plugins interested in authentication, see ICoreAuthenticationInterface.
Syntax:virtual void SetCoreAuthenticationHandler(IPluginInterface* pPlugin, ICoreAuthenticationInterface* pAuthenticationHandler) = 0;
AsyncNotify - Request a chat plugin event
Notes: This method is thread safe, you can call it from any thread. You need to set a command handler first, OnChatPluginNotify() will be called for each event requested. Also see ICoreCommandInterface.
Syntax:virtual void AsyncNotify(IPluginInterface* pPlugin, int nStatusCode) = 0;
AddLocation - Add web server location
Notes: Plugins are able to transfer data via the local web server. You need to set a server handler first, OnHttpServer() will be called for each matching request. Also see ICoreServerInterface.
Syntax:virtual void AddLocation(IPluginInterface* pPlugin, const char* szLocation) = 0;
RemoveLocation - Remove web server location
Syntax:virtual void RemoveLocation(IPluginInterface* pPlugin, const char* szLocation) = 0;
AddBot - Add bot
Notes: Plugins are able to create bots on the local chat server, for example to interact with users. Bots are normal chat users, authentication as registered user is optional and should be in the format 'user:pass'. Also see ICoreBotInterface.
Syntax:virtual void AddBot(IPluginInterface* pPlugin, ICoreBotInterface* pBot, const char* szNickname, const char* szChatroom = NULL, const char* szLanguage = NULL, const char* szAuthentication = NULL, bool bAdmin = false) = 0;
RemoveBot - Remove bot
Syntax:virtual void RemoveBot(IPluginInterface* pPlugin, ICoreBotInterface* pBot) = 0;
SendBotInput - Send bot input or command to chat server
Syntax:virtual void SendBotInput(const char* szText, ICoreBotInterface* pBot) = 0;
LogServer - Write to chat server logfile
Notes: The chat actions CHAT_NOTICE, CHAT_ERROR, CHAT_DEBUG are available for logging. There are some conventions to avoid flooding the logfile: Use CHAT_NOTICE very seldom, CHAT_ERROR when necessary and CHAT_DEBUG only if the server runs in debug mode. Each debug entry must be prefixed with full class and method name.
Syntax:virtual void LogServer(int nLogAction, const char* szText) = 0;
GetIniFileName - Return INI file name for plugin settings
Syntax:virtual CString8 GetIniFileName() const = 0;
FindServerLanguage - Return ID from language name
Syntax:virtual int FindServerLanguage(const char* szLanguageName, bool bAutoLoad = false) = 0;
GetServerString - Get text string or numerical value with server information
Notes: For a list of available server information see above. String buffer will always be Null terminated.
Syntax:virtual CString8 GetServerString(const char* szKeyName, bool bExtended = false, int nLanguageID = 0) const = 0;
virtual bool GetServerString(const char* szKeyName, bool bExtended, int nLanguageID, char* pBuffer, int nBufferLen) const = 0;
virtual int GetServerValue(const char* szKeyName, bool bExtended = false) const = 0;
GetUserString - Get text string or numerical value with information of registered user
Notes: Returns information from user profile, supports arbitrary meta data. String buffer will always be Null terminated.
Syntax:virtual CString8 GetUserString(const char* szNickname, const char* szKeyName) const = 0;
virtual bool GetUserString(const char* szNickname, const char* szKeyName, char* pBuffer, int nBufferLen) const = 0;
virtual int GetUserValue(const char* szNickname, const char* szKeyName) const = 0;
SetUserString - Set string or numerical value with information of registered user
Notes: An empty string removes the key.
Syntax:virtual void SetUserString(const char* szNickname, const char* szKeyName, const char* szString) = 0;
virtual void SetUserValue(const char* szNickname, const char* szKeyName, int nValue) = 0;
FlushUser - Store any pending changes of registered user
Notes: User information changes will be automatically flushed when user logs out.
Syntax:virtual void FlushUser(const char* szNickname) = 0;
GetUserName - Return user name of registered user
Notes: Returns user name or empty string if the user is not logged in.
Syntax:virtual CString8 GetUserName(const char* szNickname) const = 0;
GetUserLanguage - Return language of user
Notes: Returns language name (ISO639) or empty string if the user does not exist.
Syntax:virtual CString8 GetUserLanguage(const char* szNickname) const = 0;
GetUserAwayStatus - Return away status of user
Notes: Returns user away status or STATUS_OFFLINE if the user does not exist, see ChatActions::User.
Syntax:virtual int GetUserAwayStatus(const char* szNickname) const = 0;
GetUserType - Return type of user
Notes: Returns chat user type or USER_NONE if the user does not exist, see ChatActions::User.
Syntax:virtual int GetUserType(const char* szNickname) const = 0;
IsUserZombie - Check if user is a zombie
Syntax:virtual bool IsUserZombie(const char* szNickname) const = 0;
IsUserVisitor - Check if user is a vistor
Syntax:virtual bool IsUserVisitor(const char* szNickname) const = 0;
IsUserNormal - Check if user is a normal user
Syntax:virtual bool IsUserNormal(const char* szNickname) const = 0;
IsUserModerator - Check if user is a moderator
Syntax:virtual bool IsUserModerator(const char* szNickname) const = 0;
IsUserAdmin - Check if user is a chat admin
Syntax:virtual bool IsUserAdmin(const char* szNickname) const = 0;
IsUserRegistered - Check if user is a registered user
Syntax:virtual bool IsUserRegistered(const char* szNickname) const = 0;
IsDebugMode - Check if server runs in debug mode
Syntax:virtual bool IsDebugMode() const = 0;

3.2. ICoreAuthenticationInterface

Description: Interface to receive user authentication requests
Header file: PichatCore_ChatInterfaces.h, namespace PichatCore
OnFindUserAuthentication - Check if user authentication exists
Syntax:virtual bool OnFindUserAuthentication(const char* szUserName) = 0;
OnCheckUserAuthentication - Check if user authentication is correct
Notes: Returns true if user exists and sets authentication status and user type accordingly. Also see ChatActions::User.
Syntax:virtual bool OnCheckUserAuthentication(const char* szUserName, const char* szPassword, const char* szHostname, unsigned long lRemoteAddr, int& nAuthenticationStatus, int& nUserType) = 0;
OnGetUserAuthenticationMetaData - Get user meta data
Notes: Meta data is a comma separated list in the format 'key=value,key=value'.
Syntax:virtual bool OnGetUserAuthenticationMetaData(const char* szUserName, CString8& sMetaData) = 0;
OnSetUserAuthenticationMetaData - Set user meta data
Syntax:virtual bool OnSetUserAuthenticationMetaData(const char* szUserName, const char* szMetaData) = 0;

3.3. ICoreBotInterface

Description: Interface for bots
Header file: PichatCore_ChatInterfaces.h, namespace PichatCore
OnChatText - Chat text
Syntax:virtual void OnChatText(const char* szText, int nTextType) = 0;
OnChatPrivMessage - Private message text
Syntax:virtual void OnChatPrivMessage(const char* szTextData) = 0;
OnChatLanguage - Language was set
Syntax:virtual void OnChatLanguage(const char* szLanguage) = 0;
OnChatNick - Nickname was set
Syntax:virtual void OnChatNick(const char* szNickname) = 0;
OnChatNickChange - Nickname of chatroom user has changed
Syntax:virtual void OnChatNickChange(const char* szUserData) = 0;
OnChatChatroom - Chatroom was set
Syntax:virtual void OnChatChatroom(const char* szChatroomName) = 0;
OnChatChatroomTopic - Chatroom topic has changed
Syntax:virtual void OnChatChatroomTopic(const char* szTopic) = 0;
OnChatUserNumber - Chatroom user number has changed
Syntax:virtual void OnChatUserNumber(int nUser) = 0;
OnChatJoin - User has joined chatroom
Syntax:virtual void OnChatJoin(const char* szNickname, int nAwayStatus, bool bReconnecting) = 0;
OnChatLeave - User has left chatroom
Syntax:virtual void OnChatLeave(const char* szNickname, int nAwayStatus, bool bReconnecting) = 0;
OnChatNetwork - Network status has changed
Syntax:virtual void OnChatNetwork(int nStatus) = 0;

3.4. ICoreCommandInterface

Description: Interface to receive plugin commands and notifications
Header file: PichatCore_ChatInterfaces.h, namespace PichatCore
OnChatPluginCommand - Handle plugin command from application
Syntax:virtual void OnChatPluginCommand(const char* szTextData) = 0;
OnChatPluginNotify - Handle plugin notification
Syntax:virtual void OnChatPluginNotify(int nStatusCode) = 0;

3.5. ICoreServerInterface

Description: Interface to receive chat and web server actions
Header file: PichatCore_ChatInterfaces.h, namespace PichatCore
OnChatServer - Handle chat server actions
Syntax:virtual void OnChatServer(int nChatAction, ChatActions::ChatCallbackData data) = 0;
OnHttpServer - Handle web server requests
Syntax:virtual void OnHttpServer(int nChatAction, ChatActions::HttpCallbackData data) = 0;

3.6. IDataGeneratorInterface

Description: Interface for data generators
Header file: PichatCore_ChatInterfaces.h, namespace PichatCore
GetLocation - Return location string
Syntax:virtual const char* GetLocation() const = 0;
GetLocationArguments - Return location arguments, URL encoded
Syntax:virtual const char* GetLocationArguments() const = 0;
GetHeader - Return request header
Notes: Returns header value or empty string if not found.
Syntax:virtual const MEMBLOCK GetHeader(const char* szKeyName, int nKeyLen = -1) const = 0;
GetRemoteAddr - Return address of remote peer
Notes: Returns the IP address of client/proxy in network order.
Syntax:virtual unsigned long GetRemoteAddr() const = 0;
GetOutputStream - Return output stream
Notes: This method gives access to an output stream, you can provide data as file or memory. Memory is typically used for dynamic generated data.
Syntax:virtual SharkEngine::CFileStream& GetOutputStream() = 0;
SendStreamResponse - Send response with data in output stream
Notes: The given file name is used to detect content type and compression.
Syntax:virtual void SendStreamResponse(const char* szStreamName, const char* szContentType = NULL, const char* szExtraHeaders = NULL, time_t tLastModified = 0) = 0;
SendStatusResponse - Send response with status
Syntax:virtual void SendStatusResponse(int nStatusCode, const char* szText = NULL) = 0;

3.7. IDataLanguageInterface

Description: Interface with access to languages and text strings
Header file: PichatCore_ChatInterfaces.h, namespace PichatCore
FindLanguage - Return ID from language name
Syntax:virtual int FindLanguage(const char* szLanguageName, bool bAutoLoad = false) = 0;
FindLanguageName - Return name from language ID
Syntax:virtual const char* FindLanguageName(int nLanguageID) const = 0;
GetStringLanguage - Return text string
Syntax:virtual const char* GetStringLanguage(int nTextID, int nLanguageID) const = 0;

3.8. IDataReceiveInterface

Description: Interface for data receivers
Header file: PichatCore_ChatInterfaces.h, namespace PichatCore
OnReceiveLine - Handle received text line
Syntax:virtual void OnReceiveLine(char* szText) = 0;

3.9. IPluginInterface

Description: Interface for plugins
Header file: PichatCore_ChatInterfaces.h, namespace PichatCore
Comments: Plugins extend the chat with additional features. Derive your own plugin from this interface and export a factory function called CreatePlugin() to create an instance of the plugin. Once a plugin is successfully created it has access to chat functionality, see IApplicationInterface.
Construction
Syntax:extern "C" PichatCore::IPluginInterface* CreatePlugin(PichatCore::IApplicationInterface* pApi);
DeleteThis - Destroy plugin instance
Syntax:virtual void DeleteThis() const = 0;
GetVersionName - Return plugin version name
Notes: Text string in the format 'category.type', where category describes the offered service such as 'bot' or 'webcam'.
Syntax:virtual const char* GetVersionName() const = 0;
GetVersionDescription - Return plugin version description
Syntax:virtual const char* GetVersionDescription() const = 0;
GetVersionNumber - Return plugin version number
Notes: Byte 2 major version, byte 1 minor version, byte 0 release number.
Syntax:virtual int GetVersionNumber() const = 0;
GetAuthor - Return plugin author or copyright information
Syntax:virtual const char* GetAuthor() const = 0;

3.10. Misc

Description: Miscellaneous helper methods
Header file: PichatCore_Definitions.h, namespace PichatCore
GetLibraryVersion - Return library version of PichatCore
Syntax:const char* GetLibraryVersion();

Appendix A: Code examples

Pichat plugin using interface IPluginInterface, basic implementation:
using namespace PichatCore; namespace Plugin { class CImplementation : public IPluginInterface { public: CImplementation(IApplicationInterface* pApi) { //TODO: more code here } virtual ~CImplementation() { } virtual void DeleteThis() const { delete this; } virtual const char* GetVersionName() const { return "Example.Simple"; } virtual const char* GetVersionDescription() const { return "Chat plugin example"; } virtual int GetVersionNumber() const { return 0x000101; } //note: v0.1.1 virtual const char* GetAuthor() const { return "Created by Moaky Moak"; } }; }; PLUGINEXAMPLE_EXPORT IPluginInterface* CreatePlugin(IApplicationInterface* pApi) { return new Plugin::CImplementation(pApi); }
HTTP client class CSocketClientHttp, downloading file from web server:
using namespace PichatCore; class CClientHttp : public CSocketClientHttp { public: void OnRequest(int nErrorCode) { CSocketClientHttp::OnRequest(nErrorCode); if(nErrorCode == ERROR_SUCCESS) { printf("Request completed, status %d, size %d\n", GetResponseStatusCode(), GetContentDataSize()); } else { printf("Request failed\n"); } } }; CClientHttp client; client.SetOutputStream("pichat_updates.xml"); client.Get("http://www.pichat.net/siterss/");
SMTP client class CSocketClientSmtp, sending email to mail server:
using namespace PichatCore; class CClientSmtp : public CSocketClientSmtp { public: void OnRequest(int nErrorCode) { CSocketClientSmtp::OnRequest(nErrorCode); if(nErrorCode == ERROR_SUCCESS) { printf("Request completed, status %d\n", GetResponseStatusCode()); } else { printf("Request failed\n"); } } }; CClientSmtp client; client.SetRequestServer("mail.example.com", 25, "example.com"); client.SetRequestEnvelope("sender@example.com", "receipient@example.com"); client.SetRequestData("Subject:Test email\n\nHi! I am hungry, please send some pizza."); client.Request();
There are more code examples in the Pichat SDK.
For further information and feedback please contact me.
Pichat is a simple to use chat software. It comes with integrated LAN messenger and webchat. The chat server supports multiple chatrooms, text formatting with smileys and a user-friendly webchat (HTML, CSS, DOM, JavaScript). The webchat works with nearly any web browser, easily integrated into your design, no PHP/Flash/Java required. Software for free information exchange for Linux and Windows. Built with Yellow