Ggg

OBIMP (Open Binary Instant Messaging Protocol)

Draft 1.0, Revision C.

Content:

1. Basic information

2. General BEX types

3. Administrative BEX types

4. OBIMP packets sequences

5. Country and language codes

 ********************************************************************************** 

1. Basic information

General information:

OBIMP is a binary networking protocol and is transmitted in network byte order (NBO) over TCP.

This protocol was developed for instant messaging services. The main idea was to make open,

simple, secure and extensible binary instant messaging protocol. OBIMP implies structured data

interchanging between server and clients using defined in this document rules. Every protocol

data begins from OBIMP header. Header contains control values and special command type and

subtype that are called binary extension (BEX) type and subtype. All strings that supposed to be

transmitted inside OBIMP packet have to be encoded to UTF-8 encoding including account names.

Servers and ports:

To identify OBIMP connection it is recommended to use following port numbers on server

and these ports should be default ports on client programs:

7023 - TCP port number for client connections

7024 - TCP port number for administrative connections

7025 - TCP port number for secure client connections over TLS/SSL

7026 - TCP port number for secure administrative connections over TLS/SSL

Protocol data types:

Byte, Bool - unsigned 1 byte

Word - unsigned 2 bytes

LongWord – unsigned 4 bytes

QuadWord – unsigned 8 bytes

OctaWord – unsigned 16 bytes

BLK - bytes array, variable length

UTF8 - UTF-8 encoded string, variable length

OBIMP header structure (header is always 17 bytes length):

- Byte: every server/client command starts from byte 0x23 - "#";

- LongWord: sequence, from 0 to 0xFFFFFFFF, first packet have to start always from 0;

- Word: BEX type;

- Word: BEX subtype;

- LongWord: request id, used for marking client requests to link it with server replies;

- LongWord: following data length;

All following data is wTLD (wide Type Length Data) based according its BEX type and subtype.

wTLD types are unique only inside the same BEX. There cannot be two or more wTLDs with

same type in one BEX. There is no any protocol version transmitted in packets because of

wTLD structured data. Being typed, protocol can be extended and updated without any

server/client incompatibility risks.

wTLD may have embedded one or more sTLD (short Type Length Data) to describe data

that is not supposed to be too long. To correctly identify sTLD, all sTLDs have to be used

strongly inside documented parts of this specification.

wTLD/sTLD may have no data, it is called empty wTLD/sTLD, in this case length will be zero.

wTLD structure is:

- Type: LongWord

- Length: LongWord

- Data: data with specified length

sTLD structure is:

- Type: Word

- Length: Word

- Data: data with specified length

BEX types marking in this document and limits:

If BEX have to be sent by client it will be marked as "CLI" inside BEX definition.

If BEX have to be sent by server it will be marked as "SRV" inside BEX definition.

If the same BEX can be sent by client and by server it will be marked as "CLI_SRV"

inside BEX definition.

As far as maximal BEX data size can be 4GB and in present time this is too large

data for one BEX packet there are client BEX limits exist and it depends

on OBIMP server software configuration. By default every client BEX cannot be

larger than OBIMP_BEX_MAX_DATA_LEN including all wTLDs inside BEX else

server will disconnect such a client. Server has no BEX data size limits for server

BEXs.

OBIMP_BEX_MAX_DATA_LEN = 0x00020000

 ********************************************************************************** 

2. General BEX types

General BEX types are transmitted between OBIMP clients and server for instant

messaging services, including accounts login and registration processes.

Available general BEX types:

'''0x0001, Common. (OBIMP_BEX_COM)'''

'''0x0002, Contact list. (OBIMP_BEX_CL)'''

0x0003, Presence (OBIMP_BEX_PRES)

0x0004, Instant messaging (OBIMP_BEX_IM)

0x0005, Users directory (OBIMP_BEX_UD)

0x0006, User avatars (OBIMP_BEX_UA)

=====================================================

'''BEX 0x0001, Common. (OBIMP_BEX_COM)'''

=====================================================

'''Subtype: 0x0001. (OBIMP_BEX_COM_CLI_HELLO)'''

Client have to initiate login sequence first.

If client already passed login sequence during connection negotiation and it has

got unique server cookie then it have to include wTLD 0x0002 with cookie. If cookie

is correct then server will reply with OBIMP_BEX_COM_LOGIN_REPLY.

If client is going to register new account then it have to add only one

empty wTLD 0x0003.

Available request scenarios:

Request:

wTLD 0x0001: UTF8, account name

Optional:

wTLD 0x0002: BLK, unique server cookie

Request:

wTLD 0x0003: empty, new account registration attempt

'''Subtype: 0x0002. (OBIMP_BEX_COM_SRV_HELLO)'''

If account is valid then server will send wTLD 0x0002 with server key else it

will send wTLD 0x0001 with hello error code. Instead of sending server key,

server can redirect to another OBIMP server using wTLD 0x0003

and wTLD 0x0004. If client was redirected then login sequence will start

from beginning.

If client requested new account registration then server will reply

with wTLD 0x0005. If there is registration URL available in server

configuration then server will add wTLD 0x0006 where user can register

new account from web.

Only for compatibility purposes with existing users databases was added

plain-text authentication. If server supports only plain-text authentication

it have to send only wTLD 0x0007. This authentication type is not recommended.

Available replies:

Reply:

wTLD 0x0001: Word, hello error (HELLO_ERROR_CODE)

Reply:

wTLD 0x0002: BLK, server key to generate one-time MD5 password hash

Reply:

wTLD 0x0003: UTF8, redirect, new server host/ip

wTLD 0x0004: LongWord, redirect, new server port number

Reply:

wTLD 0x0005: Bool, if value is True then registration is enabled

Optional:

wTLD 0x0006: UTF8, registration URL

Reply:

wTLD 0x0007: empty, server requires plain-text password authentication

Hello error codes:

HELLO_ERROR_ACCOUNT_INVALID = 0x0001

HELLO_ERROR_SERVICE_TEMP_UNAVAILABLE = 0x0002

HELLO_ERROR_ACCOUNT_BANNED = 0x0003

HELLO_ERROR_WRONG_COOKIE = 0x0004

HELLO_ERROR_TOO_MANY_CLIENTS = 0x0005

HELLO_ERROR_INVALID_LOGIN = 0x0006

'''Subtype: 0x0003. (OBIMP_BEX_COM_CLI_LOGIN)'''

If server replied with server key then client have to generate special MD5 hash

and send it to server.

If server requested plain-text password authentication then client have to send

plain-text password.

Request:

wTLD 0x0001: UTF8, account name

wTLD 0x0002: OctaWord, one-time generated MD5 hash (see below how to generate it)

Request:

wTLD 0x0001: UTF8, account name

wTLD 0x0003: UTF8, plain-text password

One-time MD5 hash generated using following formula:

MD5( MD5( UTF8Encode( LowerCase(Account) ) + "OBIMPSALT" + UTF8Encode(Password) ) + ServerKey )

As far as account name and password is Unicode, UTF-8 encoding used before

MD5 hash generation to make it more universal and platform independent.

Note that LowerCase have to support Unicode "lowercasing".

'''Subtype: 0x0004. (OBIMP_BEX_COM_SRV_LOGIN_REPLY)'''

If account and MD5 hash matched then server will send wTLD 0x0002 with

supported BEXs and wTLD 0x0003 with maximal client BEXs data length else

it will send wTLD 0x0001 with login error code.

If account and MD5 hash matched and current server is just for authentication

purposes then it will reply with unique cookie and with main server address

and port where client have to connect.

Available replies:

Reply:

wTLD 0x0001: Word, login error (LOGIN_ERROR_CODE)

Optional:

wTLD 0x0007: UTF8, password reminder URL if wrong password code

Reply:

wTLD 0x0002: array of Word, server supported BEXs (Word pairs, first Word is BEX type,

second Word is maximal BEX subtype)

wTLD 0x0003: LongWord, maximal client BEXs data length

Reply:

wTLD 0x0004: UTF8, new server host/ip

wTLD 0x0005: LongWord, new server port number

wTLD 0x0006: BLK, unique server cookie

Login error codes:

LOGIN_ERROR_ACCOUNT_INVALID = 0x0001

LOGIN_ERROR_SERVICE_TEMP_UNAVAILABLE = 0x0002

LOGIN_ERROR_ACCOUNT_BANNED = 0x0003

LOGIN_ERROR_WRONG_PASSWORD = 0x0004

LOGIN_ERROR_INVALID_LOGIN = 0x0005

'''Subtype: 0x0005. (OBIMP_BEX_COM_SRV_BYE)'''

Server can close connection for some reason. It will send wTLD 0x0001 with bye

reason code and after sending will immediately close connection.

wTLD 0x0001: Word, bye reason code (BYE_REASON_CODE)

Bye reason codes:

BYE_REASON_SRV_SHUTDOWN = 0x0001

BYE_REASON_CLI_NEW_LOGIN = 0x0002

BYE_REASON_ACCOUNT_KICKED = 0x0003

BYE_REASON_INCORRECT_SEQ = 0x0004

BYE_REASON_INCORRECT_BEX_TYPE = 0x0005

BYE_REASON_INCORRECT_BEX_SUB = 0x0006

