PichatCore documentation, generated with mkdocument
Last update 31/Mar/2011 by Mark Seuffert
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
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.
Constants
| DATA_NOT_FOUND | section not found |
| DATA_DEFAULT | default 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
Clear - Clear text container and remove all text strings
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; |
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_FOUND | section not found |
| DATA_DEFAULT | default 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
Clear - Clear text container and remove all text strings
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); |
Description: Namespace with chat actions
Header file: PichatCore_ChatActions.h, namespace PichatCore::ChatActions
Constants
| chat actions (* = for chat admins only): |
| CHAT_NONE | none or invalid |
| CHAT_NOTICE | generic notice information |
| CHAT_DEBUG | generic debug information |
| CHAT_ERROR | generic error information |
| CHAT_TEXT | chat text |
| CHAT_CLEAR | clear text |
| CHAT_PRIVMESSAGE | private message text |
| CHAT_INSTMESSAGE | instant message text |
| CHAT_UNKNOWN | unknown server action |
| CHAT_LANGUAGE | language was set |
| CHAT_NICK | nickname was set |
| CHAT_NICKCHANGE | nickname of chatroom user has changed |
| CHAT_USERMODE | user mode was set |
| CHAT_USERMODECHANGE | user mode of chatroom user has changed |
| CHAT_AWAY | away status was set |
| CHAT_AWAYCHANGE | away status of chatroom users has changed |
| CHAT_CHATROOM | chatroom was set |
| CHAT_CHATROOMMODE | chatroom mode has changed |
| CHAT_CHATROOMTOPIC | chatroom topic has changed |
| CHAT_CHATROOMLIST | chatroom list has changed |
| CHAT_USERLIST | chatroom user list has changed |
| CHAT_USERNUMBER | chatroom user number has changed |
| CHAT_JOIN | user has joined chatroom |
| CHAT_LEAVE | user has left chatroom |
| CHAT_PING | ping from user |
| CHAT_PONG | pong from user, just 4 fun |
| CHAT_PINGREPLY | ping reply from user |
| CHAT_DEBUGMODE | debug mode has changed |
| CHAT_NETWORK | network status has changed |
| CHAT_SERVER_STATUS | server status has changed |
| CHAT_SERVER_PING | server connection test |
| CHAT_SERVER_USERNUMBER | server 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_COMMAND | client has issued a command |
| CHAT_ACTION_CUSTOM | custom actions, free for use |
| |
| chat text color codes: |
| TEXT_COLOR_NONE | no special text color |
| TEXT_COLOR_1 | text color one, negative emphasis or warning (e.g. red) |
| TEXT_COLOR_2 | text color two, positive emphasis (e.g. green) |
| TEXT_COLOR_3 | text color three, neutral emphasis (e.g. blue) |
| TEXT_COLOR_4 | text color four, alternative emphasis (e.g. yellow) |
| TEXT_COLOR_CUSTOM | custom colors, free for use |
| |
| generic chat actions types: |
| SERVER_NONE | no special type |
| SERVER_CHAT_LOGFILE | action for chat server logfile (if available) |
| SERVER_HTTP_LOGFILE | action for web server logfile (if available) |
| SERVER_TYPE_CUSTOM | custom types, free for use |
Description: Namespace with chat network status
Header file: PichatCore_ChatActions.h, namespace PichatCore::ChatActions::Network
Constants
| chat network status: |
| STATUS_CLOSED | client closed |
| STATUS_CLOSED_RECONNECT | client closed, waiting for reconnect |
| STATUS_UNCONNECTED | client not connected |
| STATUS_CLOSING | client closing/disconnecting |
| STATUS_CONNECTING_START | client starting new connection |
| STATUS_CONNECTING_LOOKUP | client resolving hostname |
| STATUS_CONNECTING | client connecting |
| STATUS_CONNECTED | client connected to other peer |
| STATUS_CONNECTED_SESSION_START | client connected, starting handshake |
| STATUS_CONNECTED_SESSION_OK | client connected, session established |
| STATUS_CONNECTED_SESSION | client connected, user is logged in |
| STATUS_SERVER_OFFLINE | local server offline |
| STATUS_SERVER_ONLINE | local server online |
| STATUS_TYPE_CUSTOM | custom types, free for use |
Description: Namespace with chat server status codes
Header file: PichatCore_ChatActions.h, namespace PichatCore::ChatActions::Server
Constants
| STATUS_CODE_NONE | chat status codes |
| STATUS_CODE_CONNECTED_BINARY | |
| STATUS_CODE_CONNECTED_TEXT | |
| STATUS_CODE_ACCEPTED | |
| STATUS_CODE_DONE | |
| STATUS_CODE_NEXT_REQUEST | |
| STATUS_CODE_BAD_REQUEST | chat 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_ERROR | chat server errors |
| STATUS_CODE_CHAT_SERVER_CLOSED | |
| STATUS_CODE_CHAT_SERVER_FULL | |
| STATUS_CODE_CHAT_LOGIN_FAILED | |
| |
| chat modes: |
| CHAT_NONE | no valid chat mode |
| CHAT_OPEN | any user can enter the chat |
| CHAT_MEMBERS | only registered users can enter the chat |
| CHAT_CLOSED | no new users can enter the chat |
| |
| chatroom types: |
| CHATROOM_NONE | no valid chatroom type |
| CHATROOM_NORMAL | normal chatroom, any user can join and talk |
| CHATROOM_MODERATED | moderated chatroom, restricted talking |
| CHATROOM_CONFERENCE | conference chatroom, restricted joining |
Description: Namespace with chat user status
Header file: PichatCore_ChatActions.h, namespace PichatCore::ChatActions::User
Constants
| user away status: |
| STATUS_OFFLINE | user is offline |
| STATUS_ONLINE | user is online |
| STATUS_ONLINE_UNUSED2 | unused |
| STATUS_ONLINE_UNUSED3 | unused |
| STATUS_AWAY | user is away |
| STATUS_AWAY_UNUSED5 | unused |
| STATUS_AWAY_UNUSED6 | unused |
| STATUS_AWAY_UNUSED7 | unused |
| STATUS_AWAY_DND | user is away, do not disturb |
| STATUS_TYPE_CUSTOM | custom types, free for use |
| |
| user connect/reconnect status: |
| STATUS_CONNECTING | user is connecting |
| STATUS_RECONNECTING | user is reconencting |
| |
| user authentication status: |
| AUTHENTICATION_NONE | user not found |
| AUTHENTICATION_OK | user authenticated |
| AUTHENTICATION_USERNAME_FAILED | user disabled |
| AUTHENTICATION_PASSWORD_FAILED | password mismatch |
| AUTHENTICATION_ADDRESS_FAILED | address mismatch |
| AUTHENTICATION_SAFEGUARD_FAILED | safeguard on user |
| AUTHENTICATION_TYPE_CUSTOM | custom types, free for use |
| |
| chat user types: |
| USER_NONE | no valid user type |
| USER_ZOMBIE | user with many restrictions |
| USER_VISITOR | user with some restrictions |
| USER_NORMAL | user without restrictions |
| USER_MODERATOR | user with moderation rights |
| USER_ADMIN | user with administration rights |
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) |
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); |
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
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; |
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); |
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
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; |
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.
Create - Create plugin
| Syntax: | bool Create(const char* szFileName, IApplicationInterface* pApi = NULL); |
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; |
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_NONE | server not connected |
| SOCKET_HANDSHAKE_REQUEST | sending request and headers |
| SOCKET_HANDSHAKE_DATA | sending additional content data |
| SOCKET_HANDSHAKE_RESPONSE | waiting for response |
| SOCKET_HANDSHAKE_HEADERS | receiving headers |
| SOCKET_DATA_TRANSFER | receiving content data |
| SOCKET_KEEP_ALIVE | waiting for next request |
| |
| output stream modes: |
| STREAM_OVERWRITE | existing download is overwritten |
| STREAM_RESUME | existing download is continued if possible |
| |
| custom error codes: |
| ERROR_EINPUTSTREAM | reading input stream failed |
| ERROR_EOUTPUTSTREAM | writing output stream failed |
| ERROR_EDECOMPRESSION | decompression failed |
| ERROR_EBADENCODING | bad 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; |
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_NONE | server not connected |
| SOCKET_HANDSHAKE_WAIT | waiting for welcome |
| SOCKET_HANDSHAKE_HELO | sending initialisation |
| SOCKET_HANDSHAKE_AUTH | sending authentication |
| SOCKET_HANDSHAKE_SENDER | sending envelope sender |
| SOCKET_HANDSHAKE_RECIPIENT | sending envelope recipient |
| SOCKET_HANDSHAKE_REQUEST | sending request |
| SOCKET_DATA_TRANSFER | sending content data |
| SOCKET_DATA_RESPONSE | waiting for response |
| SOCKET_KEEP_ALIVE | waiting for next request |
| |
| SMTP authentication types: |
| SMTP_AUTH_NONE | no authentication used |
| SMTP_AUTH_PLAIN | PLAIN authentication, Base64 encoded |
| SMTP_AUTH_LOGIN | LOGIN 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; |
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_NONE | HTTP 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_REQUEST | HTTP 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_ERROR | HTTP server errors |
| STATUS_HTTP_NOT_IMPLEMENTED | |
| STATUS_HTTP_SERVICE_UNAVAILABLE | |
| |
| request type: |
| HTTP_NONE | no request |
| HTTP_GET | request for data |
| HTTP_HEAD | request for headers only |
| HTTP_POST | request with additional data |
| HTTP_OPTIONS | request for communication options |
| HTTP_TRACE | request for diagnostic information |
| HTTP_UNKNOWN | unknown request |
| HTTP_BAD | bad request |
| HTTP_CUSTOM | custom 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); |
Description: Mail server status codes
Header file: PichatCore_SocketClientSmtp.h, namespace PichatCore
Constants
| STATUS_SMTP_NONE | SMTP 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_ERROR | SMTP 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_REQUEST | SMTP 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 | |
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_default | | name of default chatroom, chat server entrance |
| chat_chatroom_banned | | name of chatroom for banned users |
| chat_interests | | keywords with interests |
| chat_language | | requested language, ISO639 |
| chat_language_charset | | charset of language (e.g. ISO-8859-1) |
| chat_languages_preferred | | languages preferred |
| chat_location_chat | | web server location for webchat |
| chat_location_media | | web server location for graphics and sounds |
| chat_location_status | | web server location for status page |
| chat_location_protected | | web server location for password protected files |
| chat_server_http_root | | web server root directory |
| chat_server_name | | chat server name |
| chat_server_version | | chat server version |
| chat_server_welcome | | chat server welcome message |
| chat_web_page_header | | header for web pages |
| chat_web_page_footer | | footer 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_nameX | | chatroom name (X = number of permanent chatroom) |
| chat_chatroom_topicX | | chatroom topic (") |
| chat_chatroom_user_listX | | chatroom 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_mode | | chat server mode (open/members/closed) |
| chat_server_uptime | * | time chat server is running (seconds) |
| chat_user_nicknameX | | nickname 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; |
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; |
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; |
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; |
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; |
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; |
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; |
Description: Interface for data receivers
Header file: PichatCore_ChatInterfaces.h, namespace PichatCore
OnReceiveLine - Handle received text line
| Syntax: | virtual void OnReceiveLine(char* szText) = 0; |
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; |
Description: Miscellaneous helper methods
Header file: PichatCore_Definitions.h, namespace PichatCore
GetLibraryVersion - Return library version of PichatCore
| Syntax: | const char* GetLibraryVersion(); |
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);
}
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/");
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();
For further information and feedback please contact me.
