howtouse.md

Документация

Константы

IRCPROTOCOL_BYTESPERMESSAGEMAXIMUM

Максимальное количество байт, которое может занимать одно IRC‐сообщение вместе с символами CrLf.

Const IRCPROTOCOL_BYTESPERMESSAGEMAXIMUM = 512

Длина строки измеряется в символах, а размер одного символа не всегда равен одному байту. Для кодировки UTF-8 размер одного символа может быть от одного до шести байт.

IRCPROTOCOL_DEFAULTPORT

Стандартный порт по умолчанию для соединения с сервером.

Const IRCPROTOCOL_DEFAULTPORT = 6667

Функции

CreateIrcClient

Создаёт объект IrcClient и возвращает указатель на него.

Declare Function CreateIrcClient() As IrcClient Ptr

В случае ошибки возвращает 0.

DestroyIrcClient

Уничтожает объект IrcClient.

Declare Sub DestroyIrcClient( _
	ByVal pIrcClient As IrcClient Ptr _
)

IrcClientSetCallback

Устанавливает обработчики событий.

Declare Function IrcClientSetCallback( _
	ByVal pIrcClient As IrcClient Ptr, _
	ByVal pEvents As IrcEvents Ptr, _
	ByVal lpParameter As LPCLIENTDATA _
)As HRESULT

IrcClientGetCodePage

Получает номер кодировочной таблицы, используемой для преобразования байт в строку.

Declare Function IrcClientGetCodePage( _
	ByVal pIrcClient As IrcClient Ptr, _
	ByVal pCodePage As Integer Ptr _
)As HRESULT

В стандарте IRC‐протокола не определено, каким образом строки будут преобразовываться в байты, эта задача возлагается на самого клиента. Клиент для преобразования строк использует кодировочную таблицу. Например: 65001 (UTF-8), 1251 (кодировка Windows для кириллицы), 866 (кодировка DOS для кириллицы), 20866 (KOI8-R), 21866 (KOI8-U).

Библиотека использует кодировку UTF-8 по умолчанию (65001).

Нельзя использовать кодировки, в символах которых присутствуют нули. Например: UTF-16 (1200), UTF-16 BE (1201). Нули в данном случае будут интерпретироваться как символ с кодом 0, что в большинстве случаев означает конец последовательности символов. IRC‐протокол накладывает ограничение на использование нулевого символа.

IrcClientSetCodePage

Устанавливает номер кодировочной таблицы, используемой для преобразования байт в строку.

Declare Function IrcClientSetCodePage( _
	ByVal pIrcClient As IrcClient Ptr, _
	ByVal CodePage As Integer _
)As HRESULT

ClientVersion

Версия используемой программы. Если установлена, то будет отправлена серверу на CTCP‐запрос VERSION.

Dim ClientVersion As WString Ptr

ClientUserInfo

Информация о пользователе. Если установлена, то будет отправлена серверу на CTCP‐запрос USERINFO.

Dim ClientUserInfo As WString Ptr

Функции

Все функции возвращают HRESULT.

IrcClientOpenConnection

Открывает соединение с сервером.

Declare Function IrcClientOpenConnection( _
	ByVal pIrcClient As IrcClient Ptr, _
	ByVal Server As BSTR, _
	ByVal Port As Integer, _
	ByVal LocalAddress As BSTR, _
	ByVal LocalPort As Integer, _
	ByVal Password As BSTR, _
	ByVal Nick As BSTR, _
	ByVal User As BSTR, _
	ByVal ModeFlags As Long, _
	ByVal RealName As BSTR _
)As HRESULT

Параметры

pIrcClient

Указатель на структуру `IrcClient`. Структура должна быть инициализирована нулями.

Server

Имя сервера для соединения: доменное имя или IP‐адрес, например, chat.freenode.net.

Port

Номер порта для соединения. Стандартный порт для IRC сети — 6667. Однако также доступны некоторые другие порты, на каждом из которых используется определённая кодировка для преобразования байт в строку. Необходимо смотреть в описании сервера на его официальном сайте.