BYE_REASON_INCORRECT_BEX_STEP = 0x0007

BYE_REASON_TIMEOUT = 0x0008

BYE_REASON_INCORRECT_WTLD = 0x0009

BYE_REASON_NOT_ALLOWED = 0x000A

BYE_REASON_FLOODING = 0x000B

'''Subtype: 0x0006. (OBIMP_BEX_COM_CLI_SRV_KEEPALIVE_PING)'''

Server and client can send keep alive pings each other to check that

connection is not broken.

No wTLDs.

Server.

Server can send this BEX every n minutes if connection is idle. If server will not

receive pong BEX from client during next n minutes then server will close connection.

Client.

Client can send this BEX any time after login sequence if needed. If pong BEX

from server was not received during time defined by client developer, then

client have to close connection.

'''Subtype: 0x0007. (OBIMP_BEX_COM_CLI_SRV_KEEPALIVE_PONG)'''

After receiving ping BEX, client/server have to reply with this BEX to notify that

connection is not broken.

No wTLDs.

'''Subtype: 0x0008. (OBIMP_BEX_COM_CLI_REGISTER)'''

Used to register new account from client. It is not recommended to enable

registration through protocol if you are going to make public IM server.

If registration is disabled, client can register new account only by adding

wTLD 0x0004 with current server administrative key. This is useful if registration

for clients is disabled and used only web form or administration program for

registration.

wTLD 0x0001: UTF8, account name (maximal UTF-8 encoded length depends on server setting)

wTLD 0x0002: UTF8, password (maximal UTF-8 encoded length is 1024)

wTLD 0x0003: UTF8, secure email (maximal UTF-8 encoded length is 1024)

Optional:

wTLD 0x0004: BLK, current server administrative key

'''Subtype: 0x0009. (OBIMP_BEX_COM_SRV_REGISTER_REPLY)'''

This is server reply for registration attempt.

If server replied with REG_RES_BAD_ACCOUNT_NAME then it will include

optional wTLDs with registration conditions.

wTLD 0x0001: Word, registration result code (see below)

Optional:

wTLD 0x0002: UTF8, allowed characters in the account name for registration

wTLD 0x0003: UTF8, disallowed first characters in the account name for registration

wTLD 0x0004: UTF8, disallowed last characters in the account name for registration

wTLD 0x0005: LongWord, minimal account name length for registration

Registration result codes:

REG_RES_SUCCESS = 0x0000

REG_RES_DISABLED = 0x0001

REG_RES_ACCOUNT_EXISTS = 0x0002

REG_RES_BAD_ACCOUNT_NAME = 0x0003

REG_RES_BAD_REQUEST = 0x0004

REG_RES_BAD_SERVER_KEY = 0x0005

REG_RES_SERVICE_TEMP_UNAVAILABLE = 0x0006

=====================================================

'''BEX 0x0002, Contact list. (OBIMP_BEX_CL)'''

=====================================================

'''Subtype: 0x0001. (OBIMP_BEX_CL_CLI_PARAMS)'''

Client have to request contact list parameters and limits to notify user if any

limit exceeding.

No wTLDs.

'''Subtype: 0x0002. (OBIMP_BEX_CL_SRV_PARAMS_REPLY)'''

Contact list parameters and limits:

wTLD 0x0001: LongWord, maximal groups count

wTLD 0x0002: LongWord, maximal UTF-8 encoded group name length

wTLD 0x0003: LongWord, maximal contacts count all over contact list

wTLD 0x0004: LongWord, maximal UTF-8 encoded account name length

wTLD 0x0005: LongWord, maximal UTF-8 encoded contact name length

wTLD 0x0006: LongWord, maximal UTF-8 encoded authorization reason/revoke length

wTLD 0x0007: LongWord, maximal user/developer sTLDs count in one item

wTLD 0x0008: LongWord, maximal user/developer sTLD length

wTLD 0x0009: LongWord, offline authorization messages (requests, replies, revokes) count awaiting for client request

'''Subtype: 0x0003. (OBIMP_BEX_CL_CLI_REQUEST)'''

Client can request server side contact list any time during logged in session.

No wTLDs.

'''Subtype: 0x0004. (OBIMP_BEX_CL_SRV_REPLY)'''

Server side contact list data will be returned in wTLD 0x0001.

wTLD 0x0001: BLK, contact list data (see below how it can be parsed)

Contact list data parsing.

It consists from two parts:

1. LongWord, items count in contact list.

2. Contact list items.

Contact list item structure is universal for every item type and consists of:

Word, Item Type

LongWord, Item ID

LongWord, Group ID

LongWord, length of following sTLDs according it's item type:

for Groups:

sTLD 0x0001: UTF8, group name

for Contacts:

sTLD 0x0002: UTF8, account name

sTLD 0x0003: UTF8, contact name

sTLD 0x0004: Byte, privacy type

sTLD 0x0005: empty, authorization flag (can be removed by server only)

sTLD 0x0006: empty, general item flag (can be added/removed by server only)

Every item has unique Item ID, every item has Group ID. Group item has

Group ID of the parent group if it is sub group. If Group ID = 0 then item

has no parent group.

If item has general item flag then it means that this item was added and

can be removed only by administartor.

Every item can have own user/developer specified sTLDs for any needs,

but it have to start from sTLD 0x8000 and must meet sTLDs limits.

Item types:

CL_ITEM_TYPE_GROUP = 0x0001

CL_ITEM_TYPE_CONTACT = 0x0002

Contact privacy types:

CL_PRIV_TYPE_NONE = 0x00

CL_PRIV_TYPE_VISIBLE_LIST = 0x01

CL_PRIV_TYPE_INVISIBLE_LIST = 0x02

CL_PRIV_TYPE_IGNORE_LIST = 0x03

CL_PRIV_TYPE_IGNORE_NOT_IN_LIST = 0x04

When client adding or changing contact with privacy type

CL_PRIV_TYPE_IGNORE_NOT_IN_LIST then Group ID have to be always 0

else server will return an error. This is because of such contacts don't have to be

in contact list.

'''Subtype: 0x0005. (OBIMP_BEX_CL_CLI_VERIFY)'''

If client has local copy of the contact list it can verify its checksum with server

side copy of the contact list instead of requesting full contact list from server.

To use this BEX, client have to save local contact list copy in server format and

check MD5 of contact list data described above with MD5 checksum replied by

server for this request.

No wTLDs.

'''Subtype: 0x0006. (OBIMP_BEX_CL_SRV_VERIFY_REPLY)'''

Server will reply with current MD5 checksum of server side contact list for

client to decide, request contact list from server or local copy is actual.

wTLD 0x0001: OctaWord, MD5 checksum of the server side contact list blob

'''Subtype: 0x0007. (OBIMP_BEX_CL_CLI_ADD_ITEM)'''

Client adding item to server side contact list. If client adding new contact item

then it have to add authorization flag too else server will return bad request error.

wTLD 0x0001: Word, contact list Item Type

wTLD 0x0002: LongWord, parent Group ID of adding item

wTLD 0x0003: array of sTLD, adding item sTLDs according item type

'''Subtype: 0x0008. (OBIMP_BEX_CL_SRV_ADD_ITEM_REPLY)'''

Server will reply with wTLD 0x0001 with adding result code. If there is no any

error on adding new item then server will add wTLD 0x0002 with newly

added item ID.

wTLD 0x0001: Word, adding result code (ADD_RES_CODE)

wTLD 0x0002: LongWord, newly added Item ID

Adding result codes:

ADD_RES_SUCCESS = 0x0000

ADD_RES_ERROR_WRONG_ITEM_TYPE = 0x0001

ADD_RES_ERROR_WRONG_PARENT_GROUP = 0x0002

ADD_RES_ERROR_NAME_LEN_LIMIT = 0x0003

ADD_RES_ERROR_WRONG_NAME = 0x0004

ADD_RES_ERROR_ITEM_ALREADY_EXISTS = 0x0005

ADD_RES_ERROR_ITEM_LIMIT_REACHED = 0x0006

ADD_RES_ERROR_BAD_REQUEST = 0x0007

ADD_RES_ERROR_BAD_ITEM_STLD = 0x0008

ADD_RES_ERROR_NOT_ALLOWED = 0x0009

'''Subtype: 0x0009. (OBIMP_BEX_CL_CLI_DEL_ITEM)'''

Client deleting item from server side contact list.

wTLD 0x0001: LongWord, Item ID

'''Subtype: 0x000A. (OBIMP_BEX_CL_SRV_DEL_ITEM_REPLY)'''

Server will reply with wTLD 0x0001.

wTLD 0x0001: Word, deletion result code (DEL_RES_CODE)

Deletion result codes:

DEL_RES_SUCCESS = 0x0000

DEL_RES_ERROR_NOT_FOUND = 0x0001

DEL_RES_ERROR_NOT_ALLOWED = 0x0002

DEL_RES_ERROR_GROUP_NOT_EMPTY = 0x0003

'''Subtype: 0x000B. (OBIMP_BEX_CL_CLI_UPD_ITEM)'''

Client updating item of the server side contact list. Client can update every item

field excepting Item Type, Item ID, account name, authorization flag. Client have

to specify in the wTLD 0x0001 Item ID of updating item. To change parent group

