PichatCore Documentation, generated with mkdoc
Last update 27/Jul/2008 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 chat
functionality. Shared libraries are available for C++ on Linux, BSD and Windows.
Feature highlights:
- plugin support
- chat bots to interact with users
- chat actions such as users joining and leaving a chatroom
- not binary dependent on a specific version of STL or Boost
Description: Container for text strings
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 and external files.
Constants
| DATA_NOT_FOUND | section not found |
| DATA_DEFAULT | default section |
Create - Create text container
Notes: Initialises empty container with a reference section from a
resource. The reference section will be used to verify new sections and to
make sure that text formatting arguments are correct.
| Syntax: | bool Create(HMODULE hResourceModule, int nResourceID, const char* szSectionFilter, const char* szSectionReference, int nReserveStorage = 0); |
Destroy - Destroy text container
Clear - Clear text container and remove all text strings
AddSection - Load text strings from stream
Notes: This method can be used to load text strings from file or memory.
| Syntax: | bool AddSection(SharkEngine::CFileStream& file, const char* szSectionName); |
ScanSections - Scan stream and return list of available sections
| Syntax: | CString8 ScanSections(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; |
GetTextString - Return text string
| Syntax: | const char* GetTextString(int nTextID, int nSectionID) const; |
GetSize - Return number of sections
| Syntax: | int GetSize() 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; |
Description: Namespace with chat actions
Header file: PichatCore_ChatActions.h, namespace PichatCore::ChatActions
Comments: Pichat uses chat actions to notify when something has happened. They are one
of the central ways of communication, plugins can register an interface to
receive chat actions.
Constants
| chat actions (* = for chat admins only): |
| CHAT_NONE | none or invalid |
| CHAT_TEXT | normal text |
| CHAT_CLEAR | clear text |
| CHAT_PRIVMESSAGE | private message text |
| CHAT_INSTMESSAGE | instant message text |
| CHAT_NOTICE | generic notice description |
| CHAT_DEBUG | generic debug description |
| CHAT_ERROR | generic error description |
| 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_PINGPONG | pingpong from server |
| 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_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_ADMINLOGIN | * chat admin has logged in |
| CHAT_SERVER_ADMINLOGOUT | * chat admin has logged out |
| CHAT_SERVER_ADMINCOMMAND | * chat admin has issued a command |
| CHAT_SERVER_ONLINE | * server goes online (your own chat server) |
| CHAT_SERVER_OFFLINE | * server goes offline (your own chat server) |
| CHAT_PEER_AWAYCHANGE | * away status has changed (in your local network) |
| CHAT_PEER_ONLINE | * peer goes online (in your local network) |
| CHAT_PEER_OFFLINE | * peer goes offline (in your 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 | 1st color (default, e.g. black) |
| TEXT_COLOR_2 | 2nd color (neutral status, e.g. blue) |
| TEXT_COLOR_3 | 3rd color (positive status, e.g. green) |
| TEXT_COLOR_4 | 4th color (negative status, e.g. red) |
| 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 unconnected |
| 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_ERROR | local server error |
| 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_FAILURE | |
| 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
| chat user 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_RESERVED | reserved types, do not use |
| STATUS_TYPE_CUSTOM | custom types, free for use |
| |
| user connect/reconnect status: |
| STATUS_CONNECTING | user is connecting |
| STATUS_RECONNECTING | user is reconencting |
| |
| 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 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); |
SplitAddress - Split chat server address
Notes: This method splits chat server address into authentication,
hostname, port and chatroom.
| Syntax: | void SplitAddress(const char* szText, CString8& sAuthentication, CString8& sHostname, CString8& sPort, CString8& sChatroomName, int nDefaultPort); |
SplitUrl - Split absolute URL
Notes: This method splits absolute URL into authentication, hostname, port
and location.
| Syntax: | void SplitUrl(const char* szText, CString8& sAuthentication, CString8& sHostname, CString8& sPort, 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); |
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 percentage
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); |
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); |
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); |
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* szPath); |
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); |
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 = AND, 1 = OR, 2 = EXCLUSIVE OR.
| Syntax: | void ChangeBitValue(int& nVariable, int nBits, int nOperation); |
| void ChangeBoolValue(bool& nVariable, int nOperation); |
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); |
AsText - Return value as text string
| Syntax: | CString8 AsText(int nValue) |
| CString8 AsText(DWORD dwValue) |
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 - Get plugin version name
| Syntax: | const char* GetVersionName() const; |
GetVersionDescription - Get plugin version description
| Syntax: | const char* GetVersionDescription() const; |
GetVersionNumber - Get plugin version number
| Syntax: | int GetVersionNumber() const; |
GetPtr - Return pointer to plugin
| Syntax: | void* GetPtr() const; |
IsCreated - Check if plugin instance was 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 basic HTTP 1.1 client as defined in RFC 1945,
RFC 2616, RFC 2617. It supports persistent connections, compression, basic
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() inform when data download has stopped
Construction
| Syntax: | CSocketClientHttp(); |
Constants
| socket status: |
| SOCKET_NONE | web 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 too.
| 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: 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:
- OnCheckUserPermission() called when authentication is required
- OnServerLocation() called when request has been received
- 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); |
SetForwarderAddress - Set reverse proxy for incoming traffic
Notes: This method allows to evaluate 'X-Forwarded-For' header from a
trustworthy proxy, i.e. to determine the external IP address of a request.
| Syntax: | void SetForwarderAddress(CString8 sFollowXForwardedFor); |
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: 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.
| Syntax: | virtual void SetCoreCommandHandler(IPluginInterface* pPlugin, ICoreCommandInterface* pCommandHandler) = 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; |
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* szAuthentication = NULL, const char* szChatroom = 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; |
FindServerLanguage - Return ID from language name
| Syntax: | virtual int FindServerLanguage(const char* szLanguageName, bool bAutoLoad = false) = 0; |
GetServerString - Get string with server information
Notes: For a list of available server information see above.
| 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; |
GetServerValue - Get value with server information
Notes: For a list of available server information see above.
| Syntax: | virtual int GetServerValue(const char* szKeyName, bool bExtended = false) const = 0; |
GetUserAwayStatus - Return away status of user
Notes: Returns chat user status or STATUS_OFFLINE if the user does not
exist, see
ChatActions::User.
| Syntax: | virtual int GetUserAwayStatus(const char* szNickname) const = 0; |
GetUserName - Return user name of registered user
Notes: Returns chat user name or empty string if the user is not logged in.
| Syntax: | virtual CString8 GetUserName(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; |
IsDebugMode - Check if server runs in debug mode
| Syntax: | virtual bool IsDebugMode() const = 0; |
Description: Interface for bots
Header file: PichatCore_ChatInterfaces.h, namespace PichatCore
OnChatText - Normal text
| Syntax: | virtual void OnChatText(const char* szText, int nTextType) = 0; |
OnChatPrivMessage - Private message text
| Syntax: | virtual void OnChatPrivMessage(const char* szTextData) = 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) = 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; |
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; |
GetTextStringLanguage - Return text string
| Syntax: | virtual const char* GetTextStringLanguage(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
| 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; |
Description: Miscellaneous helper methods
Header file: PichatCore_Definitions.h, namespace PichatCore
GetLibraryVersion - Return library version of PichatCore
| Syntax: | const char* GetLibraryVersion(); |
For further information and feedback please contact me.
