# Version 1.0.1
# Relax NG grammar for edklog2xml output
# See http://www.relaxng.org
# for documentation on Relax NG
grammar {
    start = EdkTraffic
    EdkTraffic = element edk-traffic {attribute version {"1.0.1"}, Opcode*}
    # Each opcode element describes one edonkey message.
    Opcode = element opcode
    {   # The message was either received or sent by the server.
        attribute dir {"received" | "sent"},
    	attribute TS {xsd:float},
        # IP address (or clientID) the message was received from or sent to.
        # IP addresses and clientIDs are anonymised.
        # The first one seen is assigned number 0 and the following ones
        # are assigned incrementing numbers.
    	attribute IP {xsd:unsignedInt}, 
        # type of the client: "high" for high ID, "low" for low ID.
        attribute type {"low"|"high"},
    	attribute port {xsd:unsignedShort},
    	(opcodesFileSearch | opcodesSourceSearch | opcodesMain)
    }

    # edonkey traffic is stored in three XML files, according to opcodes.

    # 'FileSearch.xml' contains keywords/metadata driven file search queries and answers;
    opcodesFileSearch = (GLOBSEARCHREQ3 | GLOBSEARCHREQ2 | GLOBSEARCHREQ | GLOBSEARCHRES) 
    # 'SourceSearch.xml' contains file-id driven source search queries, and answers;
    opcodesSourceSearch = (GLOBGETSOURCES | GLOBGETSOURCES2 | GLOBFOUNDSOURCES)
    # 'Main.xml' contains other queries (statistics, server-list...)
    opcodesMain = (GLOBSERVSTATREQ | GLOBSERVSTATRES | SERVER_DESC_REQ | SERVER_DESC_RES 
        | SERVER_LIST_REQ | SERVER_LIST_REQ2 | SERVER_LIST_RES) 

    # All the names for the opcodes are those used in the eMule source code,
    # available at http://www.emule-project.net/

    #####################################################################################
    # Keywords/metadata driven file search queries and answers
    #####################################################################################

    # Three variants for queries.

    # First variant: a tagSet describing the client capabilites (not fully documented),
    # and a tagList describing the query
    GLOBSEARCHREQ3 = element OP_GLOBSEARCHREQ3 {tagSet, tagList} 

    # Second and third variants: a tagList.
    GLOBSEARCHREQ2 = element OP_GLOBSEARCHREQ2 {tagList}
    GLOBSEARCHREQ = element OP_GLOBSEARCHREQ {tagList}

    # tagList represents a list of tags (they are defined formally below)
    # These tags can be named or not.
    # For all tags appearing in a tagList in the above queries,
    # if they are named their meaning is explicit.
    # Otherwise the meaning of the tags is not fully documented.
    # Most queries should consist of an anonString tag,
    # or several anonString tags separated by Bool tags.
    # Tags appearing in tagSets, named or not, are not documented.


    # Answer to a keywords/metadata file search query.
    # A list of file ids, together with, for each file, a description
    # and a source for it.
    GLOBSEARCHRES = element OP_GLOBSEARCHRES {fileInfoList} 

    #####################################################################################
    # Source search queries and answers
    #####################################################################################
    
    # Two variants for queries

    # Search by file id: a list of file ids.
    GLOBGETSOURCES = element OP_GLOBGETSOURCES {File+} 
    # Search by file id AND filesize: a list of file ids and file sizes
    GLOBGETSOURCES2 = element OP_GLOBGETSOURCES2 {sizedFile+} 

    # Answer to a source search query.
    # A list of file ids.
    # To each file id is associated a list of sources
    GLOBFOUNDSOURCES = element OP_GLOBFOUNDSOURCES {sourcesList+} 

    #####################################################################################
    # Statistics, etc.
    #####################################################################################

    # Query for statistics of the server.
    # A single integer (challenge number) used to identify
    # the query
    GLOBSERVSTATREQ = element OP_GLOBSERVSTATREQ {xsd:unsignedInt}

    # Answer to a GLOBSERSTATREQ query.
    # succession of 'info' fields.
    GLOBSERVSTATRES = element OP_GLOBSERVSTATRES {element info {xsd:unsignedInt}*}

    # Meaning of the info fields above (only the first three are mandatory):
    # 1 Challenge number
    # 2 Current number of connected users
    # 3 Current number of referenced files 
    # 4 Maximum number of users connected simultaneously
    # 5 Soft limit of number of files referenced
    # 6 Hard limit of number of files referenced
    # 7 UDP flags (32bits flags)
    # Flag details :
    # 0x01 Server supports OP_GLOBGETSOURCES opcode
    # 0x02 Server supports GET_FILES (undocumented)
    # 0x08 Server supports new-style tags
    # 0x10 Server supports unicode strings
    # 0x20 Server supports OP_GLOBGETSOURCES2 opcode
    # 0x100 Server supports 64 bits large file size
    # 0x200 Server supports UDP traffic obfuscation
    # 0x400 Server supports TCP traffic obfuscation

    # Undocumented traffic
    # The traffic below has been decoded into opcodes which themselves have been
    # decomposed into elements, but globally the meaning of these elements is
    # unknown

    # Query for a description of a server
    SERVER_DESC_REQ = element OP_SERVER_DESC_REQ {(Integer, Integer) | Integer | empty}

    # Answer to the above query: two strings or a tag list.
    # If mode is 0 then two strings are following, if 1 a tagList is following.
    SERVER_DESC_RES = element OP_SERVER_DESC_RES {
        element mode {xsd:unsignedByte}, 
        (tagList | String*)
    }

    SERVER_LIST_REQ = element OP_SERVER_LIST_REQ {Host}
    SERVER_LIST_REQ2 = element OP_SERVER_LIST_REQ2 {empty}
    SERVER_LIST_RES = element OP_SERVER_LIST_RES {serverList}

    # Not all opcodes can be received or sent by the server.
    # The different possibilities are listed below:
    #                           R   S
    # OP_GLOBSEARCHREQ3       | x |   |
    # OP_GLOBSEARCHREQ2       | x |   |
    # OP_GLOBSEARCHREQ        | x |   |
    # OP_GLOBSEARCHRES        |   | x |
    # OP_GLOBGETSOURCES       | x |   |
    # OP_GLOBGETSOURCES2      | x |   |
    # OP_GLOBFOUNDSOURCES     |   | x |
    # OP_GLOBSERVSTATREQ      | x | x |
    # OP_GLOBSERVSTATRES      | x | x |
    # OP_SERVER_DESC_REQ      | x | x |
    # OP_SERVER_DESC_RES      | x | x |
    # OP_SERVER_LIST_REQ      | x | x |
    # OP_SERVER_LIST_REQ2     | x | x |
    # OP_SERVER_LIST_RES      | x | x |

    #####################################################################################
    # Composed objects: Lists, etc.
    #####################################################################################
    
    # tagList and tagSet represent lists of tags
    tagList = element tags {attribute count {xsd:unsignedShort}, Tag*} 
    tagSet = element tags {attribute count {xsd:unsignedShort}, Tag*}

    # A list of servers 
    serverList = element server-list {attribute count {xsd:unsignedShort}, Host*} 
    # A peer or a server
    Host = element host {
        attribute IP {xsd:unsignedInt},
        attribute type {"low"|"high"},
        attribute port {xsd:unsignedShort}
    } 


    # Files are identified by a unique file-id.
    fileInfoList = element files {attribute count {xsd:unsignedShort}, fileInfo+}
    fileInfo = element file-info {attribute id {xsd:unsignedInt}, (tagList, Host)}

    # A list of sources for a file
    sourcesList = element file-sources {
        attribute id {xsd:unsignedInt},
        attribute count {xsd:unsignedShort},
        Host+
    } 

    File = element file {attribute id {xsd:unsignedInt}}
    sizedFile = element sized-file {
        attribute id {xsd:unsignedInt},
        attribute kb-size {xsd:unsignedLong}
    }

    #####################################################################################
    # Tags
    #####################################################################################

    # Tags are the basic building blocks of most of the traffic. 
    # Tags are typed values. 
    # Tags can be named or not. 
    Tag = (unnamedTag | namedTag)

    unnamedTag = (String | Bool | Integer | Byte | Word | kbSize | Limit)

    # Strins can be either anonymized or written as-is
    String = (plainString | anonString)

    plainString = element plain-string {text}
    anonString = element anon-string {text}
    Bool = element bool {xsd:int}
    Integer = element integer {xsd:unsignedInt}
    Byte = element byte {xsd:unsignedByte}
    Word = element word {xsd:unsignedShort}
    kbSize = element kb-size {xsd:unsignedInt}
    # Limit objects are used for representing constraints of the type:
    # a file must have a size of at most 1Gb and a bitrate of at least 64kb.
    # They are not fully documented.
    Limit = element limit{Integer, Byte, (String|Byte)}

    # When the second element of a Limit tag (Byte) has one of the values listed below,
    # this has the following meaning:
    # 0 EQUAL          
    # 1 GREATER       
    # 2 LESS          
    # 3 GREATER_EQUAL
    # 4 LESS_EQUAL    
    # 5 NOTEQUAL      
    

    namedTag = element named-tag {
        # The name of a tag is a description of its value.
        # The names of the tags are typed. They can be strings or bytes 
        # (this is different than the type of the tag itself).
        # The type of the name can be byte, plain-string or anon-string.
        element name-type {text},
        element name-value {text},
        # If the name is of type byte, the element name-meaning is present,
        # otherwise not.
        # The meanings are those from the opcodes.h file from the eMule source code.
        # If the meaning is unknown, it contains UNKNOWN.
        element name-meaning {text}?,
        unnamedTag
    }
}