client have to add wTLD 0x0002 with new parent Group ID. To change other data

client have to add wTLD 0x0003 with sTLDs. wTLD 0x0003 have to include all

sTLDs of this item even if most of them are not going to be changed, because

missing sTLDs will be interpreted by server like client is going to delete them.

Client don't have to remove authorization flag if it is not removed by server yet or

don't have to add authorization flag if it was already removed by server. In both

cases server will return bad request error if such mistake will take place.

wTLD 0x0001: LongWord, Item ID

wTLD 0x0002: New parent Group ID (optional)

wTLD 0x0003: array of sTLD, item sTLDs according item type (optional)

'''Subtype: 0x000C. (OBIMP_BEX_CL_SRV_UPD_ITEM_REPLY)'''

Server will reply with wTLD 0x0001.

wTLD 0x0001: Word, update operation result code (UPD_RES_CODE)

Update operation result codes:

UPD_RES_SUCCESS = 0x0000

UPD_RES_ERROR_NOT_FOUND = 0x0001

UPD_RES_ERROR_WRONG_PARENT_GROUP = 0x0002

UPD_RES_ERROR_NAME_LEN_LIMIT = 0x0003

UPD_RES_ERROR_WRONG_NAME = 0x0004

UPD_RES_ERROR_ITEM_ALREADY_EXISTS = 0x0005

UPD_RES_ERROR_BAD_REQUEST = 0x0006

UPD_RES_ERROR_BAD_ITEM_STLD = 0x0007

UPD_RES_ERROR_NOT_ALLOWED = 0x0008

'''Subtype: 0x000D. (OBIMP_BEX_CL_CLI_SRV_AUTH_REQUEST)'''

Every newly added contact to contact list will be not authorized. To receive

presence info client have to request authorization from added contact.

Remote user will decide permit or deny this request. Authorization request

have to be sent only to contact which is in client's contact list and it is

not authorized else server will close connection with "not allowed" reason.

wTLD 0x0001: UTF8, account name of authorization request receiver/sender

wTLD 0x0002: UTF8, authorization request reason

Server can add following wTLDs:

wTLD 0x0003: empty, offline authorization message flag

wTLD 0x0004: QuadWord, offline authorization message time

'''Subtype: 0x000E. (OBIMP_BEX_CL_CLI_SRV_AUTH_REPLY)'''

Remote contact reply for authorization request.

If authorization request was granted by remote contact then server will

automatically remove authorization flag for this contact in server side contact list

and client will receive presence info of this contact according remote contact status.

Client have to manually remove authorization flag in its local copy of contact list.

If authorization request was denied by remote contact then client should suggest

deletion of this contact or sending authorization request again but later.

wTLD 0x0001: UTF8, account name of authorization reply receiver/sender

wTLD 0x0002: Word, authorization reply code

Server can add following wTLDs:

wTLD 0x0003: empty, offline authorization message flag

wTLD 0x0004: QuadWord, offline authorization message time

Authorization reply code:

AUTH_REPLY_GRANTED = 0x0001

AUTH_REPLY_DENIED = 0x0002

'''Subtype: 0x000F. (OBIMP_BEX_CL_CLI_SRV_AUTH_REVOKE)'''

Contact can revoke previously permitted authorization. Client have to

manually add authorization flag to its local copy of contact list, because server will

stop sending presence info for this contact.

wTLD 0x0001: UTF8, account name of authorization revoke receiver/sender

wTLD 0x0002: UTF8, authorization revoke reason

Server can add following wTLDs:

wTLD 0x0003: empty, offline authorization message flag

wTLD 0x0004: QuadWord, offline authorization message time

'''Subtype: 0x0010. (OBIMP_BEX_CL_CLI_REQ_OFFAUTH)'''

Using this BEX, client should request offline authorization requests, replies, revokes

on every login if in BEX OBIMP_BEX_CL_SRV_PARAMS_REPLY there are offline

authorization messages awaiting count greater than zero. If there are offline

authorization messages available then server will send offline marked

authorization requests, replies or revokes.

No wTLDs.

'''Subtype: 0x0011. (OBIMP_BEX_CL_SRV_DONE_OFFAUTH)'''

After all offline authorization messages was sent to client from server, server will

notify client about all authorization messages sent to client and they have to be

deleted by client.

No wTLDs.

'''Subtype: 0x0012. (OBIMP_BEX_CL_CLI_DEL_OFFAUTH)'''

To delete all offline authorization messages client have to send this BEX. Usually it

have to be sent after receiving server BEX OBIMP_BEX_CL_SRV_DONE_OFFAUTH.

No wTLDs.

=====================================================

BEX 0x0003, Presence (OBIMP_BEX_PRES)

=====================================================

'''Subtype: 0x0001. (OBIMP_BEX_PRES_CLI_PARAMS)'''

Client have to request presence info parameters and limits to notify user if any

limit exceeding.

No wTLDs.

'''Subtype: 0x0002. (OBIMP_BEX_PRES_SRV_PARAMS_REPLY)'''

Presence info parameters:

wTLD 0x0001: LongWord, maximal UTF-8 encoded status name length

wTLD 0x0002: LongWord, maximal UTF-8 encoded additional status picture description length

wTLD 0x0003: LongWord, maximal UTF-8 encoded client name length

wTLD 0x0004: LongWord, maximal capabilities count

'''Subtype: 0x0003. (OBIMP_BEX_PRES_CLI_SET_CAPS)'''

Before notify contacts about client presence info, client have to set own capabilities.

Client always can change this info during session.

wTLD 0x0001: Array of Word, client capabilities (see below)

wTLD 0x0002: Word, client type (see below)

wTLD 0x0003: UTF8, user client name

wTLD 0x0004: QuadWord, user client version (see below)

Available client capabilities:

CAP_MSGS_UTF8 = 0x0001 - UTF-8 encoding messages support (required for all clients)

CAP_MSGS_RTF = 0x0002 - RTF (Rich Text Format) messages support with UTF-8 encoding

CAP_MSGS_HTML = 0x0003 - HTML (HyperText Markup Language) messages support UTF-8 encoding

CAP_MSGS_ENCRYPT = 0x0004 - Encryption support

CAP_NOTIFS_TYPING = 0x0005 - Typing notifications support

CAP_AVATARS = 0x0006 - Avatars support

Available client types:

CLIENT_TYPE_USER = 0x0001 - User

CLIENT_TYPE_BOT = 0x0002 - Bot

CLIENT_TYPE_SERVICE = 0x0003 - Service

Client version represented as 8 bytes where every next 2 bytes mean

major, minor, release and build of version info.

'''Subtype: 0x0004. (OBIMP_BEX_PRES_CLI_SET_STATUS)'''

Client sets own presence info. wTLD 0x0001 must be always included in this BEX.

Optional wTLD 0x0002 with status name can be included for developers statuses

that are not defined here.

wTLD 0x0001: LongWord, presence status value (see below)

Optional:

wTLD 0x0002: UTF8, status name

wTLD 0x0003: LongWord, additional status picture number

wTLD 0x0004: UTF8, additional status picture description

Available default presence status values:

PRES_STATUS_ONLINE = 0x0000

PRES_STATUS_INVISIBLE = 0x0001

PRES_STATUS_INVISIBLE_FOR_ALL = 0x0002

PRES_STATUS_FREE_FOR_CHAT = 0x0003

PRES_STATUS_AT_HOME = 0x0004

PRES_STATUS_AT_WORK = 0x0005

PRES_STATUS_LUNCH = 0x0006

PRES_STATUS_AWAY = 0x0007

PRES_STATUS_NOT_AVAILABLE = 0x0008

PRES_STATUS_OCCUPIED = 0x0009

PRES_STATUS_DO_NOT_DISTURB = 0x000A

Users/developers can add own status values starting from 0x80000000.

PRES_STATUS_DEVELOPER >= 0x80000000

'''Subtype: 0x0005. (OBIMP_BEX_PRES_CLI_ACTIVATE)'''

To receive contacts statuses and start notify contacts about user status,

client have to activate presence info broadcast using this BEX. This BEX must be

sent only once during login sequence when client ready to receive contacts

presence info and already set own presence status.

No wTLDs.

'''Subtype: 0x0006. (OBIMP_BEX_PRES_SRV_CONTACT_ONLINE)'''

When contact goes online, server will broadcast about contact's presence info

to every contact in its contact list according contact privacy type.

wTLD 0x0001: UTF8, account name

wTLD 0x0002: LongWord, presence status value

Optional:

wTLD 0x0003: UTF8, status name

wTLD 0x0004: LongWord, additional status picture number

wTLD 0x0005: UTF8, additional status picture description

wTLD 0x0006: Array of Word, client capabilities

wTLD 0x0007: Word, client type

wTLD 0x0008: UTF8, client name

wTLD 0x0009: QuadWord, client version

wTLD 0x000A: QuadWord, client connected time

wTLD 0x000B: QuadWord, registration date

wTLD 0x000C: OctaWord, avatar MD5 hash

'''Subtype: 0x0007. (OBIMP_BEX_PRES_SRV_CONTACT_OFFLINE)'''

When contact goes offline or activates invisible status, server will broadcast