LocalAddress

Локальный IP‐адрес, к которому будет привязан клиент и с которого будет идти соединение. Можно указать конкретный IP‐адрес сетевой карты, чтобы соединение шло через неё, или оставить пустой строкой, в таком случае операционная система сама выберет сетевую карту для подключения.

LocalPort

Локальный порт, к которому будет привязан клиент и с которго будет идти соединение. Если указан 0, то операционная система сама выберет свободный порт.

Password

Пароль на IRC‐сервер, если для соединения с сервером нужен пароль, иначе нужно оставить пустой строкой.

Nick

Ник (имя пользователя), не должен содержать пробелов и спец‐символов.

User

Строка‐идентификатор пользователя, обычно имя программы‐клиента, которым пользуются, не может содержать пробелов, не меняется в течение всего соединения.

ModeFlags

Флаги режимов, задаваемых в строке подключения. Если установлен в `True`, то пользователя можно будет найти командой `WHO`. Обычно все серверы устанавливают его в `False`.

RealName

Настоящие имя и фамилия пользователя.

Описание

Если длина пароля на сервер равна нулю, то функция создаёт строку подключения вида:

NICK Paul
USER paul 8 * :Paul Mutton

Если пароль не пустой, то создаёт строку подключения вида:

PASS password
NICK Paul
USER paul 8 * :Paul Mutton

Затем открывает соединение с сервером и отправляет строку подключения на сервер.

RunIrcClient

Запускает цикл обработки данных от сервера, разбирает их по шаблону и вызывает события.

Declare Sub RunIrcClient( _
	ByVal pIrcClient As IrcClient Ptr _
)

Параметры

pIrcClient

Указатель на структуру `IrcClient`.

Описание

Функция разбирает строку по шаблону и вызывает следующие события:

• SendedRawMessageEvent
• ReceivedRawMessageEvent
• ServerErrorEvent
• ServerMessageEvent
• NoticeEvent
• ChannelMessageEvent
• PrivateMessageEvent
• UserJoinedEvent
• UserLeavedEvent
• NickChangedEvent
• TopicEvent
• QuitEvent
• KickEvent
• InviteEvent
• PingEvent
• PongEvent
• ModeEvent
• CtcpTimeRequestEvent
• CtcpUserInfoRequestEvent
• CtcpVersionRequestEvent
• CtcpActionEvent
• CtcpPingResponseEvent
• CtcpTimeResponseEvent
• CtcpUserInfoResponseEvent
• CtcpVersionResponseEvent

Функция самостоятельно обрабатывает сообщения PING и отправляет на него сообщения PONG. Если установлен обработчик события PingEvent, то обработкой сообщения PING клиент должен заниматься самостоятельно, вызывая функцию SendPong.

Цикл обработки сообщений прерывается когда получение данных от сервера завершается ошибкой.

Возвращаемое значение

Функция не возваращает значений.

CloseIrcClient

Закрывает соединение с сервером.

Declare Sub CloseIrcClient( _
	ByVal pIrcClient As IrcClient Ptr _
)

Параметры

pIrcClient

Указатель на структуру `IrcClient`.

Описание

Функция немедленно закрывает соединение с сервером, без отправки сообщения QUIT о выходе из сети и освобождает ресурсы библиотеки сокетов. Функцию CloseIrc рекомендуется вызывать при любых ошибках сети и для освобождения ресурсов библиотеки сокетов.

Возвращаемое значение

Функция не возвращает значений.

SendIrcMessage

Отправляет сообщение на канал или пользователю.

Declare Function SendIrcMessage( _
	ByVal pIrcClient As IrcClient Ptr, _
	ByVal Channel As WString Ptr, _
	ByVal MessageText As WString Ptr _
) As Boolean

Параметры

pIrcClient

Указатель на структуру `IrcClient`.

Channel

