1 /// Internal - Helper functions for the communication protocol. 2 module mysql.protocol.packet_helpers; 3 4 import std.algorithm; 5 import std.conv; 6 import std.datetime; 7 import std.exception; 8 import std.range; 9 import std.string; 10 import std.traits; 11 12 import mysql.exceptions; 13 import mysql.protocol.constants; 14 import mysql.protocol.extra_types; 15 import mysql.protocol.sockets; 16 import mysql.types; 17 18 /++ 19 Function to extract a time difference from a binary encoded row. 20 21 Time/date structures are packed by the server into a byte sub-packet 22 with a leading length byte, and a minimal number of bytes to embody the data. 23 24 Params: a = slice of a protocol packet beginning at the length byte for a chunk of time data 25 26 Returns: A populated or default initialized TimeDiff struct. 27 +/ 28 TimeDiff toTimeDiff(in ubyte[] a) pure 29 { 30 enforceEx!MYXProtocol(a.length, "Supplied byte array is zero length"); 31 TimeDiff td; 32 uint l = a[0]; 33 enforceEx!MYXProtocol(l == 0 || l == 5 || l == 8 || l == 12, "Bad Time length in binary row."); 34 if (l >= 5) 35 { 36 td.negative = (a[1] != 0); 37 td.days = (a[5] << 24) + (a[4] << 16) + (a[3] << 8) + a[2]; 38 } 39 if (l >= 8) 40 { 41 td.hours = a[6]; 42 td.minutes = a[7]; 43 td.seconds = a[8]; 44 } 45 // Note that the fractional seconds part is not stored by MySQL 46 return td; 47 } 48 49 /++ 50 Function to extract a time difference from a text encoded column value. 51 52 Text representations of a time difference are like -750:12:02 - 750 hours 53 12 minutes and two seconds ago. 54 55 Params: s = A string representation of the time difference. 56 Returns: A populated or default initialized TimeDiff struct. 57 +/ 58 TimeDiff toTimeDiff(string s) 59 { 60 TimeDiff td; 61 int t = parse!int(s); 62 if (t < 0) 63 { 64 td.negative = true; 65 t = -t; 66 } 67 td.hours = cast(ubyte) t%24; 68 td.days = cast(ubyte) t/24; 69 enforceEx!MYXProtocol(s.skipOver(":"), `Expected: ":"`); 70 td.minutes = parse!ubyte(s); 71 enforceEx!MYXProtocol(s.skipOver(":"), `Expected: ":"`); 72 td.seconds = parse!ubyte(s); 73 return td; 74 } 75 76 /++ 77 Function to extract a TimeOfDay from a binary encoded row. 78 79 Time/date structures are packed by the server into a byte sub-packet 80 with a leading length byte, and a minimal number of bytes to embody the data. 81 82 Params: a = slice of a protocol packet beginning at the length byte for a 83 chunk of time data. 84 Returns: A populated or default initialized std.datetime.TimeOfDay struct. 85 +/ 86 TimeOfDay toTimeOfDay(in ubyte[] a) pure 87 { 88 enforceEx!MYXProtocol(a.length, "Supplied byte array is zero length"); 89 uint l = a[0]; 90 enforceEx!MYXProtocol(l == 0 || l == 5 || l == 8 || l == 12, "Bad Time length in binary row."); 91 enforceEx!MYXProtocol(l >= 8, "Time column value is not in a time-of-day format"); 92 93 TimeOfDay tod; 94 tod.hour = a[6]; 95 tod.minute = a[7]; 96 tod.second = a[8]; 97 return tod; 98 } 99 100 /++ 101 Function to extract a TimeOfDay from a text encoded column value. 102 103 Text representations of a time of day are as in 14:22:02 104 105 Params: s = A string representation of the time. 106 Returns: A populated or default initialized std.datetime.TimeOfDay struct. 107 +/ 108 TimeOfDay toTimeOfDay(string s) 109 { 110 TimeOfDay tod; 111 tod.hour = parse!int(s); 112 enforceEx!MYXProtocol(tod.hour <= 24 && tod.hour >= 0, "Time column value is in time difference form"); 113 enforceEx!MYXProtocol(s.skipOver(":"), `Expected: ":"`); 114 tod.minute = parse!ubyte(s); 115 enforceEx!MYXProtocol(s.skipOver(":"), `Expected: ":"`); 116 tod.second = parse!ubyte(s); 117 return tod; 118 } 119 120 /++ 121 Function to pack a TimeOfDay into a binary encoding for transmission to the server. 122 123 Time/date structures are packed into a string of bytes with a leading length 124 byte, and a minimal number of bytes to embody the data. 125 126 Params: tod = TimeOfDay struct. 127 Returns: Packed ubyte[]. 128 +/ 129 ubyte[] pack(in TimeOfDay tod) pure nothrow 130 { 131 ubyte[] rv; 132 if (tod == TimeOfDay.init) 133 { 134 rv.length = 1; 135 rv[0] = 0; 136 } 137 else 138 { 139 rv.length = 9; 140 rv[0] = 8; 141 rv[6] = tod.hour; 142 rv[7] = tod.minute; 143 rv[8] = tod.second; 144 } 145 return rv; 146 } 147 148 /++ 149 Function to extract a Date from a binary encoded row. 150 151 Time/date structures are packed by the server into a byte sub-packet 152 with a leading length byte, and a minimal number of bytes to embody the data. 153 154 Params: a = slice of a protocol packet beginning at the length byte for a 155 chunk of Date data. 156 Returns: A populated or default initialized `std.datetime.Date` struct. 157 +/ 158 Date toDate(in ubyte[] a) pure 159 { 160 enforceEx!MYXProtocol(a.length, "Supplied byte array is zero length"); 161 if (a[0] == 0) 162 return Date(0,0,0); 163 164 enforceEx!MYXProtocol(a[0] >= 4, "Binary date representation is too short"); 165 int year = (a[2] << 8) + a[1]; 166 int month = cast(int) a[3]; 167 int day = cast(int) a[4]; 168 return Date(year, month, day); 169 } 170 171 /++ 172 Function to extract a Date from a text encoded column value. 173 174 Text representations of a Date are as in 2011-11-11 175 176 Params: s = A string representation of the time difference. 177 Returns: A populated or default initialized `std.datetime.Date` struct. 178 +/ 179 Date toDate(string s) 180 { 181 int year = parse!(ushort)(s); 182 enforceEx!MYXProtocol(s.skipOver("-"), `Expected: "-"`); 183 int month = parse!(ubyte)(s); 184 enforceEx!MYXProtocol(s.skipOver("-"), `Expected: "-"`); 185 int day = parse!(ubyte)(s); 186 return Date(year, month, day); 187 } 188 189 /++ 190 Function to pack a Date into a binary encoding for transmission to the server. 191 192 Time/date structures are packed into a string of bytes with a leading length 193 byte, and a minimal number of bytes to embody the data. 194 195 Params: dt = `std.datetime.Date` struct. 196 Returns: Packed ubyte[]. 197 +/ 198 ubyte[] pack(in Date dt) pure nothrow 199 { 200 ubyte[] rv; 201 if (dt.year < 0) 202 { 203 rv.length = 1; 204 rv[0] = 0; 205 } 206 else 207 { 208 rv.length = 5; 209 rv[0] = 4; 210 rv[1] = cast(ubyte) ( dt.year & 0xff); 211 rv[2] = cast(ubyte) ((dt.year >> 8) & 0xff); 212 rv[3] = cast(ubyte) dt.month; 213 rv[4] = cast(ubyte) dt.day; 214 } 215 return rv; 216 } 217 218 /++ 219 Function to extract a DateTime from a binary encoded row. 220 221 Time/date structures are packed by the server into a byte sub-packet 222 with a leading length byte, and a minimal number of bytes to embody the data. 223 224 Params: a = slice of a protocol packet beginning at the length byte for a 225 chunk of DateTime data 226 Returns: A populated or default initialized `std.datetime.DateTime` struct. 227 +/ 228 DateTime toDateTime(in ubyte[] a) pure 229 { 230 enforceEx!MYXProtocol(a.length, "Supplied byte array is zero length"); 231 if (a[0] == 0) 232 return DateTime(); 233 234 enforceEx!MYXProtocol(a[0] >= 4, "Supplied ubyte[] is not long enough"); 235 int year = (a[2] << 8) + a[1]; 236 int month = a[3]; 237 int day = a[4]; 238 DateTime dt; 239 if (a[0] == 4) 240 { 241 dt = DateTime(year, month, day); 242 } 243 else 244 { 245 enforceEx!MYXProtocol(a[0] >= 7, "Supplied ubyte[] is not long enough"); 246 int hour = a[5]; 247 int minute = a[6]; 248 int second = a[7]; 249 dt = DateTime(year, month, day, hour, minute, second); 250 } 251 return dt; 252 } 253 254 /++ 255 Function to extract a DateTime from a text encoded column value. 256 257 Text representations of a DateTime are as in 2011-11-11 12:20:02 258 259 Params: s = A string representation of the time difference. 260 Returns: A populated or default initialized `std.datetime.DateTime` struct. 261 +/ 262 DateTime toDateTime(string s) 263 { 264 int year = parse!(ushort)(s); 265 enforceEx!MYXProtocol(s.skipOver("-"), `Expected: "-"`); 266 int month = parse!(ubyte)(s); 267 enforceEx!MYXProtocol(s.skipOver("-"), `Expected: "-"`); 268 int day = parse!(ubyte)(s); 269 enforceEx!MYXProtocol(s.skipOver(" "), `Expected: " "`); 270 int hour = parse!(ubyte)(s); 271 enforceEx!MYXProtocol(s.skipOver(":"), `Expected: ":"`); 272 int minute = parse!(ubyte)(s); 273 enforceEx!MYXProtocol(s.skipOver(":"), `Expected: ":"`); 274 int second = parse!(ubyte)(s); 275 return DateTime(year, month, day, hour, minute, second); 276 } 277 278 /++ 279 Function to extract a DateTime from a ulong. 280 281 This is used to support the TimeStamp struct. 282 283 Params: x = A ulong e.g. 20111111122002UL. 284 Returns: A populated `std.datetime.DateTime` struct. 285 +/ 286 DateTime toDateTime(ulong x) 287 { 288 int second = cast(int) (x%100); 289 x /= 100; 290 int minute = cast(int) (x%100); 291 x /= 100; 292 int hour = cast(int) (x%100); 293 x /= 100; 294 int day = cast(int) (x%100); 295 x /= 100; 296 int month = cast(int) (x%100); 297 x /= 100; 298 int year = cast(int) (x%10000); 299 // 2038-01-19 03:14:07 300 enforceEx!MYXProtocol(year >= 1970 && year < 2039, "Date/time out of range for 2 bit timestamp"); 301 enforceEx!MYXProtocol(year != 2038 || (month < 1 && day < 19 && hour < 3 && minute < 14 && second < 7), 302 "Date/time out of range for 2 bit timestamp"); 303 return DateTime(year, month, day, hour, minute, second); 304 } 305 306 /++ 307 Function to pack a DateTime into a binary encoding for transmission to the server. 308 309 Time/date structures are packed into a string of bytes with a leading length byte, 310 and a minimal number of bytes to embody the data. 311 312 Params: dt = `std.datetime.DateTime` struct. 313 Returns: Packed ubyte[]. 314 +/ 315 ubyte[] pack(in DateTime dt) pure nothrow 316 { 317 uint len = 1; 318 if (dt.year || dt.month || dt.day) len = 5; 319 if (dt.hour || dt.minute|| dt.second) len = 8; 320 ubyte[] rv; 321 rv.length = len; 322 rv[0] = cast(ubyte)(rv.length - 1); // num bytes 323 if(len >= 5) 324 { 325 rv[1] = cast(ubyte) ( dt.year & 0xff); 326 rv[2] = cast(ubyte) ((dt.year >> 8) & 0xff); 327 rv[3] = cast(ubyte) dt.month; 328 rv[4] = cast(ubyte) dt.day; 329 } 330 if(len == 8) 331 { 332 rv[5] = cast(ubyte) dt.hour; 333 rv[6] = cast(ubyte) dt.minute; 334 rv[7] = cast(ubyte) dt.second; 335 } 336 return rv; 337 } 338 339 340 T consume(T)(MySQLSocket conn) pure { 341 ubyte[T.sizeof] buffer; 342 conn.read(buffer); 343 ubyte[] rng = buffer; 344 return consume!T(rng); 345 } 346 347 string consume(T:string, ubyte N=T.sizeof)(ref ubyte[] packet) pure 348 { 349 return packet.consume!string(N); 350 } 351 352 string consume(T:string)(ref ubyte[] packet, size_t N) pure 353 in 354 { 355 assert(packet.length >= N); 356 } 357 body 358 { 359 return cast(string)packet.consume(N); 360 } 361 362 /// Returns N number of bytes from the packet and advances the array 363 ubyte[] consume()(ref ubyte[] packet, size_t N) pure nothrow 364 in 365 { 366 assert(packet.length >= N); 367 } 368 body 369 { 370 auto result = packet[0..N]; 371 packet = packet[N..$]; 372 return result; 373 } 374 375 T decode(T:ulong)(in ubyte[] packet, size_t n) pure nothrow 376 { 377 switch(n) 378 { 379 case 8: return packet.decode!(T, 8)(); 380 case 4: return packet.decode!(T, 4)(); 381 case 3: return packet.decode!(T, 3)(); 382 case 2: return packet.decode!(T, 2)(); 383 case 1: return packet.decode!(T, 1)(); 384 default: assert(0); 385 } 386 } 387 388 T consume(T)(ref ubyte[] packet, int n) pure nothrow 389 if(isIntegral!T) 390 { 391 switch(n) 392 { 393 case 8: return packet.consume!(T, 8)(); 394 case 4: return packet.consume!(T, 4)(); 395 case 3: return packet.consume!(T, 3)(); 396 case 2: return packet.consume!(T, 2)(); 397 case 1: return packet.consume!(T, 1)(); 398 default: assert(0); 399 } 400 } 401 402 TimeOfDay consume(T:TimeOfDay, ubyte N=T.sizeof)(ref ubyte[] packet) pure 403 in 404 { 405 static assert(N == T.sizeof); 406 } 407 body 408 { 409 enforceEx!MYXProtocol(packet.length, "Supplied byte array is zero length"); 410 uint length = packet.front; 411 enforceEx!MYXProtocol(length == 0 || length == 5 || length == 8 || length == 12, "Bad Time length in binary row."); 412 enforceEx!MYXProtocol(length >= 8, "Time column value is not in a time-of-day format"); 413 414 packet.popFront(); // length 415 auto bytes = packet.consume(length); 416 417 // TODO: What are the fields in between!?! Blank Date? 418 TimeOfDay tod; 419 tod.hour = bytes[5]; 420 tod.minute = bytes[6]; 421 tod.second = bytes[7]; 422 return tod; 423 } 424 425 Date consume(T:Date, ubyte N=T.sizeof)(ref ubyte[] packet) pure 426 in 427 { 428 static assert(N == T.sizeof); 429 } 430 body 431 { 432 return toDate(packet.consume(5)); 433 } 434 435 DateTime consume(T:DateTime, ubyte N=T.sizeof)(ref ubyte[] packet) pure 436 in 437 { 438 assert(packet.length); 439 assert(N == T.sizeof); 440 } 441 body 442 { 443 auto numBytes = packet.consume!ubyte(); 444 if(numBytes == 0) 445 return DateTime(); 446 447 enforceEx!MYXProtocol(numBytes >= 4, "Supplied packet is not large enough to store DateTime"); 448 449 int year = packet.consume!ushort(); 450 int month = packet.consume!ubyte(); 451 int day = packet.consume!ubyte(); 452 int hour = 0; 453 int minute = 0; 454 int second = 0; 455 if(numBytes > 4) 456 { 457 enforceEx!MYXProtocol(numBytes >= 7, "Supplied packet is not large enough to store a DateTime with TimeOfDay"); 458 hour = packet.consume!ubyte(); 459 minute = packet.consume!ubyte(); 460 second = packet.consume!ubyte(); 461 } 462 return DateTime(year, month, day, hour, minute, second); 463 } 464 465 466 @property bool hasEnoughBytes(T, ubyte N=T.sizeof)(in ubyte[] packet) pure 467 in 468 { 469 static assert(T.sizeof >= N, T.stringof~" not large enough to store "~to!string(N)~" bytes"); 470 } 471 body 472 { 473 return packet.length >= N; 474 } 475 476 T decode(T, ubyte N=T.sizeof)(in ubyte[] packet) pure nothrow 477 if(isIntegral!T) 478 in 479 { 480 static assert(N == 1 || N == 2 || N == 3 || N == 4 || N == 8, "Cannot decode integral value. Invalid size: "~N.stringof); 481 static assert(T.sizeof >= N, T.stringof~" not large enough to store "~to!string(N)~" bytes"); 482 assert(packet.hasEnoughBytes!(T,N), "packet not long enough to contain all bytes needed for "~T.stringof); 483 } 484 body 485 { 486 T value = 0; 487 static if(N == 8) // 64 bit 488 { 489 value |= cast(T)(packet[7]) << (8*7); 490 value |= cast(T)(packet[6]) << (8*6); 491 value |= cast(T)(packet[5]) << (8*5); 492 value |= cast(T)(packet[4]) << (8*4); 493 } 494 static if(N >= 4) // 32 bit 495 { 496 value |= cast(T)(packet[3]) << (8*3); 497 } 498 static if(N >= 3) // 24 bit 499 { 500 value |= cast(T)(packet[2]) << (8*2); 501 } 502 static if(N >= 2) // 16 bit 503 { 504 value |= cast(T)(packet[1]) << (8*1); 505 } 506 static if(N >= 1) // 8 bit 507 { 508 value |= cast(T)(packet[0]) << (8*0); 509 } 510 return value; 511 } 512 513 T consume(T, ubyte N=T.sizeof)(ref ubyte[] packet) pure nothrow 514 if(isIntegral!T) 515 in 516 { 517 static assert(N == 1 || N == 2 || N == 3 || N == 4 || N == 8, "Cannot consume integral value. Invalid size: "~N.stringof); 518 static assert(T.sizeof >= N, T.stringof~" not large enough to store "~to!string(N)~" bytes"); 519 assert(packet.hasEnoughBytes!(T,N), "packet not long enough to contain all bytes needed for "~T.stringof); 520 } 521 body 522 { 523 // The uncommented line triggers a template deduction error, 524 // so we need to store a temporary first 525 // could the problem be method chaining? 526 //return packet.consume(N).decode!(T, N)(); 527 auto bytes = packet.consume(N); 528 return bytes.decode!(T, N)(); 529 } 530 531 532 T myto(T)(string value) 533 { 534 static if(is(T == DateTime)) 535 return toDateTime(value); 536 else static if(is(T == Date)) 537 return toDate(value); 538 else static if(is(T == TimeOfDay)) 539 return toTimeOfDay(value); 540 else 541 return to!T(value); 542 } 543 544 T decode(T, ubyte N=T.sizeof)(in ubyte[] packet) pure nothrow 545 if(isFloatingPoint!T) 546 in 547 { 548 static assert((is(T == float) && N == float.sizeof) 549 || is(T == double) && N == double.sizeof); 550 } 551 body 552 { 553 T result = 0; 554 (cast(ubyte*)&result)[0..T.sizeof] = packet[0..T.sizeof]; 555 return result; 556 } 557 558 T consume(T, ubyte N=T.sizeof)(ref ubyte[] packet) pure nothrow 559 if(isFloatingPoint!T) 560 in 561 { 562 static assert((is(T == float) && N == float.sizeof) 563 || is(T == double) && N == double.sizeof); 564 } 565 body 566 { 567 return packet.consume(T.sizeof).decode!T(); 568 } 569 570 571 SQLValue consumeBinaryValueIfComplete(T, int N=T.sizeof)(ref ubyte[] packet, bool unsigned) 572 { 573 SQLValue result; 574 575 // Length of DateTime packet is NOT DateTime.sizeof, it can be 1, 5 or 8 bytes 576 static if(is(T==DateTime)) 577 result.isIncomplete = packet.length < 1; 578 else 579 result.isIncomplete = packet.length < N; 580 581 // isNull should have been handled by the caller as the binary format uses a 582 // null bitmap, and we don't have access to that information at this point 583 assert(!result.isNull); 584 if(!result.isIncomplete) 585 { 586 // only integral types is unsigned 587 static if(isIntegral!T) 588 { 589 if(unsigned) 590 result.value = packet.consume!(Unsigned!T)(); 591 else 592 result.value = packet.consume!(Signed!T)(); 593 } 594 else 595 { 596 // TODO: DateTime values etc might be incomplete! 597 result.value = packet.consume!(T, N)(); 598 } 599 } 600 return result; 601 } 602 603 SQLValue consumeNonBinaryValueIfComplete(T)(ref ubyte[] packet, bool unsigned) 604 { 605 SQLValue result; 606 auto lcb = packet.decode!LCB(); 607 result.isIncomplete = lcb.isIncomplete || packet.length < (lcb.value+lcb.totalBytes); 608 result.isNull = lcb.isNull; 609 if(!result.isIncomplete) 610 { 611 // The packet has all the data we need, so we'll remove the LCB 612 // and convert the data 613 packet.skip(lcb.totalBytes); 614 assert(packet.length >= lcb.value); 615 auto value = cast(string) packet.consume(cast(size_t)lcb.value); 616 617 if(!result.isNull) 618 { 619 assert(!result.isIncomplete); 620 assert(!result.isNull); 621 static if(isIntegral!T) 622 { 623 if(unsigned) 624 result.value = to!(Unsigned!T)(value); 625 else 626 result.value = to!(Signed!T)(value); 627 } 628 else 629 { 630 static if(isArray!T) 631 { 632 // to!() crashes when trying to convert empty strings 633 // to arrays, so we have this hack to just store any 634 // empty array in those cases 635 if(!value.length) 636 result.value = T.init; 637 else 638 result.value = cast(T)value.dup; 639 640 } 641 else 642 { 643 // TODO: DateTime values etc might be incomplete! 644 result.value = myto!T(value); 645 } 646 } 647 } 648 } 649 return result; 650 } 651 652 SQLValue consumeIfComplete(T, int N=T.sizeof)(ref ubyte[] packet, bool binary, bool unsigned) 653 { 654 return binary 655 ? packet.consumeBinaryValueIfComplete!(T, N)(unsigned) 656 : packet.consumeNonBinaryValueIfComplete!T(unsigned); 657 } 658 659 SQLValue consumeIfComplete()(ref ubyte[] packet, SQLType sqlType, bool binary, bool unsigned, ushort charSet) 660 { 661 switch(sqlType) 662 { 663 default: assert(false, "Unsupported SQL type "~to!string(sqlType)); 664 case SQLType.NULL: 665 SQLValue result; 666 result.isIncomplete = false; 667 result.isNull = true; 668 return result; 669 case SQLType.TINY: 670 return packet.consumeIfComplete!byte(binary, unsigned); 671 case SQLType.SHORT: 672 return packet.consumeIfComplete!short(binary, unsigned); 673 case SQLType.INT24: 674 return packet.consumeIfComplete!(int, 3)(binary, unsigned); 675 case SQLType.INT: 676 return packet.consumeIfComplete!int(binary, unsigned); 677 case SQLType.LONGLONG: 678 return packet.consumeIfComplete!long(binary, unsigned); 679 case SQLType.FLOAT: 680 return packet.consumeIfComplete!float(binary, unsigned); 681 case SQLType.DOUBLE: 682 return packet.consumeIfComplete!double(binary, unsigned); 683 case SQLType.TIMESTAMP: 684 return packet.consumeIfComplete!DateTime(binary, unsigned); 685 case SQLType.TIME: 686 return packet.consumeIfComplete!TimeOfDay(binary, unsigned); 687 case SQLType.YEAR: 688 return packet.consumeIfComplete!ushort(binary, unsigned); 689 case SQLType.DATE: 690 return packet.consumeIfComplete!Date(binary, unsigned); 691 case SQLType.DATETIME: 692 return packet.consumeIfComplete!DateTime(binary, unsigned); 693 case SQLType.VARCHAR: 694 case SQLType.ENUM: 695 case SQLType.SET: 696 case SQLType.VARSTRING: 697 case SQLType.STRING: 698 case SQLType.NEWDECIMAL: 699 return packet.consumeIfComplete!string(false, unsigned); 700 case SQLType.TINYBLOB: 701 case SQLType.MEDIUMBLOB: 702 case SQLType.BLOB: 703 case SQLType.LONGBLOB: 704 case SQLType.BIT: // Yes, BIT. See note below. 705 706 // TODO: This line should work. Why doesn't it? 707 //return packet.consumeIfComplete!(ubyte[])(binary, unsigned); 708 709 auto lcb = packet.consumeIfComplete!LCB(); 710 assert(!lcb.isIncomplete); 711 SQLValue result; 712 result.isIncomplete = false; 713 result.isNull = lcb.isNull; 714 if(result.isNull) 715 { 716 // TODO: consumeIfComplete!LCB should be adjusted to do 717 // this itself, but not until I'm certain that nothing 718 // is reliant on the current behavior. 719 packet.popFront(); // LCB length 720 } 721 else 722 { 723 auto data = packet.consume(cast(size_t)lcb.value); 724 if(charSet == 0x3F) // CharacterSet == binary 725 result.value = data; // BLOB-ish 726 else 727 result.value = cast(string)data; // TEXT-ish 728 } 729 730 // Type BIT is treated as a length coded binary (like a BLOB or VARCHAR), 731 // not like an integral type. So convert the binary data to a bool. 732 // See: http://dev.mysql.com/doc/internals/en/binary-protocol-value.html 733 if(sqlType == SQLType.BIT) 734 { 735 enforceEx!MYXProtocol(result.value.length == 1, 736 "Expected BIT to arrive as an LCB with length 1, but got length "~to!string(result.value.length)); 737 738 result.value = result.value[0] == 1; 739 } 740 741 return result; 742 } 743 } 744 745 /++ 746 Extract number of bytes used for this LCB 747 748 Returns the number of bytes required to store this LCB 749 750 See_Also: $(LINK http://forge.mysql.com/wiki/MySQL_Internals_ClientServer_Protocol#Elements) 751 752 Returns: 0 if it's a null value, or number of bytes in other cases 753 +/ 754 byte getNumLCBBytes(in ubyte lcbHeader) pure nothrow 755 { 756 switch(lcbHeader) 757 { 758 case 251: return 0; // null 759 case 0: .. case 250: return 1; // 8-bit 760 case 252: return 2; // 16-bit 761 case 253: return 3; // 24-bit 762 case 254: return 8; // 64-bit 763 764 case 255: 765 default: 766 assert(0); 767 } 768 assert(0); 769 } 770 771 772 /++ 773 Decodes a Length Coded Binary from a packet 774 775 See_Also: struct `mysql.protocol.extra_types.LCB` 776 777 Params: 778 packet = A packet that starts with a LCB. The bytes is popped off 779 iff the packet is complete. See `mysql.protocol.extra_types.LCB`. 780 781 Returns: A decoded LCB value 782 +/ 783 T consumeIfComplete(T:LCB)(ref ubyte[] packet) pure nothrow 784 in 785 { 786 assert(packet.length >= 1, "packet has to include at least the LCB length byte"); 787 } 788 body 789 { 790 auto lcb = packet.decodeLCBHeader(); 791 if(lcb.isNull || lcb.isIncomplete) 792 return lcb; 793 794 if(lcb.numBytes > 1) 795 { 796 // We know it's complete, so we have to start consuming the LCB 797 // Single byte values doesn't have a length 798 packet.popFront(); // LCB length 799 } 800 801 assert(packet.length >= lcb.numBytes); 802 803 lcb.value = packet.consume!ulong(lcb.numBytes); 804 return lcb; 805 } 806 807 LCB decodeLCBHeader(in ubyte[] packet) pure nothrow 808 in 809 { 810 assert(packet.length >= 1, "packet has to include at least the LCB length byte"); 811 } 812 body 813 { 814 LCB lcb; 815 lcb.numBytes = getNumLCBBytes(packet.front); 816 if(lcb.numBytes == 0) 817 { 818 lcb.isNull = true; 819 return lcb; 820 } 821 822 assert(!lcb.isNull); 823 // -1 for LCB length as we haven't popped it off yet 824 lcb.isIncomplete = (lcb.numBytes > 1) && (packet.length-1 < lcb.numBytes); 825 if(lcb.isIncomplete) 826 { 827 // Not enough bytes to store data. We don't remove any data, and expect 828 // the caller to check isIncomplete and take action to fetch more data 829 // and call this method at a later time 830 return lcb; 831 } 832 833 assert(!lcb.isIncomplete); 834 return lcb; 835 } 836 837 /++ 838 Decodes a Length Coded Binary from a packet 839 840 See_Also: struct `mysql.protocol.extra_types.LCB` 841 842 Params: 843 packet = A packet that starts with a LCB. See `mysql.protocol.extra_types.LCB`. 844 845 Returns: A decoded LCB value 846 +/ 847 LCB decode(T:LCB)(in ubyte[] packet) pure nothrow 848 in 849 { 850 assert(packet.length >= 1, "packet has to include at least the LCB length byte"); 851 } 852 body 853 { 854 auto lcb = packet.decodeLCBHeader(); 855 if(lcb.isNull || lcb.isIncomplete) 856 return lcb; 857 assert(packet.length >= lcb.totalBytes); 858 859 if(lcb.numBytes == 0) 860 lcb.value = 0; 861 else if(lcb.numBytes == 1) 862 lcb.value = packet.decode!ulong(lcb.numBytes); 863 else 864 { 865 // Skip the throwaway byte that indicated "at least 2 more bytes coming" 866 lcb.value = packet[1..$].decode!ulong(lcb.numBytes); 867 } 868 869 return lcb; 870 } 871 872 /++ 873 Parse Length Coded String 874 875 See_Also: $(LINK http://forge.mysql.com/wiki/MySQL_Internals_ClientServer_Protocol#Elements) 876 +/ 877 string consume(T:LCS)(ref ubyte[] packet) pure 878 in 879 { 880 assert(packet.length >= 1, "LCS packet needs to store at least the LCB header"); 881 } 882 body 883 { 884 auto lcb = packet.consumeIfComplete!LCB(); 885 assert(!lcb.isIncomplete); 886 if(lcb.isNull) 887 return null; 888 enforceEx!MYXProtocol(lcb.value <= uint.max, "Protocol Length Coded String is too long"); 889 return cast(string)packet.consume(cast(size_t)lcb.value).idup; 890 } 891 892 /++ 893 Skips over n items, advances the array, and return the newly advanced array 894 to allow method chaining. 895 +/ 896 T[] skip(T)(ref T[] array, size_t n) pure nothrow 897 in 898 { 899 assert(n <= array.length); 900 } 901 body 902 { 903 array = array[n..$]; 904 return array; 905 } 906 907 /++ 908 Converts a value into a sequence of bytes and fills the supplied array. 909 910 Params: 911 IsInt24 = If only the most significant 3 bytes from the value should be used. 912 value = The value to add to array. 913 array = The array we should add the values for. It has to be large enough, 914 and the values are packed starting index 0. 915 +/ 916 void packInto(T, bool IsInt24 = false)(T value, ubyte[] array) pure nothrow 917 in 918 { 919 static if(IsInt24) 920 assert(array.length >= 3); 921 else 922 assert(array.length >= T.sizeof, "Not enough space to unpack "~T.stringof); 923 } 924 body 925 { 926 static if(T.sizeof >= 1) 927 { 928 array[0] = cast(ubyte) (value >> 8*0) & 0xff; 929 } 930 static if(T.sizeof >= 2) 931 { 932 array[1] = cast(ubyte) (value >> 8*1) & 0xff; 933 } 934 static if(!IsInt24) 935 { 936 static if(T.sizeof >= 4) 937 { 938 array[2] = cast(ubyte) (value >> 8*2) & 0xff; 939 array[3] = cast(ubyte) (value >> 8*3) & 0xff; 940 } 941 static if(T.sizeof >= 8) 942 { 943 array[4] = cast(ubyte) (value >> 8*4) & 0xff; 944 array[5] = cast(ubyte) (value >> 8*5) & 0xff; 945 array[6] = cast(ubyte) (value >> 8*6) & 0xff; 946 array[7] = cast(ubyte) (value >> 8*7) & 0xff; 947 } 948 } 949 else 950 { 951 array[2] = cast(ubyte) (value >> 8*2) & 0xff; 952 } 953 } 954 955 ubyte[] packLength(size_t l, out size_t offset) pure nothrow 956 out(result) 957 { 958 assert(result.length >= 1); 959 } 960 body 961 { 962 ubyte[] t; 963 if (!l) 964 { 965 t.length = 1; 966 t[0] = 0; 967 } 968 else if (l <= 250) 969 { 970 t.length = 1+l; 971 t[0] = cast(ubyte) l; 972 offset = 1; 973 } 974 else if (l <= 0xffff) // 16-bit 975 { 976 t.length = 3+l; 977 t[0] = 252; 978 packInto(cast(ushort)l, t[1..3]); 979 offset = 3; 980 } 981 else if (l < 0xffffff) // 24-bit 982 { 983 t.length = 4+l; 984 t[0] = 253; 985 packInto!(uint, true)(cast(uint)l, t[1..4]); 986 offset = 4; 987 } 988 else // 64-bit 989 { 990 ulong u = cast(ulong) l; 991 t.length = 9+l; 992 t[0] = 254; 993 u.packInto(t[1..9]); 994 offset = 9; 995 } 996 return t; 997 } 998 999 ubyte[] packLCS(void[] a) pure nothrow 1000 { 1001 size_t offset; 1002 ubyte[] t = packLength(a.length, offset); 1003 if (t[0]) 1004 t[offset..$] = (cast(ubyte[]) a)[0..$]; 1005 return t; 1006 } 1007 1008 1009 debug(MYSQLN_TESTS) 1010 unittest 1011 { 1012 static void testLCB(string parseLCBFunc)(bool shouldConsume) 1013 { 1014 ubyte[] buf = [ 0xde, 0xcc, 0xbb, 0xaa, 0x99, 0x88, 0x77, 0x66, 0x55, 0x01, 0x00 ]; 1015 ubyte[] bufCopy; 1016 1017 bufCopy = buf; 1018 LCB lcb = mixin(parseLCBFunc~"!LCB(bufCopy)"); 1019 assert(lcb.value == 0xde && !lcb.isNull && lcb.totalBytes == 1); 1020 assert(bufCopy.length == buf.length - (shouldConsume? lcb.totalBytes : 0)); 1021 1022 buf[0] = 251; 1023 bufCopy = buf; 1024 lcb = mixin(parseLCBFunc~"!LCB(bufCopy)"); 1025 assert(lcb.value == 0 && lcb.isNull && lcb.totalBytes == 1); 1026 //TODO: This test seems to fail for consumeIfComplete, need to investigate. 1027 // Don't know if fixing it might cause a problem, or if I simple misunderstood 1028 // the function's intent. 1029 if(parseLCBFunc != "consumeIfComplete") 1030 assert(bufCopy.length == buf.length - (shouldConsume? lcb.totalBytes : 0)); 1031 1032 buf[0] = 252; 1033 bufCopy = buf; 1034 lcb = mixin(parseLCBFunc~"!LCB(bufCopy)"); 1035 assert(lcb.value == 0xbbcc && !lcb.isNull && lcb.totalBytes == 3); 1036 assert(bufCopy.length == buf.length - (shouldConsume? lcb.totalBytes : 0)); 1037 1038 buf[0] = 253; 1039 bufCopy = buf; 1040 lcb = mixin(parseLCBFunc~"!LCB(bufCopy)"); 1041 assert(lcb.value == 0xaabbcc && !lcb.isNull && lcb.totalBytes == 4); 1042 assert(bufCopy.length == buf.length - (shouldConsume? lcb.totalBytes : 0)); 1043 1044 buf[0] = 254; 1045 bufCopy = buf; 1046 lcb = mixin(parseLCBFunc~"!LCB(bufCopy)"); 1047 assert(lcb.value == 0x5566778899aabbcc && !lcb.isNull && lcb.totalBytes == 9); 1048 assert(bufCopy.length == buf.length - (shouldConsume? lcb.totalBytes : 0)); 1049 } 1050 1051 //TODO: Merge 'consumeIfComplete(T:LCB)' and 'decode(T:LCB)', they do 1052 // basically the same thing, only one consumes input and the other 1053 // doesn't. Just want a better idea of where/how/why they're both 1054 // used, and maybe more tests, before I go messing with them. 1055 testLCB!"consumeIfComplete"(true); 1056 testLCB!"decode"(false); 1057 } 1058 1059 debug(MYSQLN_TESTS) 1060 unittest 1061 { 1062 ubyte[] buf; 1063 ubyte[] bufCopy; 1064 1065 buf.length = 0x2000200; 1066 buf[] = '\x01'; 1067 buf[0] = 250; 1068 buf[1] = '<'; 1069 buf[249] = '!'; 1070 buf[250] = '>'; 1071 bufCopy = buf; 1072 string x = consume!LCS(bufCopy); 1073 assert(x.length == 250 && x[0] == '<' && x[249] == '>'); 1074 1075 buf[] = '\x01'; 1076 buf[0] = 252; 1077 buf[1] = 0xff; 1078 buf[2] = 0xff; 1079 buf[3] = '<'; 1080 buf[0x10000] = '*'; 1081 buf[0x10001] = '>'; 1082 bufCopy = buf; 1083 x = consume!LCS(bufCopy); 1084 assert(x.length == 0xffff && x[0] == '<' && x[0xfffe] == '>'); 1085 1086 buf[] = '\x01'; 1087 buf[0] = 253; 1088 buf[1] = 0xff; 1089 buf[2] = 0xff; 1090 buf[3] = 0xff; 1091 buf[4] = '<'; 1092 buf[0x1000001] = '*'; 1093 buf[0x1000002] = '>'; 1094 bufCopy = buf; 1095 x = consume!LCS(bufCopy); 1096 assert(x.length == 0xffffff && x[0] == '<' && x[0xfffffe] == '>'); 1097 1098 buf[] = '\x01'; 1099 buf[0] = 254; 1100 buf[1] = 0xff; 1101 buf[2] = 0x00; 1102 buf[3] = 0x00; 1103 buf[4] = 0x02; 1104 buf[5] = 0x00; 1105 buf[6] = 0x00; 1106 buf[7] = 0x00; 1107 buf[8] = 0x00; 1108 buf[9] = '<'; 1109 buf[0x2000106] = '!'; 1110 buf[0x2000107] = '>'; 1111 bufCopy = buf; 1112 x = consume!LCS(bufCopy); 1113 assert(x.length == 0x20000ff && x[0] == '<' && x[0x20000fe] == '>'); 1114 } 1115 1116 /// Set packet length and number. It's important that the length of packet has 1117 /// already been set to the final state as its length is used. 1118 void setPacketHeader(ref ubyte[] packet, ubyte packetNumber) pure nothrow 1119 in 1120 { 1121 // packet should include header, and possibly data 1122 assert(packet.length >= 4); 1123 } 1124 body 1125 { 1126 auto dataLength = packet.length - 4; // don't include header in calculated size 1127 assert(dataLength <= uint.max); 1128 packet.setPacketHeader(packetNumber, cast(uint)dataLength); 1129 } 1130 1131 void setPacketHeader(ref ubyte[] packet, ubyte packetNumber, uint dataLength) pure nothrow 1132 in 1133 { 1134 // packet should include header 1135 assert(packet.length >= 4); 1136 // Length is always a 24-bit int 1137 assert(dataLength <= 0xffff_ffff_ffff); 1138 } 1139 body 1140 { 1141 dataLength.packInto!(uint, true)(packet); 1142 packet[3] = packetNumber; 1143 }