about it to contacts in its contact list according contact privacy type.

wTLD 0x0001: UTF8, account name

=====================================================

BEX 0x0004, Instant messaging (OBIMP_BEX_IM)

=================================================== ==

'''Subtype: 0x0001. (OBIMP_BEX_IM_CLI_PARAMS)'''

Client have to request instant messaging parameters and limits to notify user if any

limit exceeding.

No wTLDs.

'''Subtype: 0x0002. (OBIMP_BEX_IM_SRV_PARAMS_REPLY)'''

Instant messaging parameters:

wTLD 0x0001: LongWord, maximal UTF-8 encoded account name length

wTLD 0x0002: LongWord, maximal message data length

wTLD 0x0003: LongWord, offline messages count awaiting for client request

'''Subtype: 0x0003. (OBIMP_BEX_IM_CLI_REQ_OFFLINE)'''

Client should request offline messages on every login if in BEX

OBIMP_BEX_IM_SRV_PARAMS_REPLY there are offline messages awaiting count

greater than zero. If there are offline messages available then server will send

offline marked message BEX.

No wTLDs.

'''Subtype: 0x0004. (OBIMP_BEX_IM_SRV_DONE_OFFLINE)'''

After all offline messages was sent to client from server, server will notify client

about all messages sent to client and they have to be deleted by client.

No wTLDs.

'''Subtype: 0x0005. (OBIMP_BEX_IM_CLI_DEL_OFFLINE)'''

To delete all offline messages client have to send this BEX. Usually it have to be

sent after receiving server BEX OBIMP_BEX_IM_SRV_DONE_OFFLINE.

No wTLDs.

'''Subtype: 0x0006. (OBIMP_BEX_IM_CLI_MESSAGE)'''

Client sending message. Message type must be selected using remote client

capabilities. Base capability is UTF-8 encoded message. It have to be used

for sending messages to not in list contacts and to online contacts which client

doesn't support any other message types. If remote client does not have capability

of message type support then such message even will not be delivered to remote

client. Every message must have unique message ID and it must not be zero else

server will close connection. Unique message ID is generating by client and it can

be any kind of counter.

To send encrypted message client have to add wTLD 0x0006, but first of all it

have to request public key from remote contact using corresponding BEX.

wTLD 0x0001: UTF8, account name of message receiver

wTLD 0x0002: LongWord, unique message ID

wTLD 0x0003: LongWord, message type (see below)

wTLD 0x0004: BLK, message data

Optional:

wTLD 0x0005: empty, request message acknowledge from remote client

wTLD 0x0006: LongWord, encryption type (see corresponding BEX for types)

Message types:

MSG_TYPE_UTF8 = 0x0001 - UTF-8 encoded message (base type)

MSG_TYPE_RTF = 0x0002 - RTF (Rich Text Format) message with UTF-8 encoding

MSG_TYPE_HTML = 0x0003 - HTML (HyperText Markup Language) message with UTF-8 encoding

'''Subtype: 0x0007. (OBIMP_BEX_IM_SRV_MESSAGE)'''

Client receiving message. It will receive exactly the same message that it was

generated by remote client in BEX above excepting wTLD 0x0001. Server can

add additional wTLDs.

If received encrypted message with wTLD 0x0006, then client have to decrypt

received message data and then parse it according message type.

wTLD 0x0001: UTF8, account name of message sender

wTLD 0x0002: LongWord, unique message ID

wTLD 0x0003: LongWord, message type

wTLD 0x0004: BLK, message data

Optional:

wTLD 0x0005: empty, request message delivery report from remote client

wTLD 0x0006: LongWord, encryption type (see corresponding BEX for types)

Server can add following wTLDs:

wTLD 0x0007: empty, offline message flag

wTLD 0x0008: QuadWord, offline message time

wTLD 0x0009: empty, system message flag

'''Subtype: 0x0008. (OBIMP_BEX_IM_CLI_SRV_MSG_REPORT)'''

If remote client requested message delivery report in its message then client

should send message acknowledge immediately after receiving message.

In cases of privacy when using invisible statuses and for not in list contacts

client should not send message acknowledge.

wTLD 0x0001: UTF8, account name of delivery report receiver/sender

wTLD 0x0002: LongWord, unique received message ID

'''Subtype: 0x0009. (OBIMP_BEX_IM_CLI_SRV_NOTIFY)'''

If both clients support notifications then they have to send them in both

directions when needed.

wTLD 0x0001: UTF8, account name of notification receiver/sender

wTLD 0x0002: LongWord, notification type (see below)

wTLD 0x0003: LongWord, notification value (see below)

Available notifications types:

NOTIF_TYPE_USER_TYPING = 0x0001

Notification values:

NOTIF_VALUE_USER_TYPING_START = 0x0001

NOTIF_VALUE_USER_TYPING_FINISH = 0x0002

'''Subtype: 0x000A. (OBIMP_BEX_IM_CLI_SRV_ENCRYPT_KEY_REQ)'''

If remote client which contact is in client contact list has asymmetric key

cryptography support capability then client can request public key to encrypt

outgoing messages for remote client.

wTLD 0x0001: UTF8, account name of public key request receiver/sender

'''Subtype: 0x000B. (OBIMP_BEX_IM_CLI_SRV_ENCRYPT_KEY_REPLY)'''

If client supports asymmetric key cryptography and it has public key, it will

reply with encryption type and public key else it will reply with ENC_TYPE_DISABLED

or will not reply at all.

wTLD 0x0001: UTF8, account name of public key receiver/sender

wTLD 0x0002: LongWord, encryption type (see below)

Optional (added only when encryption type is not ENC_TYPE_DISABLED):

wTLD 0x0003: BLK, public key

Available encryption types:

ENC_TYPE_DISABLED = 0x0000 (encryption disabled or not supported)

ENC_TYPE_OBIMP = 0x0001 (OBIMP client internal encryption, currently is TDES)

ENC_TYPE_PGP = 0x0002 (currently is not used)

=====================================================

BEX 0x0005, Users directory (OBIMP_BEX_UD)

=====================================================

'''Subtype: 0x0001. (OBIMP_BEX_UD_CLI_PARAMS)'''

Client have to request users directory parameters and limits to notify user if any

limit exceeding.

No wTLDs.

'''Subtype: 0x0002. (OBIMP_BEX_UD_SRV_PARAMS_REPLY)'''

Users directory parameters:

wTLD 0x0001: LongWord, maximal UTF-8 encoded account name length

wTLD 0x0002: LongWord, maximal UTF-8 encoded details field length

wTLD 0x0003: LongWord, maximal UTF-8 encoded about field length

wTLD 0x0004: Bool, if True then client can change account's secure email

wTLD 0x0005: Bool, if True then client can change account's password

wTLD 0x0006: UTF8, secure email/password changing URL if available

'''Subtype: 0x0003. (OBIMP_BEX_UD_CLI_DETAILS_REQ)'''

Client can request user details any time during session. Only for authorized

contacts in client's contact list server will return all available details else it will

return only nick name, first name and last name.

Client account details can be requested the same way.

wTLD 0x0001: UTF8, account name

'''Subtype: 0x0004. (OBIMP_BEX_UD_SRV_DETAILS_REQ_REPLY)'''

Users directory details for requested account.

wTLD 0x0001: Word, request details result code (DETAILS_RES_CODE)

wTLD 0x0002: UTF8, account name

Only for client's account:

wTLD 0x0003: UTF8, secure email

wTLD 0x0019: Bool, if True then online status will not be shown in users directory

Optional:

wTLD 0x0004: UTF8, nick name

wTLD 0x0005: UTF8, first name

wTLD 0x0006: UTF8, last name

wTLD 0x0007: Word, country code (see below)

wTLD 0x0008: UTF8, region/state

wTLD 0x0009: UTF8, city

wTLD 0x000A: UTF8, zip code

wTLD 0x000B: UTF8, address

wTLD 0x000C: Word, language code (see below)

wTLD 0x000D: Word, additional language code (see below)

wTLD 0x000E: Byte, gender (0x00 - not specified, 0x01 - female, 0x02 - male)

wTLD 0x000F: QuadWord, birthday

wTLD 0x0010: UTF8, homepage

wTLD 0x0011: UTF8, about

wTLD 0x0012: UTF8, interests

wTLD 0x0013: UTF8, email

wTLD 0x0014: UTF8, additional email

wTLD 0x0015: UTF8, home phone

wTLD 0x0016: UTF8, work phone

wTLD 0x0017: UTF8, cellular phone

wTLD 0x0018: UTF8, fax number

wTLD 0x001A: UTF8, company

wTLD 0x001B: UTF8, division/department

wTLD 0x001C: UTF8, position

User details request result codes:

DETAILS_RES_SUCCESS = 0x0000

DETAILS_RES_NOT_FOUND = 0x0001

DETAILS_RES_TOO_MANY_REQUESTS = 0x0002

DETAILS_RES_SERVICE_TEMP_UNAVAILABLE = 0x0003

Country codes:

Can be found at the end of this document

Language codes:

Can be found at the end of this document

'''Subtype: 0x0005. (OBIMP_BEX_UD_CLI_DETAILS_UPD)'''

Client can update own account details. Client can send only updated details fields.

wTLD 0x0001: UTF8, client's account name