Имя пользователя или канал. Если указан канал, то сообщение получат все пользователи, сидящие на канале. Если указано имя пользователя, то сообщение получит только этот пользователь.

MessageText

Текст сообщения

Описание

Функция создаёт строку вида:

PRIVMSG target :Message Text

Где target — это канал или имя пользователя. Эта строка преобразуется в массив байт в соответствии с текущей кодировкой и отправляется на сервер.

Возвращаемое значение

В случае успеха функция возвращает True, в случае ошибки возвращает False.

SendNotice

Отправляет уведомление пользователю.

Declare Function SendNotice( _
	ByVal pIrcClient As IrcClient Ptr, _
	ByVal Channel As WString Ptr, _
	ByVal NoticeText As WString Ptr _
) As Boolean

Параметры

pIrcClient

Указатель на структуру `IrcClient`.

Channel

Имя пользователя, получателя уведомления.

NoticeText

Текст уведомления.

Описание

Функция создаёт строку вида:

NOTICE target :Notice Text

Где target — это имя пользователя. Эта строка преобразуется в массив байт в соответствии с текущей кодировкой и отправляется на сервер.

Уведомление аналогично сообщению с тем отличием, что на него не следует отвечать автоматически.

Возвращаемое значение

В случае успеха функция возвращает True, в случае ошибки возвращает False.

ChangeTopic

Устанавливает, удаляет или получает тему канала.

Declare Function ChangeTopic( _
	ByVal pIrcClient As IrcClient Ptr, _
	ByVal Channel As WString Ptr, _
	ByVal TopicText As WString Ptr _
) As Boolean

Параметры

pIrcClient

Указатель на структуру `IrcClient`.

Channel

Канал для установки или запроса темы.

TopicText

Текст темы.

Описание

Если TopicText — нулевой указатель NULL, то на сервер отправляется строка:

Topic

В ответ сервер отправит тему канала. Сервер ответит кодами RPL_TOPIC, если тема существует, или RPL_NOTOPIC, если тема не установлена.

Если TopicText — указатель на пустую строку, на сервер отправляется строка:

Topic :

В этом случае сервер удалит тему канала.

Иначе на сервер отправляется строка:

Topic :TopicText

В этом случае сервер установит тему канала, указанную в TopicText.

Возвращаемое значение

В случае успеха функция возвращает True, в случае ошибки возвращает False.

QuitFromServer

Отправляет на сервер сообщение о выходе, что вынуждает сервер закрыть соединение. Перегружена.

Declare Function QuitFromServer Overload( _
	ByVal pIrcClient As IrcClient Ptr _
) As Boolean

Declare Function QuitFromServer Overload( _
	ByVal pIrcClient As IrcClient Ptr, _
	ByVal MessageText As WString Ptr _
) As Boolean

Параметры

pIrcClient

Указатель на структуру `IrcClient`.

MessageText

Текст прощального сообщения.

Описание

Если длина прощального сообщения равна нулю, то функция отправляет на сервер строку:

QUIT

Иначе функция отправляет строку

QUIT :Прощальное сообщение

Это вынуждает сервер закрыть соединение с клиентом.

Возвращаемое значение

В случае успеха функция возвращает True, в случае ошибки возвращает False.

ChangeNick

Меняет ник пользователя.

Declare Function ChangeNick( _
	ByVal pIrcClient As IrcClient Ptr, _
	ByVal Nick As WString Ptr _
) As Boolean

Параметры

pIrcClient

Указатель на структуру `IrcClient`.

Nick

Новый ник.

Описание

Функция отправляет на сервер строку:

NICK новый ник

Возвращаемое значение

В случае успеха функция возвращает True, в случае ошибки возвращает False.

JoinChannel

Присоединяет к каналу или каналам.

Declare Function JoinChannel( _
	ByVal pIrcClient As IrcClient Ptr, _
	ByVal Channel As WString Ptr _
) As Boolean

Параметры

pIrcClient

Указатель на структуру `IrcClient`.

Channel

