DAmn
From Botdom Wiki
→
|
It is suggested that this page should be moved to Botdom Documentation. Please do not move the page by hand. It will be moved by an administrator with the full edit history. In the meantime, you may continue to edit the page as normal. You can discuss this decision on the talk page. |
- The correct title of this article is dAmn. The initial letter is capitalized due to technical limitations.
dAmn (the deviantART Message Network, or deviantART Messaging Network) is deviantART's real-time messaging network. Since its beginning, it has become one of the most popular communication features of deviantART.
Contents |
History
- This section is a stub. You can help Botdom Wiki by expanding it by clicking the edit button at the right.
dAmn was launched on August 7, 2004, when deviantART upgraded to version 4.
Official client
- This section is a stub. You can help Botdom Wiki by expanding it by clicking the edit button at the right.
dAmn's official client is run in a web browser using either a Mozilla Firefox extension, Flash or Java, and accompanied with JavaScript. The client is present at the chat subdomain of deviantart.com.
Authtokens
Any clients wishing to connect to dAmn need to provide an authtoken in the login packet. More information on this can be found here.
Protocol
dAmn has a raw protocol system, which makes building a bot much easier. dAmn runs on chat.deviantart.com (198.172.81.21), TCP port 3900.
This section aims to guide you through the protocols and each packet that can you can send or receive. Everything is seen from the client's point of view. All characters will be spelled out in this guide, however in languages like PHP, you might need to type \n instead of line breaks seen in packets. Variables will be shown in bold italics in the code. We will show every variable's meaning (unless it's already shown a paragraph before or the meaning is very simple). Optional parts are displayed in a grey color.
Basic packet format
Basic Explanation
The basic format of a dAmn packet looks like this:
packetname mainparam some=variables somemore=variables (Any characters can be used here) Main content is placed here.
Where mainparam is a parameter that's very relevant to the packet's subject, e.g. a username or chat room. Also, as said, remember that all packets end in a pure NULL character which is sometime represented as \0, \000 or chr(0). Most packets also need a line feed (aka Unix line break \n) before the NULL, however packets where the last part is distributed to the chat room (the send packet being the best example) does not need this.
If you used \n instead of line breaks, the example packet above would look like this:
packetname mainparam\nsome=variables\nsomemore=variables (Any characters can be used here)\n\nMain content is placed here.
In raw format, chat room names are formatted chat:name where name is the name of the chat room. Private chat room names are formatted pchat:user1:user2 where user1 and user2 is the names of the users who are in the private room. The usernames are sorted alphabetically, so e.g. "Albert" would go before "Zack".
Official Way
While looking at the source code for the official client, This is how its Officially broken down:
cmd param arg1=value1 arg2=value2 body
Some packets insert a sub-packet into the body (recv is one of them) and those sub-packets are formatted (and can be parsed by the official parser) just like their enclosing packet. There are times when a sub-packet will contian only argument's and a body and not have the cmd/param at the start. Also, Param is optional. See dAmn Packet Parser for an example easy way to parse packets.
Client packets
These are the packets that go from the client to the server.
dAmnClient (handshake)
This packet performs the initial handshake with the server before you continue logging in.
dAmnClient version agent=agent optionalparameter=value value optionalparameter2=value
The variable version is the version of the protocol which you are going to use. Only the newest version will work, if you use an older version, you will get disconnected. The current protocol version that is used is 0.3 (as of April 8 2008).
The agent variable is required. This is used to tell the server which kind of client/agent is used to connect to the server. Examples could be dAmn WebClient 0.7.pre-1 or futurism/beta 0.3. It is not your deviantART username. In addition to this, you can set any other variable you want. It is unknown whether the server takes action on these variables or saves them anywhere. In 0.1, variables weren't available in this packet.
You have to wait for a dAmnServer (handshake response) packet before you can go on to logging in.
login
After handshaking, you use this packet to log in to the server.
login username pk=authtoken
The username being the username you want to log in with, obviously, and the authtoken being your user account's dA authtoken. This is a hash value which changes every time you log in (unless you're using reusetoken) or log out. When you've logged in, you can see it in the cookie you receive from deviantART. In Firefox, this can be done by going to Tools > Settings > Privacy > View cookies and browsing. The cookie is a URL encoded list of variables, and the authtoken is one of those. It can also be seen in the source code when using the official dAmn client. Look for this: dAmn_Login( "username", "authtoken" );
After sending this packet, you have to wait for a server login packet in return before you can continue.
join
To join a chat room, send this packet:
join chat:chatroom
Very simple. chatroom is of course the name of the chat room you wish to join. To join a private chat, send this packet:
join pchat:user1:user2
Again very simple, the two users are the name of the users who should chat, which means one of those are you. They are sorted alphabetically.
part
Parting a chat room is almost the same as above:
part chat:chatroom
part pchat:user1:user2
pong
This is a very simple packet. As you'll learn later, the server occasionally sends a ping packet to check your connection. When it does that, simply return with this packet:
pong
However, if you want, you can also send this packet whenever you wish.
send
Here we're getting to what you may call the real stuff! You use this packet to send messages to a chat room. Mainly, there are three types of messages which you can send, which is defined by the middle part of the packet. (Actually, the send packet is used for many things, but we're going to cover the message related actions in this section.)
Based on testing done by doofsmack[1], it seems that if the message sub-packet (anything after the send chat:chatroom) is larger than 8192 bytes, the message is rejected and you are disconnected. All your sent messages are received back like all the other messages, so there's no need to show the message when sending it.
msg
This is the "ordinary" one that sends a normal message.
send chat:chatroom msg main content
Again, chatroom is the chat room in which you want to say something. As in all other places, it can also be in the pchat:user1:user2 format. And the content variable is simply the stuff you want to send!
action
But you can not only using the send command for messages. You also use it for /me actions. This only requires a slight change in the packet:
send chat:chatroom action main content
Which will output /me content.
npmsg
And the last thing you can send is also the npmsg (non parsed message) type:
send chat:chatroom npmsg main content
Non parsed messages nothing (like tags, emoticons, etc.) is parsed. That's what you send when you hold the shift button while entering your message on the official dAmn client.
promote
Now that we've really gotten into it, we'd like to do more! Here's the packet you use to promote people:
send chat:chatroom
promote username
privclass
In this one, username is the name of the user you want promoted. If you specify a privclass, the user will go directly to that privclass if you have the privileges to do so. If you don't specify any, the person will be promoted to the privclass just above the one he's currently in.
demote
Demoting is basically the same procedure as above.
send chat:chatroom
demote username
privclass
Again, username being the name of the user you want promoted. If you specify a privclass, the user will go directly to that privclass if you have the privileges to do so. If you don't specify any, the person will be promoted to the privclass just above the one he's currently in.
kick
You can kick people out from the room (if you have sufficient privileges) with this packet:
kick chat:chatroom
u=username
reason
This will kick username form chatroom with the reason reason. The reason can be empty.
ban
And if the annoying guys just keep coming back, you can ban them from the chatroom with this packet:
send chat:chatroom ban username
This will ban username from chatroom. Note: One line break is required at the end
unban
This is basically the same as ban.
send chat:chatroom unban username
This will demote username from chatroom to the guest privclass, even if he wasn't originally banned.
get
property
Use this command to receive properties for a special room if you haven't already received them.
get chat:chatroom p=property
Where property can be either title, topic, privclasses or members. It will then send you a property packet in return. You should receive those automatically when you join a room, but you can use this command to receive them again.
userinfo
You can also use this packet to get information about a user.
get login:username p=info
This will return a property packet with the information you'll need to know about username and its connection to dAmn.
set
Now that you know how to get a property, this packet lets you set a property:
set chat:chatroom p=property value
This sets the property (which can be either title or topic) to the value in chatroom if you have sufficient privileges.
admin
This packet lets you perform admin commands if you have the privileges, just like the /admin command or chatroom settings window in the official dAmn client:
send chat:chatroom admin command
Where command is the admin command you want to execute. Example: update privclass Name +smilies.
disconnect
This packet allows you to quit dAmn gracefully. It asks the server to disconnect you. The server replies with a part packet per room the user is joined to, followed by a disconnect packet.
disconnect
All rooms that you leave will show your reason for leaving as "quit".
Based on testing done by plaguethenet it appears that you cannot set the reason for disconnecting.
kill
This packet is used by dAmn admins to kill a connection. No error packets are sent by the server if the user is unprivileged (assuming the packet is properly formed), even if the username sent doesn't exist (as opposed to get packet, which will result in a namespace error packet).
kill login:username
reason
The reason is optional.
Server packets
This are the packets that go from the server to the client.
dAmnServer (handshake)
This is the server's reply packet to your dAmnClient handshake packet.
dAmnServer version
This packet is very simple. If the dAmn protocol version which you selected in your dAmnClient packet is supported by the server, it will return it here in the variable version. If you received this packet, you successfully handshaked and you're ready to log in!
login
When you've sent your log in packet, the server will response with a packet of the same name.
login username e=event symbol=symbol realname=Deviants Supplied Name typename=Type of Artist gpc=Server Privs
This packet will simply tell you whether your login as username was successful. We know of these values which event can have:
- ok
- Your login was successful!
- authentication failed
- Your username / authtoken combination wasn't correct.
- not privileged
- Unfortunately, you've been banned from the dAmn service.
- too many connections
- You have too many connections open (Limit is 20 connections per username.)
Furthermore, this packet also sends information about the account you're logging into. The values of symbol, realname, and typename are self-explanatory. In almost all instances gpc will equal guest.
join
When you've tried to join a room, you'll receive this packet in return which determines whether your join was successful.
join chat:chatroom e=event
event determines whether your join was successful. We know of these values event can have:
- ok
- You've successfully joined chatroom.
- not privileged
- You're banned from this room, or it's a private room.
- chatroom doesn't exist
- Self-explanatory. The room you're trying to join doesn't exist.
- bad namespace
- The name of the room you are trying to join uses bad characters that can't be in a room name.
Like everywhere else, the chatroom variable can also be in the pchat:user1:user2 format.
part
Like above, when you've tried to part a room, you'll receive this packet in return which determines whether your part was successful.
part chat:chatroom
e=event
r=reason
We know of these values event can have:
- ok
- You've successfully parted chatroom.
- not joined
- You haven't joined this room.
- bad namespace
- The name of the room you are trying to part uses bad characters that can't be in a room name.
In addition, there's also a reason parameter, which appears when you've been forced to part by the server or a Message Network Administrator. We know of these values reason can have:
- bad msg
- You were disconnected because your message had characters that was not supported, or your sub-packet wasn't correct.
- bad data
- You sent a packet that can't be used or doesn't exist.
- msg too big
- The message you were trying to send was longer than 8192 bytes.
- killed: reason
- A message network administrator closed your connection with reason.
property
This packet is sent by the server to set an object's property.
property chat:chatroom p=property by=who set the topic/title ts=time topic/title was set value
This assigns value to chatroom's property. We know of these values property can have:
- topic
- chatroom's topic.
- title
- chatroom's title.
- privclasses
- chatroom's privclasses.
- members
- The list of people currently in chatroom.
- login:username
- Whois information for username.
We'll write more about each property in a later section. You usually get the first four properties when you join a room, but they can also be received using the get packet. The last one is request-only.
whois
This packet is the server's whois packet
property login:username p=info usericon=usericon symbol=symbol realname=realname typename=typename gpc=global privs conn online=seconds online idle=seconds idle ns channel ns channel conn online=seconds online idle=seconds idle ns channel ns channel etc.
This packet is relatively easy to parse, ns and channel require special handly, But each conn subpacket is a seperate connection.
It should also be noted that this packet will not show pchat's that the user is joined, only chats from the normal namespace will be included.
recv
This is where stuff really happens! You use this server packet to receive messages of many kinds, determined by the value part of the packet.
msg
This is the packet you use to receive ordinary messages.
recv chat:chatroom msg main from=username content
This indicates that username has said content in chatroom. (And of course chatroom can be in the pchat:user1:user2 format.) When you send npmsgs, they will also end up here, however with unparsed emoticons and tags (which are html encoded with > etc).
action
This is the packet you use to receive /me actions.
recv chat:chatroom action main from=username content
This indicates that username has content'd in chatroom.
join
This is the packet you receive when someone else joins one of the rooms you are in.
recv chat:chatroom join username s=show
This indicates that username has joined chatroom; show is either a 1 or 0 indicating whether the client should display a join notification. Furthermore, this packet will also send you information about username, we'll cover that later.
part
Like above, this is the packet you receive when someone else parts one of the rooms you are in.
recv chat:chatroom
part username
r=reason
This indicates that username has parted chatroom with or without a reason. If it's blank, the user have only parted this chatroom, but still has a connection open. If there's a reason, username's connection was also closed at the same time as the part happened. We know of these values reason can have:
- connection closed
- The user closed connection.
- connection reset
- The user's connection was reset.
- timed out
- The user didn't respond to the server after a while, and was disconnected by the server.
- bad msg
- The message had characters that was not supported or sent an incorrect sub-packet, and was disconnected by the server.
- bad data
- The user sent a packet that can't be used or doesn't exist, and was disconnected by the server.
- msg too long
- The message which the user was trying to send was too long, and the user was disconnected by the server.
- send error
- We still don't know for sure what this means. We're guessing miscellaneous error that doesn't fall into any other category.
- quit
- the user gracefully disconnected from the server. (See disconnect)
- killed: reason
- A message network administrator closed the users connection with reason.
privchg
This is the packet you receive when someone gets promoted, demoted, banned or unbanned.
recv chat:chatroom privchg username by=username2 pc=privclass
This indicates that username was moved to privclass by username2.
kicked
This is the packet you receive when someone else gets kicked.
recv chat:chatroom
kicked username
by=username2
reason
This indicates that username has been kicked from chatroom by username2 with reason, which can be empty.
admin
This is when someone does some admin commands. They are different for each admin command. If the order of the privclasses in a room is changed the server sends a privclass property packet along with the admin packet.
create & update
This is the packet you receive when someone creates or updates a privclass.
recv chat:chatroom admin action p=privclass by=username name=privclassname privs=privileges
(With action being either create or update) This indicates that username created or updated the privclass privclassname with the privs privileges in chatroom.
rename & move
This is the packet you receive when someone renames a privclass or moves all users from one privclass to another.
recv chat:chatroom
admin action
p=privclass
by=username
prev=previousprivclassname
name=privclassname
n=usersaffected
If action is rename, then this indicates that username renamed the privclass previousprivclassname to privclassname. If the action is move, then this indicates that username moved all users from the privclass previousprivclassname to privclassname. The original privclass still exists. The parameter usersaffected then shows how many deviants were actually moved in the admin action. This parameter only exists if action is move.
remove
This is the packet you receive when someone removes a privclass.
recv chat:chatroom admin remove p=privclass by=username name=privclassname n=usersaffected
This simply indicates that username removed the privclass privclassname, and that usersaffected users were affected by this.
show
This is the packet you recieve when you send the admin command show. For privclasses you get this:
recv chat:chatroom admin show p=privclass privclassname privs
This does not need to be parsed and can be directly displayed. Its already preformatted.
If you send the admin command show users then you will get this:
recv chat:chatroom admin show p=users privclassname: user1 user2 .... userN privclassname: user1 user2 .... userN
This is also already formatted.
privclass
This is an error packet received after attempting to use the admin command in a channel.
recv chat:chatroom admin privclass p=action e=error command
command is the admin command that was sent by the client.
kicked
This is the packet you receive if you get kicked (not if anyone else does).
kicked chat:chatroom
by=username
reason
This indicates that username kicked you from chatroom with the eventual reason reason.
ping
To check your connection, the server will send you the ping packet.
ping
When you receive this packet, it is required that you send a pong packet in return, or you will be disconnected (timed out) by the server. The time it waits before disconnecting you seems to be 48 seconds. If there is no successful interaction between your client and the server within 96 seconds then it is likely that your client has been disconnected from the server. However, the maximum time it usually takes for a connection to time out appears to be around two minutes.
disconnect
This is the packet you receive if you fail to connect (or end up disconnecting) to the dAmn service somehow.
disconnect e=event
event indicates why you were disconnected. We know of these values event can have:
- ok
- The server has accepted your request to quit gracefully.
- killed
- You were killed by a message network administrator.
- no login
- You failed to start the connection process by handshaking and/or logging in.
- shutdown
- The server is temporarily shutting down. All users get disconnected.
Error packets
This is a list of server packets which are only used to report errors with client packets.
send
This is the packet you receive if an error occurs during a client send packet.
send chat:chatroom e=event
event specifies what the error is. We know of these values event can have:
- nothing to send
- You're trying to send an empty message.
- not privileged
- This could be many reason. Either you don't have privileges to do what you're trying to do, or you haven't joined the room in which you're trying to do something.
- not open
- You're trying to do something in a room that no one's in.
- format error
- There is a slight error in your packet syntax, but not a huge error, such as missing line breaks at the end.
- bad command
- The sub-packet you were trying to send was incorrect for this type of room.
kick
This is the packet you receive if an error occurs during a client kick packet.
kick chat:chatroom u=username e=event
event specifies what the error is. We know of these values event can have:
- no such member
- The user you're trying to kick isn't in the room, or you haven't joined the room in which you're trying to kick.
- not privileged
- You don't have +kick privileges, or the user you're trying to kick is in a class above you, is the creator of the room or is a Message Network Administrator.
get
This is the packet you receive if an error occurs during a client get packet.
get chat:chatroom p=property e=event
event specifies what the error is. We know of these values event can have:
- not joined
- You're trying to get a property for a room you haven't joined.
- unknown property
- This property doesn't exist.
set
This is the packet you receive if an error occurs during a client set packet.
set chat:chatroom p=property e=event
event specifies what the error is. We know of these values event can have:
- not joined
- You're trying to set a property for a room you haven't joined.
- unknown property
- This property doesn't exist.
- not privileged
- You don't have permission to set this property.
kill
This is the packet you receive if you send a kill packet with a malformed namespace. This is the only known error packet for kill packets.
kill login:username e=event
- bad namespace
- The username you specified does not exist or is not on dAmn.
- not privileged
- You don't have permission to kill the specified login, Which in most cases is true unless you're MN@.
References
- ↑ dAmnhack wiki on the dAmn protocol (Copyright (c) 2004-2005 Matthias Bauer, David Robson, Bernd Zeimetz and others - released under GNU FDL)