Optional:

wTLD 0x0002: UTF8, nick name

wTLD 0x0003: UTF8, first name

wTLD 0x0004: UTF8, last name

wTLD 0x0005: Word, country code (see below)

wTLD 0x0006: UTF8, region/state

wTLD 0x0007: UTF8, city

wTLD 0x0008: UTF8, zip code

wTLD 0x0009: UTF8, address

wTLD 0x000A: Word, language code (see below)

wTLD 0x000B: Word, additional language code (see below)

wTLD 0x000C: Byte, gender (0x00 - not specified, 0x01 - female, 0x02 - male)

wTLD 0x000D: QuadWord, birthday

wTLD 0x000E: UTF8, homepage

wTLD 0x000F: UTF8, about

wTLD 0x0010: UTF8, interests

wTLD 0x0011: UTF8, email

wTLD 0x0012: UTF8, additional email

wTLD 0x0013: UTF8, home phone

wTLD 0x0014: UTF8, work phone

wTLD 0x0015: UTF8, cellular phone

wTLD 0x0016: UTF8, fax number

wTLD 0x0017: Bool, if True then online status will not be shown in users directory

wTLD 0x0018: UTF8, company

wTLD 0x0019: UTF8, division/department

wTLD 0x001A: UTF8, position

'''Subtype: 0x0006. (OBIMP_BEX_UD_SRV_DETAILS_UPD_REPLY)'''

Server will reply with update result code.

wTLD 0x0001: Word, update details result code (UPD_DETAILS_RES_CODE)

Update details result codes:

UPD_DETAILS_RES_SUCCESS = 0x0000

UPD_DETAILS_RES_BAD_REQUEST = 0x0001

UPD_DETAILS_RES_SERVICE_TEMP_UNAVAILABLE = 0x0002

'''Subtype: 0x0007. (OBIMP_BEX_UD_CLI_SEARCH)'''

Client can search for other users according search criterion. Every criterion in the

client request have to be represented as corresponding wTLD.

Request:

wTLD 0x0001: UTF8, account name

Or request:

wTLD 0x0002: UTF8, email

Or request:

wTLD 0x0003: UTF8, nick name

wTLD 0x0004: UTF8, first name

wTLD 0x0005: UTF8, last name

wTLD 0x0006: Word, country code

wTLD 0x0007: UTF8, city

wTLD 0x0008: Word, language code

wTLD 0x0009: Byte, gender (0x00 - not specified, 0x01 - female, 0x02 - male)

wTLD 0x000A: Byte, age min

wTLD 0x000B: Byte, age max

wTLD 0x000C: Byte, zodiac sign (see below)

wTLD 0x000D: UTF8, interests

wTLD 0x000E: empty, search online users only

Zodiac signs:

ZODIAC_ARIES = 0x01

ZODIAC_TAURUS = 0x02

ZODIAC_GEMINI = 0x03

ZODIAC_CANCER = 0x04

ZODIAC_LEO = 0x05

ZODIAC_VIRGO = 0x06

ZODIAC_LIBRA = 0x07

ZODIAC_SCORPIO = 0x08

ZODIAC_SAGITTARIUS = 0x09

ZODIAC_CAPRICORN = 0x0A

ZODIAC_AQUARIUS = 0x0B

ZODIAC_PISCES = 0x0C

'''Subtype: 0x0008. (OBIMP_BEX_UD_SRV_SEARCH_REPLY)'''

Server will reply with search results. There can be more than one BEX if more

than one user corresponds for search criterion.

wTLD 0x0001: Word, request details result code (SEARCH_RES_CODE)

Optional:

wTLD 0x0002: UTF8, account name

wTLD 0x0003: UTF8, nick name

wTLD 0x0004: UTF8, first name

wTLD 0x0005: UTF8, last name

wTLD 0x0006: Byte, gender (0x00 - not specified, 0x01 - female, 0x02 - male)

wTLD 0x0007: Byte, age

wTLD 0x0008: empty, user is online

If this is last BEX with search result then server will add following wTLDs:

wTLD 0x0009: empty, last search result

wTLD 0x000A: LongWord, total count of results in DB

Search result codes:

SEARCH_RES_SUCCESS = 0x0000

SEARCH_RES_NOT_FOUND = 0x0001

SEARCH_RES_BAD_REQUEST = 0x0002

SEARCH_RES_TOO_MANY_REQUESTS = 0x0003

SEARCH_RES_SERVICE_TEMP_UNAVAILABLE = 0x0004

'''Subtype: 0x0009. (OBIMP_BEX_UD_CLI_SECURE_UPD)'''

If server allowed changing of secure email and password then client can send

this BEX. To change secure email or password client have to send wTLD 0x0001 with

client's account name and wTLD 0x0002 with current password.

wTLD 0x0001: UTF8, client's account name

wTLD 0x0002: UTF8, account's current password

wTLD 0x0003: UTF8, account's new secure email

or/and

wTLD 0x0004: UTF8, account's new password

'''Subtype: 0x000A. (OBIMP_BEX_UD_SRV_SECURE_UPD_REPLY)'''

Server will reply with secure email or password update result code.

wTLD 0x0001: Word, update result code (UPD_SECURE_RES_CODE)

Update details result codes:

UPD_SECURE_RES_SUCCESS = 0x0000

UPD_SECURE_RES_BAD_REQUEST = 0x0001

UPD_SECURE_RES_SERVICE_TEMP_UNAVAILABLE = 0x0002

UPD_SECURE_RES_NOT_ALLOWED = 0x0003

=====================================================

BEX 0x0006, User avatars (OBIMP_BEX_UA)

Currently server supports PNG avatars only.

Server will check PNG header on setting new avatar.

=====================================================

'''Subtype: 0x0001. (OBIMP_BEX_UA_CLI_PARAMS)'''

Client have to request users avatars parameters and limits to notify user if any

limit exceeding.

No wTLDs.

'''Subtype: 0x0002. (OBIMP_BEX_UA_SRV_PARAMS_REPLY)'''

If server has saved client avatar then it will add wTLD 0x0002 with avatar file

MD5 hash. Users avatars parameters:

wTLD 0x0001: LongWord, maximal avatar file size

wTLD 0x0002: OctaWord, current client avatar file MD5 hash

Before sending BEXs below client have to set capabilities using

OBIMP_BEX_PRES_CLI_SET_CAPS where have to be avatars support capability

else server will reply with error.

'''Subtype: 0x0003. (OBIMP_BEX_UA_CLI_AVATAR_REQ)'''

Client can request own and users avatars any time during session. Avatar file

MD5 hash can be got from presence info if remote client supports avatars.

wTLD 0x0001: OctaWord, avatar file MD5 hash

'''Subtype: 0x0004. (OBIMP_BEX_UA_SRV_AVATAR_REPLY)'''

If server has such avatar with requested MD5 hash then it will reply with

avatar file else it will reply with error in wTLD 0x0001.

wTLD 0x0001: Word, avatar request result (see below)

wTLD 0x0002: OctaWord, avatar file MD5 hash

wTLD 0x0003: BLK, avatar file

Avatar request result:

AVATAR_REQ_SUCCESS = 0x0000

AVATAR_REQ_NOT_FOUND = 0x0001

AVATAR_REQ_NOT_ALLOWED = 0x0002

'''Subtype: 0x0005. (OBIMP_BEX_UA_CLI_AVATAR_SET)'''

Client can set own avatar any time during session. Client have to send MD5 hash

of the avatar file that will be checked by server after receiving this BEX.

Old avatar will be replaced by server automatically.

To remove or clear avatar client have to send empty wTLD 0x0001.

wTLD 0x0001: OctaWord, avatar file MD5 hash

wTLD 0x0002: BLK, avatar file data

Or

wTLD 0x0001: empty, means that client cleared own avatar

'''Subtype: 0x0006. (OBIMP_BEX_UA_SRV_AVATAR_SET_REPLY)'''

If avatar was successfully received by server and avatar file MD5 hash checked

then server will broadcast new avatar MD5 hash to users in presence info.

wTLD 0x0001: Word, avatar request result (see below)

Avatar set result:

AVATAR_SET_SUCCESS = 0x0000

AVATAR_SET_BAD_MD5 = 0x0001

AVATAR_SET_NOT_ALLOWED = 0x0002

AVATAR_SET_TEMP_UNAVAILABLE = 0x0003

 ********************************************************************************** 

3. Administrative BEX types

Administrative BEX types are transmitted between OBIMP administrative clients and

administrative server for OBIMP server settings and user accounts administration.

Available BEX types:

'''0x0001, Windows server administration. (OBIMP_BEX_WADM)'''

=====================================================

BEX 0xF001, Windows server administration (OBIMP_BEX_WADM)

=====================================================

'''Subtype: 0x0001. (OBIMP_BEX_WADM_CLI_LOGIN)'''

To login for administrative purposes client have to connect to special

administrative server and port number. And this will be first BEX after connection

established. Server key is generated on server.

wTLD 0x0001: BLK, current server administrative key

'''Subtype: 0x0002. (OBIMP_BEX_WADM_SRV_LOGIN_REPLY)'''

If this is administrative server will reply with this BEX. If client sent valid