Список каналов, разделённый запятыми без пробелов. Если на канале установлен пароль, то через пробел указываются пароли для входа, разделённые запятыми без пробелов.

Описание

Функция отправляет на сервер строку:

JOIN channel

Пример

' Присоединение к каналам
Client.JoinChannel("#freebasic,#freebasic-ru")

' Присоединение к каналам с указанием для первого канала пароля
Client.JoinChannel("#freebasic,#freebasic-ru password1")

Возвращаемое значение

В случае успеха функция возвращает True, в случае ошибки возвращает False.

PartChannel

Отключает от канала. Перегружена.

Declare Function PartChannel Overload( _
	ByVal pIrcClient As IrcClient Ptr, _
	ByVal Channel As WString Ptr _
) As Boolean

Declare Function PartChannel Overload( _
	ByVal pIrcClient As IrcClient Ptr, _
	ByVal Channel As WString Ptr, _
	ByVal MessageText As WString Ptr _
) As Boolean

Параметры

pIrcClient

Указатель на структуру `IrcClient`.

Channel

Канал для выхода.

MessageText

Текст прощального сообщения.

Описание

Функция отправляет на сервер строку:

PART channel: прощальное сообщение

Это вынуждает сервер отсоединить пользователя от канала.

Возвращаемое значение

В случае успеха функция возвращает True, в случае ошибки возвращает False.

SendCtcpAction

Отправляет CTCP‐сообщение ACTION, отображаемое клиентами так, будто пользователь сказал текст от третьего лица.

Declare Function SendCtcpAction( _
	ByVal pIrcClient As IrcClient Ptr, _
	ByVal UserName As WString Ptr, _
	ByVal MessageText As WString Ptr _
) As Boolean

Параметры

pIrcClient

Указатель на структуру `IrcClient`.

UserName

Имя пользователя или канал, кому адресовано сообщение.

MessageText

Текст сообщения.

Описание

Сообщение ACTION позволяет сказать текст от третьего лица. В большинстве клиентов ACTION отправляется через команду /me.

Функция отправляет на сервер строку:

PRIVMSG UserName: �ACTION MessageText�

Возвращаемое значение

В случае успеха функция возвращает True, в случае ошибки возвращает False.

SendCtcpPingRequest

Отправляет CTCP‐запрос PING.

Declare Function SendCtcpPingRequest( _
	ByVal pIrcClient As IrcClient Ptr, _
	ByVal UserName As WString Ptr, _
	ByVal TimeValue As WString Ptr _
) As Boolean

Параметры

pIrcClient

Указатель на структуру `IrcClient`.

UserName

Имя пользователя, у которого запрашивают PING.

TimeValue

Текущее время.

Описание

Функция отправляет на сервер строку:

PRIVMSG UserName: �PING TimeValue�

Запрос CTCP PING позволит определить задержку сообщений, которая существует непосредственно между двумя клиентами. CTCP PING работает путем отправки целочисленного аргумента (метки времени) целевому клиенту. Клиент может ответить, предоставляя точно такой же числовой параметр. Вычисляется разница между исходной меткой времени и текущей меткой времени, при этом результат отображается пользователю, который инициировал CTCP PING. Чаще всего используется временная метка, использующая миллисекунды из‐за большинства пользователей с широкополосным подключением к интернету с задержкой менее 1 секунды.

Возвращаемое значение

В случае успеха функция возвращает True, в случае ошибки возвращает False.

SendCtcpTimeRequest

Отправляет CTCP‐запрос TIME, чтобы узнать локальное время клиента.

Declare Function SendCtcpTimeRequest( _
	ByVal pIrcClient As IrcClient Ptr, _
	ByVal UserName As WString Ptr _
) As Boolean

Параметры

pIrcClient

Указатель на структуру `IrcClient`.

UserName

Имя пользователя, у которого запрашивают локальное время.

Описание

Функция отправляет на сервер строку:

PRIVMSG UserName: �TIME�

Запрос CTCP TIME позволяет получить локальное время клиента.

