{"_id":"552854af60c60f230003fb96","parentDoc":null,"user":"55282916d9e1db2d00cd923c","__v":52,"category":{"_id":"55284ed68962f339009a67e1","__v":6,"pages":["552854af60c60f230003fb96","5528553ad9e1db2d00cd9292","55286c7d391a362500d9b3f5","55290f5bceedaa0d00bc5c5b","56d1fb3d93f76e0b00bbc5e2","56d1fb6293f76e0b00bbc5e4"],"project":"552829408962f339009a678d","version":"552829408962f339009a6790","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-04-10T22:29:42.627Z","from_sync":false,"order":9,"slug":"protocol","title":"MTProto v2"},"project":"552829408962f339009a678d","version":{"_id":"552829408962f339009a6790","project":"552829408962f339009a678d","__v":26,"createdAt":"2015-04-10T19:49:20.516Z","releaseDate":"2015-04-10T19:49:20.516Z","categories":["552829418962f339009a6791","55284ed68962f339009a67e1","55286c73391a362500d9b3f4","552918f6b316811900149f59","5529b255d739240d00a3483e","553287590a578a0d008d4ff5","55329385e7d1fa0d003fc946","5550b55200420e0d00d1312f","55525fca953c9c0d00f507d7","559199695631432f002d358a","559d8d96980b801700d5ec7e","55c5e833cccdeb2d004e24b9","55d76504f662951900fc0e7d","55ea213cc62aa02f008229cd","56157b750f5ed00d00483dd8","561981fbac0924170069f4e8","561b8b1ea430930d0037ea67","563417428b86331700b488ca","56cd785bface161300dae0ec","56cdcc6e70db8a15006395f4","56cdf1b749abf10b0036a34a","56cedc8ce50c9c1b00830423","56e97ba8d825061900d1ac83","570d505228e6900e00477229","573614ca2ab52e1700c8e851","57d556a2496a3117004d70cf"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-04-10T22:54:39.937Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"auth":"required","params":[],"url":""},"isReference":false,"order":2,"body":"Connection Level describes messages for transmitting of connection packets, checking connection state and initialization of connection. On client applications Connection Level usually implemented separately for each platform.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"TCP Transport\"\n}\n[/block]\nBefore working with connection handshake is required to perform. Client can send data after handshake without waiting handshake completion. All data in TCP Transport is separated into frames. Before work client need to perform handshake. After successful handshake connection believed to be established.\n[block:callout]\n{\n  \"type\": \"danger\",\n  \"body\": \"TCP Transport use **slightly different encoding rules**. Main difference that there are no varint in scheme. bytes are encoded with length as int and raw bytes, byte[32] is a raw 32 bytes. This is done for predictable size of Frame.\",\n  \"title\": \"Different encoding rules\"\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"Frame {\\n\\t// Index of package starting from zero. \\n  // If packageIndex is broken connection need to be dropped.\\n\\tpackageIndex: int\\n  // Type of message\\n  header: byte\\n  // Package payload\\n  body: bytes\\n  // CRC32 of body\\n  crc32: int\\n}\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\nFrame can contain different data in body field depends on header value. \nIf header is equals to zero then payload is protocol object and **need to be sent to [Transport Level](doc:transport-level)**. Otherwise frame is signaling message. Unknown messages can be silently ignored.\n[block:callout]\n{\n  \"type\": \"danger\",\n  \"title\": \"Protocol package\",\n  \"body\": \"If header in frame **equals to zero**, then payload is protocol object and **need to be sent to [Transport Level](doc:transport-level)**. Otherwise frame is signaling message.\"\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"// header = 1\\n// Ping message can be sent from both sides\\nPing {\\n\\trandomBytes: bytes\\n}\\n\\n// header = 2\\n// Pong message need to be sent immediately after receving Ping message\\nPong {\\n\\t// Same bytes as in Ping package\\n\\trandomBytes: bytes\\n}\\n\\n// header = 3\\n// Notification about connection drop\\nDrop {\\n\\tmessageId: long\\n  errorCode: byte\\n  errorMessage: string\\n}\\n\\n// header = 4\\n// Sent by server when we need to temporary redirect to another server\\nRedirect {\\n\\thost: string\\n  port: int\\n  // Redirection timeout\\n  timeout: int\\n}\\n\\n// header = 6\\n// Proto package is received by destination peer. Used for determening of connection state\\nAck {\\n\\treceivedPackageIndex: int\\n}\\n\\n// header == 0xFF\\nHandshake {\\n  // Current MTProto revision\\n  // For Rev 2 need to eq 1\\n\\tprotoRevision: byte\\n  // API Major and Minor version\\n  apiMajorVersion: byte\\n\\tapiMinorVersion: byte\\n  // Some Random Bytes (suggested size is 32 bytes)\\n  randomBytes: bytes\\n}\\n\\n// header == 0xFE\\nHandshakeResponse {\\n  // return same versions as request, 0 - version is not supported\\n\\tprotoRevision: byte\\n  apiMajorVersion: byte\\n\\tapiMinorVersion: byte\\n  // SHA256 of randomBytes from request\\n  sha1: byte[32]\\n}\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Why we need randomBytes??\",\n  \"body\": \"You may wonder why we need such strange thing? But very often in some networks raw TCP data is changed in unpredictable way and we need some simple check that we have connection to good sever and not to some proxy that inject HTML to traffic.\\nSame technic is used in WebSockets.\"\n}\n[/block]","excerpt":"Lowest level of MTProto v2","slug":"connection-level","type":"basic","title":"Connection Level"}

Connection Level

Lowest level of MTProto v2

Connection Level describes messages for transmitting of connection packets, checking connection state and initialization of connection. On client applications Connection Level usually implemented separately for each platform. [block:api-header] { "type": "basic", "title": "TCP Transport" } [/block] Before working with connection handshake is required to perform. Client can send data after handshake without waiting handshake completion. All data in TCP Transport is separated into frames. Before work client need to perform handshake. After successful handshake connection believed to be established. [block:callout] { "type": "danger", "body": "TCP Transport use **slightly different encoding rules**. Main difference that there are no varint in scheme. bytes are encoded with length as int and raw bytes, byte[32] is a raw 32 bytes. This is done for predictable size of Frame.", "title": "Different encoding rules" } [/block] [block:code] { "codes": [ { "code": "Frame {\n\t// Index of package starting from zero. \n // If packageIndex is broken connection need to be dropped.\n\tpackageIndex: int\n // Type of message\n header: byte\n // Package payload\n body: bytes\n // CRC32 of body\n crc32: int\n}", "language": "text" } ] } [/block] Frame can contain different data in body field depends on header value. If header is equals to zero then payload is protocol object and **need to be sent to [Transport Level](doc:transport-level)**. Otherwise frame is signaling message. Unknown messages can be silently ignored. [block:callout] { "type": "danger", "title": "Protocol package", "body": "If header in frame **equals to zero**, then payload is protocol object and **need to be sent to [Transport Level](doc:transport-level)**. Otherwise frame is signaling message." } [/block] [block:code] { "codes": [ { "code": "// header = 1\n// Ping message can be sent from both sides\nPing {\n\trandomBytes: bytes\n}\n\n// header = 2\n// Pong message need to be sent immediately after receving Ping message\nPong {\n\t// Same bytes as in Ping package\n\trandomBytes: bytes\n}\n\n// header = 3\n// Notification about connection drop\nDrop {\n\tmessageId: long\n errorCode: byte\n errorMessage: string\n}\n\n// header = 4\n// Sent by server when we need to temporary redirect to another server\nRedirect {\n\thost: string\n port: int\n // Redirection timeout\n timeout: int\n}\n\n// header = 6\n// Proto package is received by destination peer. Used for determening of connection state\nAck {\n\treceivedPackageIndex: int\n}\n\n// header == 0xFF\nHandshake {\n // Current MTProto revision\n // For Rev 2 need to eq 1\n\tprotoRevision: byte\n // API Major and Minor version\n apiMajorVersion: byte\n\tapiMinorVersion: byte\n // Some Random Bytes (suggested size is 32 bytes)\n randomBytes: bytes\n}\n\n// header == 0xFE\nHandshakeResponse {\n // return same versions as request, 0 - version is not supported\n\tprotoRevision: byte\n apiMajorVersion: byte\n\tapiMinorVersion: byte\n // SHA256 of randomBytes from request\n sha1: byte[32]\n}", "language": "text" } ] } [/block] [block:callout] { "type": "info", "title": "Why we need randomBytes??", "body": "You may wonder why we need such strange thing? But very often in some networks raw TCP data is changed in unpredictable way and we need some simple check that we have connection to good sever and not to some proxy that inject HTML to traffic.\nSame technic is used in WebSockets." } [/block]