server key it will reply with wTLD 0x0001 with success code. After

success administrative login client can send other administrative BEXs.

wTLD 0x0001: Word, administrative result code (see below)

Administrative status codes:

ADM_RES_CODE_SUCCESS = 0x0000

ADM_RES_CODE_BAD_KEY = 0x0001

'''Subtype: 0x0003. (OBIMP_BEX_WADM_CLI_PARAMS)'''

To request server parameters client have to send this BEX.

No wTLDs.

'''Subtype: 0x0004. (OBIMP_BEX_WADM_SRV_PARAMS_REPLY)'''

Server parameters reply.

wTLD 0x0001: UTF8, users database directory path

wTLD 0x0002: LongWord, main server port number to listen incoming connections

wTLD 0x0003: LongWord, administration server port number to listen incoming connections

wTLD 0x0004: Bool, start main server on system start

wTLD 0x0005: Bool, start administration server on system start

wTLD 0x0006: Bool, listen for incoming connections on main server port

wTLD 0x0007: Bool, listen for incoming connections on administration server port

wTLD 0x0008: Bool, server administration key auto-change feature

wTLD 0x0009: LongWord, server administration key auto-change seconds

wTLD 0x000A: LongWord, maximal clients count limit

wTLD 0x000B: LongWord, current connected clients count

wTLD 0x000C: LongWord, total registered users count

wTLD 0x000D: LongWord, authentication timeout seconds

wTLD 0x000E: LongWord, idle seconds to send keep alive pings

wTLD 0x000F: LongWord, maximal account name length

wTLD 0x0010: LongWord, maximal groups count in contact list

wTLD 0x0011: LongWord, maximal group name length

wTLD 0x0012: LongWord, maximal contacts count

wTLD 0x0013: LongWord, maximal contact name length

wTLD 0x0014: LongWord, maximal authorization reason/revoke length

wTLD 0x0015: LongWord, maximal status name length

wTLD 0x0016: LongWord, maximal status picture description length

wTLD 0x0017: LongWord, maximal client name length

wTLD 0x0018: LongWord, maximal capabilities count

wTLD 0x0019: LongWord, maximal message data length

wTLD 0x001A: LongWord, maximal details fields length

wTLD 0x001B: LongWord, maximal about field length

wTLD 0x001C: LongWord, maximal avatar file size

wTLD 0x001D: UTF8, IP ban list

wTLD 0x001E: Bool, users can register new accounts flag

wTLD 0x001F: UTF8, registration URL

wTLD 0x0020: UTF8, allowed characters in the account name for registration

wTLD 0x0021: UTF8, disallowed first characters in the account name for registration

wTLD 0x0022: UTF8, disallowed last characters in the account name for registration

wTLD 0x0023: LongWord, minimal account name length for registration

wTLD 0x0024: UTF8, password reminder URL

wTLD 0x0025: UTF8, log files path

wTLD 0x0026: Bool, write log file for main server

wTLD 0x0027: Bool, write log file for admin server

wTLD 0x0028: UTF8, secure email and password change URL

wTLD 0x0029: Bool, users can change account's secure email

wTLD 0x002A: Bool, users can change account's password

wTLD 0x002B: LongWord, main server optional port number to listen incoming connections

wTLD 0x002C: LongWord, main server optional port number to listen incoming connections

wTLD 0x002D: BLK, general contact list data

'''Subtype: 0x0005. (OBIMP_BEX_WADM_CLI_SET)'''

To set server parameters client have to send this BEX. All wTLDs are the same like

in BEX OBIMP_BEX_WADM_SRV_PARAMS_REPLY. Client should send only

changed settings wTLDs.

wTLD 0x0001: UTF8, users database directory path

....

Client don't have to send following wTLDs:

wTLD 0x000B: LongWord, current connected clients count

wTLD 0x000C: LongWord, total registered users count

'''Subtype: 0x0006. (OBIMP_BEX_WADM_SRV_SET_REPLY)'''

This BEX is server reply if setting change BEX was sent. Server will return the

same wTLDs count like it was sent in OBIMP_BEX_WADM_CLI_SET.

wTLD 0x0001: Word, users DB directory setting change result code (see below)

....

Setting change result codes:

SET_CHANGE_SUCCESS = 0x0000

SET_CHANGE_NOT_ALLOWED = 0x0001

'''Subtype: 0x0007. (OBIMP_BEX_WADM_CLI_BROADCAST)'''

Used to send system message to clients or to disconnect all clients.

The sender of system message will be OBIMP packet begin sign "#"

and all such messages will be marked using system message flag.

wTLD 0x0001: Word, broadcast flag (see below)

To send system message, client have to add following wTLD:

wTLD 0x0002: UTF8, system message text (maximal UTF-8 encoded length is 2048)

Broadcast flags:

BROADCAST_MSG_TO_ALL = 0x0001

BROADCAST_MSG_TO_CONNECTED_ONLY = 0x0002

BROADCAST_DROP_CONNECTIONS = 0x0003

'''Subtype: 0x0008. (OBIMP_BEX_WADM_SRV_BROADCAST_REPLY)'''

Server will reply with broadcast result code.

wTLD 0x0001: Word, broadcast result code (see below)

Broadcast result codes:

BC_RES_SUCCESS = 0x0000

BC_RES_BAD_REQUEST = 0x0001

BC_RES_MSG_LEN_LIMIT = 0x0002

'''Subtype: 0x0009. (OBIMP_BEX_WADM_CLI_USER)'''

Used to add/update/ban/delete users.

wTLD 0x0001: Word, user command (see below)

wTLD 0x0002: UTF8, account name (max length depends on server setting)

CMD_USER_ADD, CMD_USER_UPD:

When adding new user, client have to add password and secure email wTLDs.

wTLD 0x0003: UTF8, password (maximal UTF-8 encoded length is 1024)

wTLD 0x0004: UTF8, secure email (maximal UTF-8 encoded length is 1024)

When changing password or changing secure email client have to add

corresponding wTLD or both wTLDs above.

CMD_USER_BAN, CMD_USER_UNBAN:

When banning or unbanning user, ban/unban note or reason should be added by

adding following wTLD:

wTLD 0x0005: UTF8, ban/unban note (maximal UTF-8 encoded length is 2048)

CMD_USER_ADD, CMD_USER_UPD:

When adding/changing user details client have to add one or more from this wTLDs:

wTLD 0x0006: UTF8, nick name

wTLD 0x0007: UTF8, first name

wTLD 0x0008: UTF8, last name

wTLD 0x0009: Word, country code

wTLD 0x000A: UTF8, region/state

wTLD 0x000B: UTF8, city

wTLD 0x000C: UTF8, zip code

wTLD 0x000D: UTF8, address

wTLD 0x000E: Word, language code

wTLD 0x000F: Word, additional language code

wTLD 0x0010: Byte, gender (0x00 - not specified, 0x01 - female, 0x02 - male)

wTLD 0x0011: QuadWord, birthday

wTLD 0x0012: UTF8, homepage

wTLD 0x0013: UTF8, about

wTLD 0x0014: UTF8, interests

wTLD 0x0015: UTF8, email

wTLD 0x0016: UTF8, additional email

wTLD 0x0017: UTF8, home phone

wTLD 0x0018: UTF8, work phone

wTLD 0x0019: UTF8, cellular phone

wTLD 0x001A: UTF8, fax number

wTLD 0x001B: Bool, if True then online status will not be shown in users directory

wTLD 0x001C: UTF8, company

wTLD 0x001D: UTF8, division/department

wTLD 0x001E: UTF8, position

Available user commands:

CMD_USER_ADD = 0x0001

CMD_USER_DEL = 0x0002

CMD_USER_UPD = 0x0003

CMD_USER_BAN = 0x0004

CMD_USER_UNBAN = 0x0005

CMD_USER_KICK = 0x0006

CMD_USER_DETAILS = 0x0007

CMD_USER_CLEARCL = 0x0008

'''Subtype: 0x000A. (OBIMP_BEX_WADM_SRV_USER_REPLY)'''

Server will reply with user add/ban/delete result code.

wTLD 0x0001: Word, user operation result code (see below)

If client requested user details and such user was found then following wTLDs

will be added:

wTLD 0x0002: UTF8, account name

wTLD 0x0003: UTF8, secure email

wTLD 0x0004: UTF8, nick name

wTLD 0x0005: UTF8, first name

wTLD 0x0006: UTF8, last name

wTLD 0x0007: Word, country code

wTLD 0x0008: UTF8, region/state

wTLD 0x0009: UTF8, city

wTLD 0x000A: UTF8, zip code

wTLD 0x000B: UTF8, address

wTLD 0x000C: Word, language code

wTLD 0x000D: Word, additional language code

wTLD 0x000E: Byte, gender (0x00 - not specified, 0x01 - female, 0x02 - male)

wTLD 0x000F: QuadWord, birthday

wTLD 0x0010: UTF8, homepage

wTLD 0x0011: UTF8, about

wTLD 0x0012: UTF8, interests

wTLD 0x0013: UTF8, email

wTLD 0x0014: UTF8, additional email

wTLD 0x0015: UTF8, home phone

wTLD 0x0016: UTF8, work phone

wTLD 0x0017: UTF8, cellular phone