Возвращаемое значение

В случае успеха функция возвращает True, в случае ошибки возвращает False.

SendCtcpUserInfoRequest

Отправляет CTCP‐запрос USERINFO, чтобы узнать информацию о пользователе.

Declare Function SendCtcpUserInfoRequest( _
	ByVal pIrcClient As IrcClient Ptr, _
	ByVal UserName As WString Ptr _
) As Boolean

Параметры

pIrcClient

Указатель на структуру `IrcClient`.

UserName

Имя пользователя, у которого запрашивают информацию.

Описание

Функция отправляет на сервер строку:

PRIVMSG UserName: �USERINFO�

Запрос CTCP USERINFO позволяет получить информацию о пользователе.

Возвращаемое значение

В случае успеха функция возвращает True, в случае ошибки возвращает False.

SendCtcpVersionRequest

Отправляет CTCP‐запрос VERSION, чтобы узнать информацию о версии программы‐клиента пользователя.

Declare Function SendCtcpVersionRequest( _
	ByVal pIrcClient As IrcClient Ptr, _
	ByVal UserName As WString Ptr _
) As Boolean

Параметры

pIrcClient

Указатель на структуру `IrcClient`.

UserName

Имя пользователя, у которого запрашивают информацию.

Описание

Функция отправляет на сервер строку:

PRIVMSG UserName: �VERSION�

Запрос CTCP VERSION позволяет получить версию программы‐клиента пользователя.

Возвращаемое значение

В случае успеха функция возвращает True, в случае ошибки возвращает False.

Declare Function SendCtcpPingResponse( _ ByVal pIrcClient As IrcClient Ptr, _ ByVal UserName As WString Ptr, _ ByVal TimeValue As WString Ptr _ ) As Boolean

Declare Function SendCtcpTimeResponse( _ ByVal pIrcClient As IrcClient Ptr, _ ByVal UserName As WString Ptr, _ ByVal TimeValue As WString Ptr _ ) As Boolean

Declare Function SendCtcpUserInfoResponse( _ ByVal pIrcClient As IrcClient Ptr, _ ByVal UserName As WString Ptr, _ ByVal UserInfo As WString Ptr _ ) As Boolean

Declare Function SendCtcpVersionResponse( _ ByVal pIrcClient As IrcClient Ptr, _ ByVal UserName As WString Ptr, _ ByVal Version As WString Ptr _ ) As Boolean

Declare Function SendPing( _ ByVal pIrcClient As IrcClient Ptr, _ ByVal Server As WString Ptr _ ) As Boolean

Declare Function SendPong( _ ByVal pIrcClient As IrcClient Ptr, _ ByVal Server As WString Ptr _ ) As Boolean

Declare Function SendRawMessage( _ ByVal pIrcClient As IrcClient Ptr, _ ByVal RawText As WString Ptr _ ) As Boolean

SendPing

Отправляет сообщение PING.

Параметры:

strServer — сервер, к которому подключён клиент.

На сообщение PING сервер ответит сообщением PONG.

В случае успеха функция возвращает значение ResultType.None, в случае ошибки возвращает код ошибки.

SendPong

Отправляет сообщение PONG.

Параметры:

strServer — сервер, к которому подключён клиент.

Сервер отправляет сообщения PING для проверки подключённости пользователя. Если пользователь вовремя не ответит сообщением PONG, то сервер закроет соединение. Обычно отправка PONG вручную не требуется, так как это берёт на себя библиотека.

В случае успеха функция возвращает значение ResultType.None, в случае ошибки возвращает код ошибки.

SendRawMessage

Отправляет данные на сервер как они есть.

Declare Function SendRawMessage( _
	ByVal RawText As WString Ptr _
) As Boolean

Параметры

RawText

Данные.

Описание

Функция отправляет данные на сервер без обработки. Используется в тех случаях, когда стандартные функции отправки сообщений не подходят.

Возвращаемое значение

В случае успеха функция возвращает True, в случае ошибки возвращает False.

События