wTLD 0x0018: UTF8, fax number

wTLD 0x0019: UTF8, base64 encoded password hash

wTLD 0x001A: QuadWord, registration date

wTLD 0x001B: LongWord, current presence status

wTLD 0x001C: QuadWord, last connected date

wTLD 0x001D: UTF8, last IP address

wTLD 0x001E: Bool, banned flag

wTLD 0x001F: QuadWord, ban/unban date

wTLD 0x0020: UTF8, ban/unban note

wTLD 0x0021: QuadWord, total logins count

wTLD 0x0022: Bool, if True then online status will not be shown in users directory

wTLD 0x0023: UTF8, company

wTLD 0x0024: UTF8, division/department

wTLD 0x0025: UTF8, position

User operation result codes:

USER_RES_SUCCESS = 0x0000

USER_RES_BAD_REQUEST = 0x0001

USER_RES_NOT_FOUND = 0x0002

USER_RES_ALREADY_EXISTS = 0x0003

USER_RES_LEN_LIMIT = 0x0004

USER_RES_SERVICE_TEMP_UNAVAILABLE = 0x0005

'''Subtype: 0x000B. (OBIMP_BEX_WADM_SRV_STATE)'''

Server can send state of total users count and connected users count.

wTLD 0x0001: LongWord, current connected clients count

wTLD 0x0002: LongWord, total registered users count

'''Subtype: 0x000C. (OBIMP_BEX_WADM_CLI_LIST)'''

Used to get list of connected, registered and last registered user lists.

wTLD 0x0001: Word, list type (see below)

wTLD 0x0002: LongWord, get next users from this index

Admin list types:

LIST_TYPE_CONNECTED = 0x0001

LIST_TYPE_REGISTERED = 0x0002

LIST_TYPE_LAST_REGED = 0x0003

'''Subtype: 0x000D. (OBIMP_BEX_WADM_SRV_LIST_REPLY)'''

Server will reply with requested list. As far as there can be a lot of users, every

new request will return maximum 100 users until LIST_REQ_FINISHED code will

not be received. If there are next users found then server will add user data wTLDs.

wTLD 0x0001: Word, list request result code (see below)

wTLD 0x0002: LongWord, last index to make next request

Optional:

wTLD 0x0003: UTF8, account name

wTLD 0x0004: UTF8, last IP address

wTLD 0x0005: QuadWord, total logins count

wTLD 0x0006: UTF8, secure e-mail

List request result codes:

LIST_REQ_FINISHED = 0x0000

LIST_REQ_MORE_AVAILABLE = 0x0001

LIST_REQ_BAD_REQUEST = 0x0002

 ********************************************************************************** 

4. OBIMP packets sequences

If BEX have to be sent by client it will be marked with "GREEN" color.

If BEX have to be sent by server it will be marked with "MAROON" color.

=====================================================

4.1 General BEX types sequences

=====================================================

4.1.1 New account registration:

- Client connects to OBIMP server

- OBIMP_BEX_COM_CLI_HELLO

wTLD 0x0003: empty, will just identify registration attempt

- OBIMP_BEX_COM_SRV_HELLO

wTLD 0x0005: Bool, if value is True then registration is enabled

Optional: wTLD 0x0006: UTF8, registration URL

a) If registration is enabled

- OBIMP_BEX_COM_CLI_REGISTER

wTLD 0x0001: UTF8, account name (maximal UTF-8 encoded length depends on server setting)

wTLD 0x0002: UTF8, password (maximal UTF-8 encoded length is 1024)

wTLD 0x0003: UTF8, secure email (maximal UTF-8 encoded length is 1024)

Optional: wTLD 0x0004: BLK, current server administrative key

- OBIMP_BEX_COM_SRV_REGISTER_REPLY

wTLD 0x0001: Word, registration result code

Optional:

wTLD 0x0002: UTF8, allowed characters in the account name for registration

wTLD 0x0003: UTF8, disallowed first characters in the account name for registration

wTLD 0x0004: UTF8, disallowed last characters in the account name for registration

wTLD 0x0005: LongWord, minimal account name length for registration

- Client disconnects

b) If registration is disabled

- Client disconnects

- If registration URL is available then client should ask user to register using this URL

4.1.2 Logging in:

--

Scenario 1 (Hello error).

- Client connects to OBIMP server

- OBIMP_BEX_COM_CLI_HELLO

wTLD 0x0001: UTF8, account name

- OBIMP_BEX_COM_SRV_HELLO 

wTLD 0x0001: Word, hello error (HELLO_ERROR_CODE)

- Client disconnects

--

Scenario 2 (Server redirect).

- Client connects to OBIMP server

- OBIMP_BEX_COM_CLI_HELLO

wTLD 0x0001: UTF8, account name

- OBIMP_BEX_COM_SRV_HELLO 

wTLD 0x0003: UTF8, redirect, new server host/ip

wTLD 0x0004: LongWord, redirect, new server port number

- Client disconnects

- Client restarts login sequence from beginning using new OBIMP server host and port

--

Scenario 3 (Login error/success/cookie).

- Client connects to OBIMP server

- OBIMP_BEX_COM_CLI_HELLO

wTLD 0x0001: UTF8, account name

- OBIMP_BEX_COM_SRV_HELLO 

wTLD 0x0002: BLK, server key to generate one-time MD5 password hash

- OBIMP_BEX_COM_CLI_LOGIN

wTLD 0x0001: UTF8, account name

wTLD 0x0002: OctaWord, one-time generated MD5 hash

- OBIMP_BEX_COM_SRV_LOGIN_REPLY

a) wTLD 0x0001: Word, login error (LOGIN_ERROR_CODE)

Optional: wTLD 0x0007: UTF8, password reminder URL if wrong password code

b) wTLD 0x0002: array of Word, server supported BEXs

wTLD 0x0003: LongWord, maximal client BEXs data length

c) wTLD 0x0004: UTF8, new server host/ip

wTLD 0x0005: LongWord, new server port number

wTLD 0x0006: BLK, unique server cookie

a) If login error

- Client disconnects

- If password reminder URL is available then client should show it to user

b) Login success (see "After login actions")

c) New server host, port number and unique cookie received

- Client disconnects

- Client restarts login sequence from beginning using new server host, port

number and cookie (see "Login with cookie" scenario)

--

Scenario 4 (Plain-text password login).

- Client connects to OBIMP server

- OBIMP_BEX_COM_CLI_HELLO

wTLD 0x0001: UTF8, account name

- OBIMP_BEX_COM_SRV_HELLO 

wTLD 0x0007: empty, server requires plain-text password authentication

- OBIMP_BEX_COM_CLI_LOGIN

wTLD 0x0001: UTF8, account name

wTLD 0x0003: UTF8, plain-text password

- OBIMP_BEX_COM_SRV_LOGIN_REPLY

(next data is the same as in scenario 3)

...

--

Scenario 5 (Login with cookie).

- Client connects to OBIMP server

- OBIMP_BEX_COM_CLI_HELLO

wTLD 0x0001: UTF8, account name

wTLD 0x0002: BLK, unique server cookie

a) If account name and cookie not matched

- OBIMP_BEX_COM_SRV_HELLO 

wTLD 0x0001: Word, hello error (HELLO_ERROR_CODE)

- Client disconnects

b) If account name and cookie matched

- OBIMP_BEX_COM_SRV_LOGIN_REPLY

wTLD 0x0002: array of Word, server supported BEXs

wTLD 0x0003: LongWord, maximal client BEXs data length

- Login success (see "After login actions")

4.1.3 After login actions:

After successful login, client have to request all server BEX types parameters,

because they can change while client was offline. Server supported BEXs was

sent to client inside OBIMP_BEX_COM_SRV_LOGIN_REPLY.

1. Request parameters for all server supported BEX types one by one excluding

OBIMP_BEX_COM type as far as it is basic BEX type:

- OBIMP_BEX_[SERVER_SUPPORTED_BEX_TYPE]_CLI_PARAMS 

For example:

- OBIMP_BEX_CL_CLI_PARAMS

- OBIMP_BEX_PRES_CLI_PARAMS

- OBIMP_BEX_IM_CLI_PARAMS

- OBIMP_BEX_UD_CLI_PARAMS

- OBIMP_BEX_UA_CLI_PARAMS

2. Before notify contacts about client presence info, client have to set own

capabilities. Client always can change this info during session.

- OBIMP_BEX_PRES_CLI_SET_CAPS

3. Request server side contact list or verify existing local copy with server's copy.

a) If there is no local copy of the server side contact list then request it from server:

- OBIMP_BEX_CL_CLI_REQUEST

- OBIMP_BEX_CL_SRV_REPLY

b) If there is local copy of the server side contact list then verify contact list's blob

by calculating its MD5 hash with MD5 hash sent by server in the reply:

- OBIMP_BEX_CL_CLI_VERIFY

- OBIMP_BEX_CL_SRV_VERIFY_REPLY

4. Continue only after successful receiving or verifying server side contact list, set

client's presence status and status picture number with description:

- OBIMP_BEX_PRES_CLI_SET_STATUS

5. Finally activate presence status broadcasting. Now client is ready for messaging.

- OBIMP_BEX_PRES_CLI_ACTIVATE

6. Request client's account details if needed:

- OBIMP_BEX_UD_CLI_DETAILS_REQ

4.1.4 Requesting offline messages:

Offline messages can be requested after sending OBIMP_BEX_PRES_CLI_ACTIVATE.

OBIMP_BEX_IM_CLI_PARAMS has offline messages awaiting wTLD. If there are offline

messages then request them:

- OBIMP_BEX_IM_CLI_REQ_OFFLINE

Server will send all available offline messages one by one marked with offline

message wTLDs:

- OBIMP_BEX_IM_SRV_MESSAGE

After sending all offline messages server will notify client by following BEX:

- OBIMP_BEX_IM_SRV_DONE_OFFLINE

If client received all offline messages then it have to request offline messages

deletion else server will send them on next request:

- OBIMP_BEX_IM_CLI_DEL_OFFLINE

4.1.5 Requesting offline authorization requests, replies, revokes:

Offline authorization messages can be requested after sending

OBIMP_BEX_PRES_CLI_ACTIVATE. OBIMP_BEX_CL_CLI_PARAMS has offline

authorization messages awaiting wTLD. If there are offline authorization messages

then request them:

- OBIMP_BEX_CL_CLI_REQ_OFFAUTH

Server will send all available offline authorization messages one by one marked

with offline authorization message wTLDs:

- OBIMP_BEX_CL_CLI_SRV_AUTH_REQUEST

or

- OBIMP_BEX_CL_CLI_SRV_AUTH_REPLY 

or

- OBIMP_BEX_CL_CLI_SRV_AUTH_REVOKE

After sending all offline authorization messages server will notify client by

following BEX:

- OBIMP_BEX_CL_SRV_DONE_OFFAUTH

If client received all offline authorization messages then it have to request offline

authorization messages deletion else server will send them on next request:

- OBIMP_BEX_CL_CLI_DEL_OFFAUTH

=====================================================

4.2 Administrative BEX types sequences

=====================================================

4.2.1 Logging in:

- Client connects to administrative server

- OBIMP_BEX_WADM_CLI_LOGIN

wTLD 0x0001: BLK, current server administrative key

- OBIMP_BEX_WADM_SRV_LOGIN_REPLY

wTLD 0x0001: Word, administrative result code

a) If was sent bad server key

- Client disconnects

b) If was sent correct server key then request all server parameters

- OBIMP_BEX_WADM_CLI_PARAMS

- OBIMP_BEX_WADM_SRV_PARAMS_REPLY

 ********************************************************************************** 

5. Country and language codes

Available country codes:

1 Afghanistan

2 Albania

3 Antarctica

4 Algeria

5 American Samoa

6 Andorra

7 Angola

8 Antigua and Barbuda

9 Azerbaijan

10 Argentina

11 Australia

12 Austria

13 Bahamas

14 Bahrain

15 Bangladesh

16 Armenia

17 Barbados

18 Belgium

19 Bermuda

20 Bhutan

21 Bolivia

22 Bosnia and Herzegovina

23 Botswana

24 Bouvet Island

25 Brazil

26 Belize

27 British Indian Ocean Territory

28 Solomon Islands

29 Virgin Islands, British

30 Brunei Darussalam

31 Bulgaria

32 Myanmar

33 Burundi

34 Belarus

35 Cambodia

36 Cameroon

37 Canada

38 Cape Verde

39 Cayman Islands

40 Central African Republic

41 Sri Lanka

42 Chad

43 Chile

44 China

45 Taiwan, Province of China

46 Christmas Island

47 Cocos (Keeling) Islands

48 Colombia

49 Comoros

50 Mayotte

51 Congo

52 Congo, Democratic Republic of the

53 Cook Islands

54 Costa Rica

55 Croatia

56 Cuba

57 Cyprus

58 Czech Republic

59 Benin

60 Denmark

61 Dominica

62 Dominican Republic

63 Ecuador

64 El Salvador

65 Equatorial Guinea

66 Ethiopia

67 Eritrea

68 Estonia

69 Faroe Islands

70 Falkland Islands (Malvinas)

71 South Georgia and the South Sandwich Islands

72 Fiji

73 Finland

74 Aland Islands

75 France

76 French Guiana

77 French Polynesia

78 French Southern Territories

79 Djibouti

80 Gabon

81 Georgia

82 Gambia

83 Palestinian Territory, Occupied

84 Germany

85 Ghana

86 Gibraltar

87 Kiribati

88 Greece

89 Greenland

90 Grenada

91 Guadeloupe

92 Guam

93 Guatemala

94 Guinea

95 Guyana

96 Haiti

97 Heard Island and McDonald Islands

98 Holy See (Vatican City State)

99 Honduras

100 Hong Kong

101 Hungary

102 Iceland

103 India

104 Indonesia

105 Iran, Islamic Republic of

106 Iraq

107 Ireland

108 Israel

109 Italy

110 Cote d'Ivoire

111 Jamaica

112 Japan

113 Kazakhstan

114 Jordan

115 Kenya

116 Korea, Democratic People's Republic of

117 Korea, Republic of

118 Kuwait

119 Kyrgyzstan

120 Lao People's Democratic Republic

121 Lebanon

122 Lesotho

123 Latvia

124 Liberia

125 Libyan Arab Jamahiriya

126 Liechtenstein

127 Lithuania

128 Luxembourg

129 Macao

130 Madagascar

131 Malawi

132 Malaysia

133 Maldives

134 Mali

135 Malta

136 Martinique

137 Mauritania

138 Mauritius

139 Mexico

140 Monaco

141 Mongolia

142 Moldova, Republic of

143 Montenegro

144 Montserrat

145 Morocco

146 Mozambique

147 Oman

148 Namibia

149 Nauru

150 Nepal

151 Netherlands

152 Netherlands Antilles

153 Aruba

154 New Caledonia

155 Vanuatu

156 New Zealand

157 Nicaragua

158 Niger

159 Nigeria

160 Niue

161 Norfolk Island

162 Norway

163 Northern Mariana Islands

164 United States Minor Outlying Islands

165 Micronesia, Federated States of

166 Marshall Islands

167 Palau

168 Pakistan

169 Panama

170 Papua New Guinea

171 Paraguay

172 Peru

173 Philippines

174 Pitcairn

175 Poland

176 Portugal

177 Guinea-Bissau

178 Timor-Leste

179 Puerto Rico

180 Qatar

181 Reunion

182 Romania

183 Russian Federation

184 Rwanda

185 Saint Barthelemy

186 Saint Helena

187 Saint Kitts and Nevis

188 Anguilla

189 Saint Lucia

190 Saint Martin (French part)

191 Saint Pierre and Miquelon

192 Saint Vincent and the Grenadines

193 San Marino

194 Sao Tome and Principe

195 Saudi Arabia

196 Senegal

197 Serbia

198 Seychelles

199 Sierra Leone

200 Singapore

201 Slovakia

202 Viet Nam

203 Slovenia

204 Somalia

205 South Africa

206 Zimbabwe

207 Spain

208 Western Sahara

209 Sudan

210 Suriname

211 Svalbard and Jan Mayen

212 Swaziland

213 Sweden

214 Switzerland

215 Syrian Arab Republic

216 Tajikistan

217 Thailand

218 Togo

219 Tokelau

220 Tonga

221 Trinidad and Tobago

222 United Arab Emirates

223 Tunisia

224 Turkey

225 Turkmenistan

226 Turks and Caicos Islands

227 Tuvalu

228 Uganda

229 Ukraine

230 Macedonia, the former Yugoslav Republic of

231 Egypt

232 United Kingdom

233 Guernsey

234 Jersey

235 Isle of Man

236 Tanzania, United Republic of

237 United States

238 Virgin Islands, U.S.

239 Burkina Faso

240 Uruguay

241 Uzbekistan

242 Venezuela, Bolivarian Republic of

243 Wallis and Futuna

244 Samoa

245 Yemen

246 Zambia

Available language codes:

1 Afrikaans

2 Albanian

3 Arabic

4 Armenian

5 Azerbaijani

6 Belorussian

7 Bhojpuri

8 Bosnian

9 Bulgarian

10 Burmese

11 Cantonese

12 Catalan

13 Chamorro

14 Chinese

15 Croatian

16 Czech

17 Danish

18 Dutch

19 English

20 Esperanto

21 Estonian

22 Farsi

23 Finnish

24 French

25 Gaelic

26 German

27 Greek

28 Gujarati

29 Hebrew

30 Hindi

31 Hungarian

32 Icelandic

33 Indonesian

34 Italian

35 Japanese

36 Khmer

37 Korean

38 Kurdish

39 Lao

40 Latvian

41 Lithuanian

42 Macedonian

43 Malay

44 Mandarin

45 Mongolian

46 Norwegian

47 Persian

48 Polish

49 Portuguese

50 Punjabi

51 Romanian

52 Russian

53 Serbian

54 Sindhi

55 Slovak

56 Slovenian

57 Somali

58 Spanish

59 Swahili

60 Swedish

61 Tagalog

62 Taiwanese

63 Tamil

64 Tatar

65 Thai

66 Turkish

67 Ukrainian

68 Urdu

69 Vietnamese

70 Welsh

71 Yiddish

72 Yoruba