1 /* 2 Copyright 2020, Dirk Krause. All rights reserved. 3 SPDX-License-Identifier: BSD-3-Clause 4 */ 5 6 #ifndef DK4SOCK_H_INCLUDED 7 /** Protection against multiple inclusions. */ 8 #define DK4SOCK_H_INCLUDED 1 9 10 /** @file dk4sock.h Socket functions. 11 12 The functions in this module are for both networking and local UNIX 13 domain sockets. 14 15 Use dk4socket_up() before using any other function shown here, use 16 dk4socket_down() to release the socket subsystem when you are done. 17 These functions simply indicate success on POSIX systems but 18 are required for subsystem initialization and release on Windows. 19 20 Exception: dk4socket_htons(), dk4socket_ntohs(), dk4socket_htonl() 21 and dk4socket_ntohl() and some other bit/byte handling functions 22 can be used without calling dk4socket_up() before. 23 24 Errors from the systems native socket functions are stored in errno 25 on POSIX systems. On Windows you can use WSAGetLastError() to find 26 an error code. 27 The dk4socket_error_reset(), dk4socket_error_get() and dk4socket_error_report() 28 functions are used to hide this difference. 29 30 31 */ 32 33 #ifndef DK4CONF_H_INCLUDED 34 #if DK4_BUILDING_DKTOOLS4 35 #include "dk4conf.h" 36 #else 37 #include <dktools-4/dk4conf.h> 38 #endif 39 #endif 40 41 42 43 #if DK4_ON_WINDOWS 44 45 #if DK4_HAVE_WINSOCK2_H 46 #ifndef WINSOCK2_H_INCLUDED 47 #include <winsock2.h> 48 #define WINSOCK2_H_INCLUDED 1 49 #endif 50 #endif 51 52 #if DK4_HAVE_WS2TCPIP_H 53 #ifndef WS2TCPIP_H_INCLUDED 54 #include <ws2tcpip.h> 55 #define WS2TCPIP_H_INCLUDED 56 #endif 57 #endif 58 59 #ifndef WINDOWS_H_INCLUDED 60 #include <windows.h> 61 #define WINDOWS_H_INCLUDED 1 62 #endif 63 64 #endif 65 /* if DK4_ON_WINDOWS*/ 66 67 #if DK4_HAVE_SYS_TYPES_H 68 #ifndef SYS_TYPES_H_INCLUDED 69 #include <sys/types.h> 70 #define SYS_TYPES_H_INCLUDED 1 71 #endif 72 #endif 73 74 #if DK4_HAVE_SYS_SOCKET_H 75 #ifndef SYS_SOCKET_H_INCLUDED 76 #include <sys/socket.h> 77 #define SYS_SOCKET_H_INCLUDED 1 78 #endif 79 #endif 80 81 #if DK4_HAVE_SYS_UN_H 82 #ifndef SYS_UN_H_INCLUDED 83 #include <sys/un.h> 84 #define SYS_UN_H_INCLUDED 1 85 #endif 86 #endif 87 88 #if DK4_HAVE_ARPA_INET_H 89 #ifndef ARPA_INET_H_INCLUDED 90 #include <arpa/inet.h> 91 #define ARPA_INET_H_INCLUDED 1 92 #endif 93 #endif 94 95 #if DK4_HAVE_NETINET_IN_H 96 #ifndef NETINET_IN_H_INCLUDED 97 #include <netinet/in.h> 98 #define NETINET_IN_H_INCLUDED 1 99 #endif 100 #endif 101 102 #if DK4_HAVE_NETINET_IN6_H 103 #ifndef NETINET_IN6_H_INCLUDED 104 #include <netinet/in6.h> 105 #define NETINET_IN6_H_INCLUDED 1 106 #endif 107 #endif 108 109 #if DK4_HAVE_NETDB_H 110 #ifndef NETDB_H_INCLUDED 111 #include <netdb.h> 112 #define NETDB_H_INCLUDED 1 113 #endif 114 #endif 115 116 #if DK4_ON_WINDOWS 117 /** Data type for sockets. */ 118 typedef SOCKET dk4_socket_t; 119 #else 120 /** Data type for sockets. */ 121 typedef int dk4_socket_t; 122 #endif 123 124 #ifndef DK4TYPES_H_INCLUDED 125 #if DK4_BUILDING_DKTOOLS4 126 #include <libdk4base/dk4types.h> 127 #else 128 #include <dktools-4/dk4types.h> 129 #endif 130 #endif 131 132 #ifndef DK4ERROR_H_INCLUDED 133 #if DK4_BUILDING_DKTOOLS4 134 #include <libdk4base/dk4error.h> 135 #else 136 #include <dktools-4/dk4error.h> 137 #endif 138 #endif 139 140 141 142 /** Set of sockets, for listening or for receiving datagrams. 143 */ 144 typedef struct { 145 dk4_socket_t *pSockets; /**< Array of sockets. */ 146 size_t szMax; /**< Array size allocated, no of sockets. */ 147 size_t szUsed; /**< Number of used sockets in array. */ 148 } dk4_socket_set_t; 149 150 151 #if !DK4_HAVE_IN_ADDR 152 /** IPv4 internet address. 153 */ 154 typedef struct in_addr IN_ADDR; 155 #endif 156 157 158 #if DK4_HAVE_STRUCT_SOCKADDR_IN6 159 #if !DK4_HAVE_IN6_ADDR 160 /** IPv6 internet address. 161 */ 162 typedef struct in6_addr IN6_ADDR; 163 #endif 164 #endif 165 166 167 /** Allowed IPv4 peer address or address range. 168 */ 169 typedef struct { 170 IN_ADDR ad; /**< Address or address base. */ 171 IN_ADDR ma; /**< Net mask. */ 172 } dk4_allowed_peer_ipv4_t; 173 174 175 176 #if DK4_HAVE_STRUCT_SOCKADDR_IN6 177 /** Allowed IPv6 peer address or address range. 178 */ 179 typedef struct { 180 IN6_ADDR ad; /**< Address or address base. */ 181 IN6_ADDR ma; /**< Net mask. */ 182 } dk4_allowed_peer_ipv6_t; 183 #endif 184 185 186 187 /** Allowed IPv6 or IPv4 peer address or range. 188 */ 189 typedef struct { 190 int af; /**< Addr family AF_INET or AF_INET6. */ 191 union { 192 dk4_allowed_peer_ipv4_t ipv4; /**< IPv4 peer data. */ 193 #if DK4_HAVE_STRUCT_SOCKADDR_IN6 194 dk4_allowed_peer_ipv6_t ipv6; /**< IPv6 peer data. */ 195 #endif 196 } data; /**< Peer data. */ 197 } dk4_allowed_peer_t; 198 199 200 201 #if DK4_HAVE_SOCKADDR_STORAGE 202 /** Buffer large enough to hold all sockaddr_xxx structures. 203 */ 204 typedef struct sockaddr_storage dk4_sockaddr_storage_t; 205 #else 206 /** Buffer large enough to hold all sockaddr_xxx structures. 207 */ 208 typedef union { 209 struct sockaddr sa; /**< Default sockaddr. */ 210 struct sockaddr_in i4; /**< IPv4 address. */ 211 #if DK4_HAVE_STRUCT_SOCKADDR_IN6 212 struct sockaddr_in6 i6; /**< IPv6 address. */ 213 #endif 214 #if DK4_HAVE_STRUCT_SOCKADDR_UN 215 struct sockaddr_un su; /**< UNIX domain socket address. */ 216 #endif 217 } dk4_sockaddr_storage_t; 218 #endif 219 220 /** Operation result values. 221 */ 222 enum { 223 /** The operation failed. 224 */ 225 DK4_SOCKET_RESULT_FAILED = -1, 226 227 /** The operation is still in progress, 228 not yet finished. 229 */ 230 DK4_SOCKET_RESULT_IN_PROGRESS = 0, 231 232 /** The operation succeeded. 233 */ 234 DK4_SOCKET_RESULT_SUCCESS = 1 235 }; 236 237 238 #if DK4_ON_WINDOWS 239 /** How to shut down a socket. 240 */ 241 enum { 242 /** Shut down read (receive) operations. 243 */ 244 DK4_SOCKET_SHUT_READ = SD_RECEIVE , 245 246 /** Shut down write (send) operations. 247 */ 248 DK4_SOCKET_SHUT_WRITE = SD_SEND , 249 250 /** Shut down both. 251 */ 252 DK4_SOCKET_SHUT_RDWR = SD_BOTH 253 }; 254 #else 255 /** How to shut down a socket. 256 */ 257 enum { 258 /** Shut down read (receive) operations. 259 */ 260 DK4_SOCKET_SHUT_READ = SHUT_RD , 261 262 /** Shut down write (send) operations. 263 */ 264 DK4_SOCKET_SHUT_WRITE = SHUT_WR , 265 266 /** Shut down both. 267 */ 268 DK4_SOCKET_SHUT_RDWR = SHUT_RDWR 269 }; 270 #endif 271 272 273 #ifndef INVALID_SOCKET 274 /** Special socket values. 275 */ 276 enum { 277 /** Invalid socket. 278 */ 279 INVALID_SOCKET = -1 280 }; 281 #endif 282 283 #ifdef __cplusplus 284 extern "C" { 285 #endif 286 287 /* 288 Error reporting. 289 ---------------- 290 Module: dk4sock01 291 */ 292 293 /** Reset error code variable (either errno or WSAGetLastError()). 294 */ 295 void 296 dk4socket_error_reset(void); 297 298 /** Get error code (either from errno or via WSAGetLastError()). 299 @return Error code. 300 */ 301 int 302 dk4socket_error_get(void); 303 304 /** Note error in error report, use error details from either 305 errno or WSAGetLastError(). 306 @param erp Error report to fill. 307 @param ec Error code DK4_E_xxx. 308 */ 309 void 310 dk4socket_error_report(dk4_er_t *erp, int ec); 311 312 /** Write IP address to debug output file. 313 For internal use only. 314 @param text Text to show before address. 315 @param addr Start of address buffer. 316 @param sz Size of address. 317 */ 318 void 319 dk4socket_debug_address(const char *text, struct sockaddr *addr, size_t sz); 320 321 322 #if (DK4_HAVE_SETSOCKOPT) && defined(SOL_SOCKET) && defined(SO_ERROR) 323 324 /** Check integer result from getsockopt() for non-null value. 325 On some systems the getsockopt() function writes an int value for 326 boolean flags, a simple byte is used on other systems. 327 After calling getsockopt() you can use this function to check 328 boolean values for true or false. 329 @param optval The value stored in an int variable by getsockopt(). 330 @param slo The length stored in the size variable. 331 @return 1 for non-null value, 0 for 0 value. 332 */ 333 int 334 dk4socket_non_null_getsockopt(int optval, socklen_t slo); 335 336 #endif 337 338 /* 339 Long and short conversion between network and host representation. 340 ------------------------------------------------------------------ 341 Module: dk4sock02 342 */ 343 344 /** Convert short from host to network representation. 345 Does not require dk4socket_up() to be called before. 346 @param u Value to convert. 347 @return Conversion result. 348 */ 349 uint16_t 350 dk4socket_htons(uint16_t u); 351 352 /** Convert short from network to host representation. 353 Does not require dk4socket_up() to be called before. 354 @param u Value to convert. 355 @return Conversion result. 356 */ 357 uint16_t 358 dk4socket_ntohs(uint16_t u); 359 360 /** Convert long from host to network representation. 361 Does not require dk4socket_up() to be called before. 362 @param u Value to convert. 363 @return Conversion result. 364 */ 365 uint32_t 366 dk4socket_htonl(uint32_t u); 367 368 /** Convert long from network to host representation. 369 Does not require dk4socket_up() to be called before. 370 @param u Value to convert. 371 @return Conversion result. 372 */ 373 uint32_t 374 dk4socket_ntohl(uint32_t u); 375 376 /** Change byte order for arbitrary data types, if the 377 Does not require dk4socket_up() to be called before. 378 systems byte order is not big-endian. 379 Does not require dk4socket_up() to be called before. 380 @param buf Address of variable. 381 @param sz Size of variable. 382 */ 383 void 384 dk4socket_swap_bytes_if_not_bigendian(void *buf, size_t sz); 385 386 /** Create a netmask in host representation for a given bit number. 387 Does not require dk4socket_up() to be called before. 388 @param dptr Address of destination variable. 389 @param sz Number of bits to set. 390 @param erp Error report, may be NULL. 391 @return DK4_SOCKET_RESULT_SUCCESS on success, 392 DK4_SOCKET_RESULT_FAILED on error. 393 394 Error codes: 395 - DK4_E_INVALID_ARGUMENTS<br> 396 if inp is NULL, 397 - DK4_E_SYNTAX<br> 398 if the number of bits is out of range. 399 */ 400 int 401 dk4socket_mask_bits(unsigned long *dptr, size_t sz, dk4_er_t *erp); 402 403 /** Set all bytes to 0x01. 404 Does not require dk4socket_up() to be called before. 405 @param ptr Pointer to variable. 406 @param nbytes Number of bytes in variable. 407 */ 408 void 409 dk4socket_set_one_bytes(void *ptr, size_t nbytes); 410 411 412 413 #if DK4_HAVE_STRUCT_SOCKADDR_IN6 414 415 /** Create IPv6 netmask in network representation. 416 @param inp Address of destination variable. 417 @param sz Number of bits to set (1 to 128). 418 @param erp Error report, may be NULL. 419 @return DK4_SOCKET_RESULT_SUCCESS on success, 420 DK4_SOCKET_RESULT_FAILED on error. 421 422 Error codes: 423 - DK4_E_INVALID_ARGUMENTS<br> 424 if inp is NULL, 425 - DK4_E_SYNTAX<br> 426 if the number of bits is out of range. 427 */ 428 int 429 dk4socket_mask6_bits(struct in6_addr *inp, size_t sz, dk4_er_t *erp); 430 431 #endif 432 433 434 435 #if DK4_HAVE_STRUCT_SOCKADDR_UN 436 437 /** Find socket address length for local UNIX domain socket. 438 For UNIX sockets the address size is not the size of 439 struct sockaddr_un, only the used part of the file name 440 buffer is counted. 441 @param sock Pointer to socket address structure. 442 @return Number of bytes used by address. 443 */ 444 size_t 445 dk4socket_unix_length(const struct sockaddr_un *sock); 446 447 #endif 448 449 /** Get protocol family for address family. 450 @param af Address family. 451 @return Protocol family on success, PF_UNSPEC on error. 452 */ 453 int 454 dk4socket_pf_for_af(int af); 455 456 /** Check address length, correct if necessary. 457 This function allows to pass a dk4_sockaddr_storage_t 458 address and sizeof(dk4_sockaddr_storage_t), the 459 dk4socket_bind(), dk4socket_connect() and dk4socket_sendto() 460 use the correct size for the address family stored. 461 @param soa Socket address. 462 @param plgt Address of length variable. 463 @return 1 on success, 0 on error. 464 */ 465 int 466 dk4socket_correct_addr_lgt(const struct sockaddr *soa, size_t *plgt); 467 468 /* 469 Convert addresses to text and vice versa. 470 ----------------------------------------- 471 Module: dk4sock03 472 */ 473 474 /** Convert address to text representation (char). 475 @param dptr Destination buffer address. 476 @param dsz Destination buffer size. 477 @param afam Address family (AF_INET or AF_INET6). 478 @param src Pointer to struct in_addr or struct in6_addr. 479 @param erp Error report, may be NULL. 480 @return DK4_SOCKET_RESULT_SUCCESS on success, 481 DK4_SOCKET_RESULT_FAILED on error. 482 483 Restriction: If the inet_ntop() function is not available 484 (i.e. on Windows with DK4_WINDOWS_LEGACY enabled) IPv6 adddresses 485 containing zero sequences are not abbreviated using ``::''. 486 487 Error codes: 488 - DK4_E_INVALID_ARGUMENTS<br> 489 if dptr or src is NULL, dsz is 0 or afam is an invalid family, 490 - DK4_E_BUFFER_TOO_SMALL<br> 491 if the output buffer is too small, 492 - DK4_E_MATH_OVERFLOW<br> 493 if a mathematical overflow occured in size calculations, 494 - DK4_E_SOCKET_INET_NTOP<br> 495 if the inet_ntop() function failed (details in iDetails1). 496 */ 497 int 498 dk4socket_c8_inet_ntop( 499 char *dptr, 500 size_t dsz, 501 int afam, 502 const void *src, 503 dk4_er_t *erp 504 ); 505 506 /** Convert IP address including port number to char text. 507 @param dptr Destination buffer address. 508 @param dsz Destination buffer size. 509 @param afam Address family. 510 @param saptr Address buffer. 511 @param sasz Address size. 512 @param erp Error report, may be NULL. 513 @return DK4_SOCKET_RESULT_SUCCESS on success, 514 DK4_SOCKET_RESULT_FAILED on error. 515 516 Restriction: If neither the getnameinfo() nor the inet_ntop() 517 function is available (i.e. on Windows with DK4_WINDOWS_LEGACY 518 enabled) IPv6 adddresses containing zero sequences are 519 not abbreviated using ``::''. 520 521 Error codes: 522 - DK4_E_INVALID_ARGUMENTS 523 - DK4_SOCKET_GETADDRINFO 524 - DK4_E_BUFFER_TOO_SMALL 525 */ 526 int 527 dk4socket_c8_addr_port_to_text( 528 char *dptr, 529 size_t dsz, 530 int afam, 531 const struct sockaddr *saptr, 532 size_t sasz, 533 dk4_er_t *erp 534 ); 535 536 /** Convert generic socket address structure to char text. 537 @param dptr Destination buffer address. 538 @param dsz Destination buffer size. 539 @param saptr Pointer to socket address structure. 540 @param erp Error report, may be NULL. 541 @return DK4_SOCKET_RESULT_SUCCESS on success, 542 DK4_SOCKET_RESULT_FAILED on error. 543 544 Restriction: If neither the getnameinfo() nor the inet_ntop() 545 function is available (i.e. on Windows with DK4_WINDOWS_LEGACY 546 enabled) IPv6 adddresses containing zero sequences are 547 not abbreviated using ``::''. 548 549 Error codes: 550 - DK4_E_INVALID_ARGUMENTS 551 - DK4_E_SOCKET_GETADDRINFO 552 - DK4_E_SYNTAX 553 - DK4_E_BUFFER_TOO_SMALL 554 */ 555 int 556 dk4socket_c8_sockaddr_to_text( 557 char *dptr, 558 size_t dsz, 559 const dk4_sockaddr_storage_t *saptr, 560 dk4_er_t *erp 561 ); 562 563 /* 564 Convert addresses to text and vice versa. 565 ----------------------------------------- 566 Module: dk4sock04 567 */ 568 569 /** Convert address to text representation (wchar_t). 570 @param dptr Destination buffer address. 571 @param dsz Destination buffer size (number of wchar_t). 572 @param afam Address family (AF_INET or AF_INET6). 573 @param src Pointer to struct in_addr or struct in6_addr. 574 @param erp Error report, may be NULL. 575 @return DK4_SOCKET_RESULT_SUCCESS on success, 576 DK4_SOCKET_RESULT_FAILED on error. 577 578 Restriction: If the inet_ntop() function is not available 579 (i.e. on Windows with DK4_WINDOWS_LEGACY enabled) IPv6 adddresses 580 containing zero sequences are not abbreviated using ``::''. 581 582 Error codes: 583 - DK4_E_INVALID_ARGUMENTS<br> 584 if dptr or src is NULL, dsz is 0 or afam is an invalid family, 585 - DK4_E_BUFFER_TOO_SMALL<br> 586 if the output buffer is too small, 587 - DK4_E_MATH_OVERFLOW<br> 588 if a mathematical overflow occured in size calculations, 589 - DK4_E_SOCKET_INET_NTOP<br> 590 if the inet_ntop() function failed (details in iDetails1), 591 - DK4_E_NOT_SUPPORTED<br> 592 if there is not wchar_t support. 593 */ 594 int 595 dk4socket_wc_inet_ntop( 596 wchar_t *dptr, 597 size_t dsz, 598 int afam, 599 const void *src, 600 dk4_er_t *erp 601 ); 602 603 /** Convert IP address including port number to wchar_t text. 604 @param dptr Destination buffer address. 605 @param dsz Destination buffer size (number of wchar_t). 606 @param afam Address family. 607 @param saptr Address buffer. 608 @param sasz Address size. 609 @param erp Error report, may be NULL. 610 @return DK4_SOCKET_RESULT_SUCCESS on success, 611 DK4_SOCKET_RESULT_FAILED on error. 612 613 Restriction: If neither the getnameinfo() nor the inet_ntop() 614 function is available (i.e. on Windows with DK4_WINDOWS_LEGACY 615 enabled) IPv6 adddresses containing zero sequences are 616 not abbreviated using ``::''. 617 618 Error codes: 619 - DK4_E_INVALID_ARGUMENTS 620 - DK4_SOCKET_GETADDRINFO 621 - DK4_E_BUFFER_TOO_SMALL 622 - DK4_E_NOT_SUPPORTED 623 */ 624 int 625 dk4socket_wc_addr_port_to_text( 626 wchar_t *dptr, 627 size_t dsz, 628 int afam, 629 const struct sockaddr *saptr, 630 size_t sasz, 631 dk4_er_t *erp 632 ); 633 634 /** Convert generic socket address structure to wchar_t text. 635 @param dptr Destination buffer address. 636 @param dsz Destination buffer size (Number of wchar_t). 637 @param saptr Pointer to socket address structure. 638 @param erp Error report, may be NULL. 639 @return DK4_SOCKET_RESULT_SUCCESS on success, 640 DK4_SOCKET_RESULT_FAILED on error. 641 642 Restriction: If neither the getnameinfo() nor the inet_ntop() 643 function is available (i.e. on Windows with DK4_WINDOWS_LEGACY 644 enabled) IPv6 adddresses containing zero sequences are 645 not abbreviated using ``::''. 646 647 Error codes: 648 - DK4_E_INVALID_ARGUMENTS 649 - DK4_E_SOCKET_GETADDRINFO 650 - DK4_E_SYNTAX 651 - DK4_E_BUFFER_TOO_SMALL 652 */ 653 int 654 dk4socket_wc_sockaddr_to_text( 655 wchar_t *dptr, 656 size_t dsz, 657 const dk4_sockaddr_storage_t *saptr, 658 dk4_er_t *erp 659 ); 660 661 /* 662 Convert addresses to text and vice versa. 663 ----------------------------------------- 664 Module: dk4sock05 665 */ 666 667 /** Convert address to text representation (dkChar). 668 @param dptr Destination buffer address. 669 @param dsz Destination buffer size (number of dkChar). 670 @param afam Address family (AF_INET or AF_INET6). 671 @param src Pointer to struct in_addr or struct in6_addr. 672 @param erp Error report, may be NULL. 673 @return DK4_SOCKET_RESULT_SUCCESS on success, 674 DK4_SOCKET_RESULT_FAILED on error. 675 676 Restriction: If the inet_ntop() function is not available 677 (i.e. on Windows with DK4_WINDOWS_LEGACY enabled) IPv6 adddresses 678 containing zero sequences are not abbreviated using ``::''. 679 680 Error codes: 681 - DK4_E_INVALID_ARGUMENTS<br> 682 if dptr or src is NULL, dsz is 0 or afam is an invalid family, 683 - DK4_E_BUFFER_TOO_SMALL<br> 684 if the output buffer is too small, 685 - DK4_E_MATH_OVERFLOW<br> 686 if a mathematical overflow occured in size calculations, 687 - DK4_E_SOCKET_INET_NTOP<br> 688 if the inet_ntop() function failed (details in iDetails1). 689 */ 690 int 691 dk4socket_inet_ntop( 692 dkChar *dptr, 693 size_t dsz, 694 int afam, 695 const void *src, 696 dk4_er_t *erp 697 ); 698 699 /** Convert IP address including port number to dkChar text. 700 @param dptr Destination buffer address. 701 @param dsz Destination buffer size (number of dkChar). 702 @param afam Address family. 703 @param saptr Address buffer. 704 @param sasz Address size. 705 @param erp Error report, may be NULL. 706 @return DK4_SOCKET_RESULT_SUCCESS on success, 707 DK4_SOCKET_RESULT_FAILED on error. 708 709 Restriction: If neither the getnameinfo() nor the inet_ntop() 710 function is available (i.e. on Windows with DK4_WINDOWS_LEGACY 711 enabled) IPv6 adddresses containing zero sequences are 712 not abbreviated using ``::''. 713 */ 714 int 715 dk4socket_addr_port_to_text( 716 dkChar *dptr, 717 size_t dsz, 718 int afam, 719 const struct sockaddr *saptr, 720 size_t sasz, 721 dk4_er_t *erp 722 ); 723 724 /** Convert generic socket address structure to dkChar text. 725 @param dptr Destination buffer address. 726 @param dsz Destination buffer size (Number of dkChar). 727 @param saptr Pointer to socket address structure. 728 @param erp Error report, may be NULL. 729 @return DK4_SOCKET_RESULT_SUCCESS on success, 730 DK4_SOCKET_RESULT_FAILED on error. 731 732 Restriction: If neither the getnameinfo() nor the inet_ntop() 733 function is available (i.e. on Windows with DK4_WINDOWS_LEGACY 734 enabled) IPv6 adddresses containing zero sequences are 735 not abbreviated using ``::''. 736 737 Error codes: 738 - DK4_E_INVALID_ARGUMENTS 739 - DK4_E_SOCKET_GETADDRINFO 740 - DK4_E_SYNTAX 741 - DK4_E_BUFFER_TOO_SMALL 742 */ 743 int 744 dk4socket_sockaddr_to_text( 745 dkChar *dptr, 746 size_t dsz, 747 const dk4_sockaddr_storage_t *saptr, 748 dk4_er_t *erp 749 ); 750 751 /* 752 Convert text to IP address (char). 753 ---------------------------------- 754 Module: dk4sock06 755 */ 756 757 /** Convert text IP address to struct in_addr or struct in6_addr. 758 @param pAddr Pointer to destination buffer. 759 @param szAddr Destination buffer size. 760 @param afam Address family (AF_INET or AF_INET6). 761 @param src Source text. 762 @param erp Error report, may be NULL. 763 @return DK4_SOCKET_RESULT_SUCCESS on success, 764 DK4_SOCKET_RESULT_FAILED on error 765 766 Error codes: 767 - DK4_E_INVALID_ARGUMENTS<br> 768 if pAddr or src is NULL or szAddr is 0, or szAddr does not have 769 the correct size for the specified family, 770 - DK4_E_SYNTAX<br> 771 if src does not contain a valid IPv4 or IPv6 address, 772 - DK4_E_SOCKET_INET_PTON<br> 773 if the inet_pton() function failed for some reason. 774 */ 775 int 776 dk4socket_c8_inet_pton( 777 void *pAddr, 778 size_t szAddr, 779 int afam, 780 const char *src, 781 dk4_er_t *erp 782 ); 783 784 /* 785 Convert text to IP address (wchar_t). 786 ------------------------------------- 787 Module: dk4sock07 788 */ 789 790 /** Convert text IP address to struct in_addr or struct in6_addr. 791 @param pAddr Pointer to destination buffer. 792 @param szAddr Destination buffer size. 793 @param afam Address family (AF_INET or AF_INET6). 794 @param src Source text. 795 @param erp Error report, may be NULL. 796 @return DK4_SOCKET_RESULT_SUCCESS on success, 797 DK4_SOCKET_RESULT_FAILED on error 798 799 Error codes: 800 - DK4_E_INVALID_ARGUMENTS<br> 801 if pAddr or src is NULL or szAddr is 0, 802 - DK4_E_BUFFER_TOO_SMALL<br> 803 if src is too long for conversion into an internal buffer, 804 - DK4_E_SYNTAX<br> 805 if src contains non-ASCII characters or is not a valid 806 IPv6 or IPv6 address, 807 - DK4_E_SOCKET_INET_PTON<br> 808 if InetPtonW() fails for some reason. 809 */ 810 int 811 dk4socket_wc_inet_pton( 812 void *pAddr, 813 size_t szAddr, 814 int afam, 815 const wchar_t *src, 816 dk4_er_t *erp 817 ); 818 819 /* 820 Convert text to IP address (dkChar). 821 ------------------------------------ 822 Module: dk4sock08 823 */ 824 825 /** Convert text IP address to struct in_addr or struct in6_addr. 826 @param pAddr Pointer to destination buffer. 827 @param szAddr Destination buffer size. 828 @param afam Address family (AF_INET or AF_INET6). 829 @param src Source text. 830 @param erp Error report, may be NULL. 831 @return DK4_SOCKET_RESULT_SUCCESS on success, 832 DK4_SOCKET_RESULT_FAILED on error. 833 834 Error codes: 835 - DK4_E_INVALID_ARGUMENTS<br> 836 if pAddr or src is NULL or szAddr is 0, 837 - DK4_E_BUFFER_TOO_SMALL<br> 838 if src is too long for conversion into an internal buffer, 839 - DK4_E_SYNTAX<br> 840 if src contains non-ASCII characters or is not a valid 841 IPv6 or IPv6 address, 842 - DK4_E_SOCKET_INET_PTON<br> 843 if inet_pton() or InetPtonW() fails for some reason. 844 */ 845 int 846 dk4socket_inet_pton( 847 void *pAddr, 848 size_t szAddr, 849 int afam, 850 const dkChar *src, 851 dk4_er_t *erp 852 ); 853 854 /* 855 Bring socket subsystem up and down. 856 ----------------------------------- 857 Module: dk4sock09 858 */ 859 /** Bring socket subsystem up. 860 This function calls WSAStartup() on Windows, simply indicates 861 success on all other systems. 862 @param er Error report, may be NULL. 863 @return DK4_SOCKET_RESULT_SUCCESS on success, 864 DK4_SOCKET_RESULT_FAILED on error. 865 866 Error codes: 867 * DK4_E_SOCKET_UP<br> 868 with WSAGetLastError() result in iDetails1 if a WinSock 869 error occured. 870 */ 871 int 872 dk4socket_up(dk4_er_t *er); 873 874 /** Bring socket subsystem down. 875 This function calls WSACleanup() on Windows, simply indicates 876 success on all other systems. 877 @param er Error report, may be NULL. 878 @return DK4_SOCKET_RESULT_SUCCESS on success, 879 DK4_SOCKET_RESULT_FAILED on error. 880 881 Error codes: 882 * DK4_E_SOCKET_DOWN<br> 883 with WSAGetLastError() result in iDetails1 if a WinSock 884 error occured. 885 */ 886 int 887 dk4socket_down(dk4_er_t *er); 888 889 /* 890 Basic socket operations (open and close). 891 ----------------------------------------- 892 Module: dk4sock10 893 */ 894 895 /** Open a socket. 896 @param af Address family (AF_INET or AF_INET6). 897 @param tp Socket type (SOCK_STREAM or SOCK_DGRAM). 898 @param pr Protocol (0). 899 @param erp Error report, may be NULL. 900 @return New socket on success, INVALID_SOCKET on error. 901 902 Error codes: 903 - DK4_E_INVALID_ARGUMENTS<br> 904 if af is not one from AF_INET, AF_INET6, AF_UNIX, or AF_LOCAL 905 or tp is not one from SOCK_STREAM or SOCK_DGRAM or pr is 906 not 0, 907 - DK4_E_SOCKET_SOCKET<br> 908 with errno/WSAGetLastError() value in iDetails1 if 909 the socket() function failed. 910 */ 911 dk4_socket_t 912 dk4socket_open(int af, int tp, int pr, dk4_er_t *erp); 913 914 /** Shut down socket. 915 @param so Socket to shut down. 916 @param how Choose tasks to end, one from: 917 DK4_SOCKET_SHUT_READ to stop reading (receiving), 918 DK4_SOCKET_SHUT_WRITE to stop writing (sending), or 919 DK4_SOCKET_SHUT_RDWR to stop both. 920 @param erp Error report, may be NULL. 921 @return DK4_SOCKET_RESULT_SUCCESS on success, 922 DK4_SOCKET_RESULT_FAILED on error. 923 */ 924 int 925 dk4socket_shutdown(dk4_socket_t so, int how, dk4_er_t *erp); 926 927 /** Close a socket. 928 @param so Socket to close. 929 @param erp Error report, may be NULL. 930 @return DK4_SOCKET_RESULT_SUCCESS on success, 931 DK4_SOCKET_RESULT_FAILED on error. 932 933 Error codes: 934 - DK4_E_INVALID_ARGUMENTS<br> 935 if af is not one from AF_INET, AF_INET6, AF_UNIX, or AF_LOCAL 936 or tp is not one from SOCK_STREAM or SOCK_DGRAM or pr is 937 not 0, 938 - DK4_E_SOCKET_CLOSE<br> 939 with errno/WSAGetLastError() value in iDetails1 if 940 the close()/closesocket() function failed. 941 */ 942 int 943 dk4socket_close(dk4_socket_t so, dk4_er_t *erp); 944 945 /* 946 Address binding. 947 ---------------- 948 Module: dk4sock11 949 */ 950 951 /** Bind a local address. 952 @param sock Socket to configure. 953 @param pAddr Pointer to socket address buffer. 954 @param szAddr Size of socket address buffer. 955 @param erp Error report, may be NULL. 956 @return DK4_SOCKET_RESULT_SUCCESS on success, 957 DK4_SOCKET_RESULT_FAILED on error. 958 959 Error codes: 960 - DK4_E_INVALID_ARGUMENTS<br> 961 if the address pointer is NULL or the address size is 0, 962 - DK4_E_SOCKET_BIND<br> 963 with errno/WSAGetLastError() value in iDetails1 if the 964 bind() function failed. 965 */ 966 int 967 dk4socket_bind( 968 dk4_socket_t sock, 969 const struct sockaddr *pAddr, 970 size_t szAddr, 971 dk4_er_t *erp 972 ); 973 974 /* 975 Client side: connecting to remote server. 976 ----------------------------------------- 977 Module: dk4sock12 978 */ 979 980 /** Connect to remote server. 981 @param sock Socket to configure. 982 @param pAddr Pointer to remote socket address buffer. 983 @param szAddr Size of remote socket address buffer. 984 @param erp Error report, may be NULL. 985 @return DK4_SOCKET_RESULT_SUCCESS on success, 986 DK4_SOCKET_RESULT_IN_PROGRESS if the operation is still in progress, 987 DK4_SOCKET_RESULT_FAILED on error. 988 989 Error codes: 990 - DK4_E_INVALID_ARGUMENTS<br> 991 if remote address pointer is NULL or remote address size is 0, 992 - DK4_E_SOCKET_CONNECT<br> 993 with errno/WSAGetLastError() value in iDetails1 if the 994 connect() function failed. 995 */ 996 int 997 dk4socket_connect( 998 dk4_socket_t sock, 999 const struct sockaddr *pAddr, 1000 size_t szAddr, 1001 dk4_er_t *erp 1002 ); 1003 1004 #if DK4_HAVE_STRUCT_SOCKADDR_UN 1005 1006 /** Create a UNIX domain socket in client mode. 1007 @param filename File name, max 107 characters long. 1008 @param erp Error report, may be NULL. 1009 @return Valid socket on success, INVALID_SOCKET on error. 1010 */ 1011 dk4_socket_t 1012 dk4socket_c8_unix_client( 1013 const char *filename, 1014 dk4_er_t *erp 1015 ); 1016 1017 #endif 1018 1019 /* 1020 Server side: listen and accept. 1021 ------------------------------- 1022 Module: dk4sock13 1023 */ 1024 1025 /** Listen on a socket. 1026 @param sock Socket to configure for listening. 1027 @param bl Backlog (Number of connections requests to queue). 1028 @param erp Error report, may be NULL. 1029 @return DK4_SOCKET_RESULT_SUCCESS on success, 1030 DK4_SOCKET_RESULT_FAILED on error. 1031 1032 Error codes: 1033 - DK4_E_INVALID_ARGUMENTS<br> 1034 if any argument is bad, 1035 - DK4_E_SOCKET_LISTEN<br> 1036 with errno/WSAGetLastError() value in iDetails1 if the 1037 listen() function failed. 1038 */ 1039 int 1040 dk4socket_listen( 1041 dk4_socket_t sock, 1042 int bl, 1043 dk4_er_t *erp 1044 ); 1045 1046 /** Accept incoming connection requests on listener socket. 1047 @param sock Listener socket. 1048 @param pAddr Pointer to address buffer, address of a 1049 dk4_sockaddr_storage_t recommended, NULL allowed. 1050 @param pSzAddr Pointer to address buffer size variable, 1051 in: buffer size, 1052 out: used size, should be NULL if pAddr is NULL. 1053 @param erp Error report, may be NULL. 1054 @return Socket for new connection on success, INVALID_SOCKET 1055 on error. 1056 1057 Error codes: 1058 - DK4_E_INVALID_ARGUMENTS<br> 1059 if any argument is bad, 1060 - DK4_E_SOCKET_ACCEPT<br> 1061 with errno/WSAGetLastError() value in iDetails1 if the 1062 accept() function failed. 1063 */ 1064 dk4_socket_t 1065 dk4socket_accept( 1066 dk4_socket_t sock, 1067 struct sockaddr *pAddr, 1068 size_t *pSzAddr, 1069 dk4_er_t *erp 1070 ); 1071 1072 #if DK4_HAVE_STRUCT_SOCKADDR_UN 1073 1074 /** Create a UNIX domain socket in listening state. 1075 @param filename File name, max 107 characters long. 1076 @param backlog Number of connection requests to queue. 1077 @param erp Error report, may be NULL. 1078 @return Valid socket on success, INVALID_SOCKET on error. 1079 1080 Error codes: 1081 - DK4_E_INVALID_ARGUMENTS<br> 1082 if filename is NULL or backlog is 0, 1083 - DK4_E_SYNTAX<br> 1084 if the file name is too long, 1085 - DK4_E_NON_SOCKET<br> 1086 if the file exists but is not a socket, 1087 - DK4_E_UNLINK_FAILED<br> 1088 if deletion of an already existing socket failed, 1089 - DK4_E_SOCKET_SOCKET<br> 1090 with errno value in iDetails1 if 1091 the socket() function failed, 1092 - DK4_E_SOCKET_BIND<br> 1093 with errno value in iDetails1 if the 1094 bind() function failed, 1095 - DK4_E_SOCKET_LISTEN<br> 1096 with errno value in iDetails1 if the 1097 listen() function failed, 1098 - DK4_E_CHMOD_FAILED<br> 1099 with errno value in iDetails1 if the chmod() function failed. 1100 */ 1101 dk4_socket_t 1102 dk4socket_c8_unix_listener( 1103 const char *filename, 1104 int backlog, 1105 dk4_er_t *erp 1106 ); 1107 1108 /** Create a UNIX domain socket in listening state, 1109 change ownership and permission. 1110 This function is intended for use in daemons which will give 1111 up root privileges before doing any service. 1112 @param filename File name, max 107 characters long. 1113 @param backlog Number of connection requests to queue. 1114 @param owner Owner UID. 1115 @param group Owner GID. 1116 @param mode File permissions in octal notation. 1117 @param erp Error report, may be NULL. 1118 @return Valid socket on success, INVALID_SOCKET on error. 1119 1120 Error codes: 1121 - DK4_E_INVALID_ARGUMENTS<br> 1122 if filename is NULL or backlog is 0, 1123 - DK4_E_SYNTAX<br> 1124 if the file name is too long, 1125 - DK4_E_NON_SOCKET<br> 1126 if the file exists but is not a socket, 1127 - DK4_E_UNLINK_FAILED<br> 1128 if deletion of an already existing socket failed, 1129 - DK4_E_SOCKET_SOCKET<br> 1130 with errno value in iDetails1 if 1131 the socket() function failed, 1132 - DK4_E_SOCKET_BIND<br> 1133 with errno value in iDetails1 if the 1134 bind() function failed, 1135 - DK4_E_SOCKET_LISTEN<br> 1136 with errno value in iDetails1 if the 1137 listen() function failed, 1138 - DK4_E_CHOWN_FAILED<br> 1139 with errno value in iDetails1 if the chown() function failed, 1140 - DK4_E_CHMOD_FAILED<br> 1141 with errno value in iDetails1 if the chmod() function failed. 1142 */ 1143 dk4_socket_t 1144 dk4socket_c8_unix_listener_owner_group_mode( 1145 const char *filename, 1146 int backlog, 1147 uid_t owner, 1148 gid_t group, 1149 mode_t mode, 1150 dk4_er_t *erp 1151 ); 1152 1153 #endif 1154 1155 /* 1156 Set socket options. 1157 ------------------- 1158 Module: dk4sock14 1159 */ 1160 1161 /** Set reuse flag for socket. 1162 Typically you should call this function immediately after 1163 creating the socket before binding any local address. 1164 @param sock 1165 @param val 1166 @param erp 1167 @return DK4_SOCKET_RESULT_SUCCESS on success, 1168 DK4_SOCKET_RESULT_FAILED on error. 1169 1170 Error codes: 1171 - DK4_E_NOT_SUPPORTED<br> 1172 if the setsockopt() function is not available, 1173 - DK4_E_INVALID_ARGUMENTS<br> 1174 if the socket is invalid, 1175 - DK4_E_SOCKET_SETSOCKOPT<br> 1176 if setsockopt() indicated an error. 1177 */ 1178 int 1179 dk4socket_option_set_reuse( 1180 dk4_socket_t sock, 1181 int val, 1182 dk4_er_t *erp 1183 ); 1184 1185 /** Set broadcast flag for socket. 1186 Typically you should call this function immediately after 1187 creating the socket before binding any local address. 1188 @param sock 1189 @param val 1190 @param erp 1191 @return DK4_SOCKET_RESULT_SUCCESS on success, 1192 DK4_SOCKET_RESULT_FAILED on error. 1193 1194 Error codes: 1195 - DK4_E_NOT_SUPPORTED<br> 1196 if the setsockopt() function is not available, 1197 - DK4_E_INVALID_ARGUMENTS<br> 1198 if the socket is invalid, 1199 - DK4_E_SOCKET_SETSOCKOPT<br> 1200 if setsockopt() indicated an error. 1201 */ 1202 int 1203 dk4socket_option_set_broadcast( 1204 dk4_socket_t sock, 1205 int val, 1206 dk4_er_t *erp 1207 ); 1208 1209 /* 1210 Set non-blocking mode. 1211 ---------------------- 1212 Module: dk4sock15 1213 */ 1214 1215 /** Set non-blocking mode for socket. 1216 @param sock 1217 @param val 1218 @param erp 1219 @return DK4_SOCKET_RESULT_SUCCESS on success, 1220 DK4_SOCKET_RESULT_FAILED on error. 1221 1222 Error codes: 1223 - DK4_E_INVALID_ARGUMENTS<br> 1224 if any argument is bad, 1225 - DK4_E_SOCKET_FCNTL<br> 1226 with errno value in iDetails1 if the fcntl() function failed, 1227 - DK4_E_SOCKET_IOCTLSOCKET 1228 with WSAGetLastError() value in iDetails1 if the 1229 ioctlsocket() function failed. 1230 */ 1231 int 1232 dk4socket_option_set_nonblock( 1233 dk4_socket_t sock, 1234 int val, 1235 dk4_er_t *erp 1236 ); 1237 1238 /* 1239 Create client side connection. 1240 ------------------------------ 1241 Module: dk4sock16 1242 */ 1243 1244 /** Create client side socket for a given address pair (remote 1245 and local address). 1246 @param protfam Protocol family (PF_INET or PF_INET6). 1247 @param pRemoteAddr Pointer to address structure containing 1248 remote address. 1249 @param szRemoteAddr Size of remote address. 1250 @param pLocalAddr Pointer to address structure for local 1251 address to bind, may be NULL to chose 1252 any address. 1253 @param szLocalAddr Size of remote address, must be 0 if 1254 pLocalAddr is NULL. 1255 @param seconds Timeout in seconds. 1256 @param microSeconds Timeout in microseconds. 1257 @param erp Error report, may be NULL. 1258 @return Valid socket on success, INVALID_SOCKET on error. 1259 1260 Error codes: 1261 - DK4_E_INVALID_ARGUMENTS<br> 1262 if any argument is bad, 1263 - DK4_E_SOCKET_SOCKET<br> 1264 if the socket() function failed to create a new socket, 1265 - DK4_E_SOCKET_BIND<br> 1266 if the bind() function failed to bind the requested local address, 1267 - DK4_E_SOCKET_FCNTL<br> 1268 if the fcntl() function failed, 1269 - DK4_E_SOCKET_IOCTLSOCKET 1270 if the ioctlsocket() function failed. 1271 - DK4_E_SOCKET_CONNECT<br> 1272 if the connect() function failed, 1273 - DK4_E_SOCKET_TIMEOUT<br> 1274 if a timeout occured in the connect attempt, 1275 - DK4_E_SOCKET_SELECT<br> 1276 if the select() function failed, 1277 - DK4_E_SOCKET_GETSOCKOPT<br> 1278 if the getsockopt() function failed. 1279 For all error codes - except DK4_E_SOCKET_TIMEOUT - the iDetails1 1280 field contains the errno or WSAGetLastError() value. 1281 */ 1282 dk4_socket_t 1283 dk4socket_tcp_client_for_addr( 1284 int protfam, 1285 struct sockaddr *pRemoteAddr, 1286 size_t szRemoteAddr, 1287 struct sockaddr *pLocalAddr, 1288 size_t szLocalAddr, 1289 long seconds, 1290 long microSeconds, 1291 dk4_er_t *erp 1292 ); 1293 1294 /* 1295 Choose remote and optionaly local address and connect. 1296 ------------------------------------------------------ 1297 Module: dk4sock17 1298 */ 1299 1300 /** Connect to a specified host name and service name. 1301 @param hostname Host name to connect to. 1302 @param svcname Service name or port number as string. 1303 @param lsvcname Local service name or port number as string. 1304 @param secs Timeout seconds (may be 0). 1305 @param usecs Timeout microseconds (may be 0). 1306 @param nsrv Flag: svname and lsvcname are numeric strings. 1307 @param erp Error report, may be NULL. 1308 @return Valid socket on success, INVALID_SOCKET on error. 1309 1310 Error codes: 1311 - DK4_E_INVALID_ARGUMENTS<br> 1312 if any argument is bad, 1313 - DK4_E_SOCKET_SOCKET<br> 1314 if the socket() function failed to create a new socket, 1315 - DK4_E_SOCKET_BIND<br> 1316 if the bind() function failed to bind the requested local address, 1317 - DK4_E_SOCKET_FCNTL<br> 1318 if the fcntl() function failed, 1319 - DK4_E_SOCKET_IOCTLSOCKET 1320 if the ioctlsocket() function failed. 1321 - DK4_E_SOCKET_GETHOSTBYNAME<br> 1322 if the gethostbyname() function failed to find the remote host. 1323 - DK4_E_SOCKET_GETSERVBYNAME<br> 1324 if the getservbyname() function failed to find the port 1325 number for the remote or local service. 1326 - DK4_E_SOCKET_GETADDRLOC<br> 1327 if the getaddrinfo() function failed to find local addresses. 1328 - DK4_E_SOCKET_GETADDRINFO<br> 1329 if the getaddrinfo() function failed to find the remote host, 1330 - DK4_E_SOCKET_CONNECT<br> 1331 if the connect() function failed, 1332 - DK4_E_SOCKET_TIMEOUT<br> 1333 if a timeout occured in the connect attempt, 1334 - DK4_E_SOCKET_SELECT<br> 1335 if the select() function failed, 1336 - DK4_E_SOCKET_GETSOCKOPT<br> 1337 if the getsockopt() function failed. 1338 - DK4_E_BUG<br> 1339 if the gethostbyname() function returned non-matching or 1340 otherwise illegal address lengths. 1341 For all error codes - except DK4_E_SOCKET_TIMEOUT and 1342 DK4_E_BUG - the iDetails1 1343 field contains the errno or WSAGetLastError() value. 1344 */ 1345 dk4_socket_t 1346 dk4socket_c8_tcp_client_host_num_srv( 1347 const char *hostname, 1348 const char *svcname, 1349 const char *lsvcname, 1350 long secs, 1351 long usecs, 1352 int nsrv, 1353 dk4_er_t *erp 1354 ); 1355 1356 /** Connect to a specified host name and service name. 1357 @param hostname Host name to connect to. 1358 @param svcname Service name or port number as string. 1359 @param lsvcname Local service name or port number as string. 1360 @param secs Timeout seconds (may be 0). 1361 @param usecs Timeout microseconds (may be 0). 1362 @param erp Error report, may be NULL. 1363 @return Valid socket on success, INVALID_SOCKET on error. 1364 1365 Error codes: 1366 - DK4_E_INVALID_ARGUMENTS<br> 1367 if any argument is bad, 1368 - DK4_E_SOCKET_SOCKET<br> 1369 if the socket() function failed to create a new socket, 1370 - DK4_E_SOCKET_BIND<br> 1371 if the bind() function failed to bind the requested local address, 1372 - DK4_E_SOCKET_FCNTL<br> 1373 if the fcntl() function failed, 1374 - DK4_E_SOCKET_IOCTLSOCKET 1375 if the ioctlsocket() function failed. 1376 - DK4_E_SOCKET_GETHOSTBYNAME<br> 1377 if the gethostbyname() function failed to find the remote host. 1378 - DK4_E_SOCKET_GETSERVBYNAME<br> 1379 if the getservbyname() function failed to find the port 1380 number for the remote or local service. 1381 - DK4_E_SOCKET_GETADDRLOC<br> 1382 if the getaddrinfo() function failed to find local addresses. 1383 - DK4_E_SOCKET_GETADDRINFO<br> 1384 if the getaddrinfo() function failed to find the remote host, 1385 - DK4_E_SOCKET_CONNECT<br> 1386 if the connect() function failed, 1387 - DK4_E_SOCKET_TIMEOUT<br> 1388 if a timeout occured in the connect attempt, 1389 - DK4_E_SOCKET_SELECT<br> 1390 if the select() function failed, 1391 - DK4_E_SOCKET_GETSOCKOPT<br> 1392 if the getsockopt() function failed. 1393 - DK4_E_BUG<br> 1394 if the gethostbyname() function returned non-matching or 1395 otherwise illegal address lengths. 1396 For all error codes - except DK4_E_SOCKET_TIMEOUT and 1397 DK4_E_BUG - the iDetails1 1398 field contains the errno or WSAGetLastError() value. 1399 */ 1400 dk4_socket_t 1401 dk4socket_c8_tcp_client_host_srv( 1402 const char *hostname, 1403 const char *svcname, 1404 const char *lsvcname, 1405 long secs, 1406 long usecs, 1407 dk4_er_t *erp 1408 ); 1409 1410 /** Connect to a specified host name and port number. 1411 @param hostname Host name to connect to. 1412 @param portno Port number in host byte order to connect to. 1413 @param lportno Local port number in host byte order (0 = any). 1414 @param secs Timeout seconds (may be 0). 1415 @param usecs Timeout microseconds (may be 0). 1416 @param erp Error report, may be NULL. 1417 @return Valid socket on success, INVALID_SOCKET on error. 1418 1419 Error codes: 1420 - DK4_E_INVALID_ARGUMENTS<br> 1421 if any argument is bad, 1422 - DK4_E_SOCKET_SOCKET<br> 1423 if the socket() function failed to create a new socket, 1424 - DK4_E_SOCKET_BIND<br> 1425 if the bind() function failed to bind the requested local address, 1426 - DK4_E_SOCKET_FCNTL<br> 1427 if the fcntl() function failed, 1428 - DK4_E_SOCKET_IOCTLSOCKET 1429 if the ioctlsocket() function failed. 1430 - DK4_E_SOCKET_GETHOSTBYNAME<br> 1431 if the gethostbyname() function failed to find the remote host. 1432 - DK4_E_SOCKET_GETSERVBYNAME<br> 1433 if the getservbyname() function failed to find the port 1434 number for the remote or local service. 1435 - DK4_E_SOCKET_GETADDRLOC<br> 1436 if the getaddrinfo() function failed to find local addresses. 1437 - DK4_E_SOCKET_GETADDRINFO<br> 1438 if the getaddrinfo() function failed to find the remote host, 1439 - DK4_E_SOCKET_CONNECT<br> 1440 if the connect() function failed, 1441 - DK4_E_SOCKET_TIMEOUT<br> 1442 if a timeout occured in the connect attempt, 1443 - DK4_E_SOCKET_SELECT<br> 1444 if the select() function failed, 1445 - DK4_E_SOCKET_GETSOCKOPT<br> 1446 if the getsockopt() function failed. 1447 - DK4_E_BUG<br> 1448 if the gethostbyname() function returned non-matching or 1449 otherwise illegal address lengths. 1450 For all error codes - except DK4_E_SOCKET_TIMEOUT and 1451 DK4_E_BUG - the iDetails1 1452 field contains the errno or WSAGetLastError() value. 1453 */ 1454 dk4_socket_t 1455 dk4socket_c8_tcp_client_host_port( 1456 const char *hostname, 1457 unsigned short portno, 1458 unsigned short lportno, 1459 long secs, 1460 long usecs, 1461 dk4_er_t *erp 1462 ); 1463 1464 /* 1465 Choose remote and optionally local address and connect (wchar_t). 1466 ----------------------------------------------------------------- 1467 Module: dk4sock18 1468 */ 1469 1470 /** Connect to a specified host name and service name. 1471 @param hostname Host name to connect to. 1472 @param svcname Service name or port number as string. 1473 @param lsvcname Local service name or port number as string. 1474 @param secs Timeout seconds (may be 0). 1475 @param usecs Timeout microseconds (may be 0). 1476 @param nsrv Flag: svname and lsvcname are numeric strings. 1477 @param erp Error report, may be NULL. 1478 @return Valid socket on success, INVALID_SOCKET on error. 1479 1480 Error codes: 1481 - DK4_E_INVALID_ARGUMENTS<br> 1482 if any argument is bad, 1483 - DK4_E_SOCKET_SOCKET<br> 1484 if the socket() function failed to create a new socket, 1485 - DK4_E_SOCKET_BIND<br> 1486 if the bind() function failed to bind the requested local address, 1487 - DK4_E_SOCKET_FCNTL<br> 1488 if the fcntl() function failed, 1489 - DK4_E_SOCKET_IOCTLSOCKET 1490 if the ioctlsocket() function failed. 1491 - DK4_E_SOCKET_GETHOSTBYNAME<br> 1492 if the gethostbyname() function failed to find the remote host. 1493 - DK4_E_SOCKET_GETSERVBYNAME<br> 1494 if the getservbyname() function failed to find the port 1495 number for the remote or local service. 1496 - DK4_E_SOCKET_GETADDRLOC<br> 1497 if the getaddrinfo() function failed to find local addresses. 1498 - DK4_E_SOCKET_GETADDRINFO<br> 1499 if the getaddrinfo() function failed to find the remote host, 1500 - DK4_E_SOCKET_CONNECT<br> 1501 if the connect() function failed, 1502 - DK4_E_SOCKET_TIMEOUT<br> 1503 if a timeout occured in the connect attempt, 1504 - DK4_E_SOCKET_SELECT<br> 1505 if the select() function failed, 1506 - DK4_E_SOCKET_GETSOCKOPT<br> 1507 if the getsockopt() function failed. 1508 - DK4_E_BUG<br> 1509 if the gethostbyname() function returned non-matching or 1510 otherwise illegal address lengths, 1511 - DK4_E_NOT_SUPPORTED<br> 1512 if wide character functions for networking are not available. 1513 For all error codes - except DK4_E_SOCKET_TIMEOUT and 1514 DK4_E_BUG - the iDetails1 1515 field contains the errno or WSAGetLastError() value. 1516 */ 1517 dk4_socket_t 1518 dk4socket_wc_tcp_client_host_num_srv( 1519 const wchar_t *hostname, 1520 const wchar_t *svcname, 1521 const wchar_t *lsvcname, 1522 long secs, 1523 long usecs, 1524 int nsrv, 1525 dk4_er_t *erp 1526 ); 1527 1528 /** Connect to a specified host name and service name. 1529 @param hostname Host name to connect to. 1530 @param svcname Service name or port number as string. 1531 @param lsvcname Local service name or port number as string. 1532 @param secs Timeout seconds (may be 0). 1533 @param usecs Timeout microseconds (may be 0). 1534 @param erp Error report, may be NULL. 1535 @return Valid socket on success, INVALID_SOCKET on error. 1536 1537 Error codes: 1538 - DK4_E_INVALID_ARGUMENTS<br> 1539 if any argument is bad, 1540 - DK4_E_SOCKET_SOCKET<br> 1541 if the socket() function failed to create a new socket, 1542 - DK4_E_SOCKET_BIND<br> 1543 if the bind() function failed to bind the requested local address, 1544 - DK4_E_SOCKET_FCNTL<br> 1545 if the fcntl() function failed, 1546 - DK4_E_SOCKET_IOCTLSOCKET 1547 if the ioctlsocket() function failed. 1548 - DK4_E_SOCKET_GETHOSTBYNAME<br> 1549 if the gethostbyname() function failed to find the remote host. 1550 - DK4_E_SOCKET_GETSERVBYNAME<br> 1551 if the getservbyname() function failed to find the port 1552 number for the remote or local service. 1553 - DK4_E_SOCKET_GETADDRLOC<br> 1554 if the getaddrinfo() function failed to find local addresses. 1555 - DK4_E_SOCKET_GETADDRINFO<br> 1556 if the getaddrinfo() function failed to find the remote host, 1557 - DK4_E_SOCKET_CONNECT<br> 1558 if the connect() function failed, 1559 - DK4_E_SOCKET_TIMEOUT<br> 1560 if a timeout occured in the connect attempt, 1561 - DK4_E_SOCKET_SELECT<br> 1562 if the select() function failed, 1563 - DK4_E_SOCKET_GETSOCKOPT<br> 1564 if the getsockopt() function failed. 1565 - DK4_E_BUG<br> 1566 if the gethostbyname() function returned non-matching or 1567 otherwise illegal address lengths, 1568 - DK4_E_NOT_SUPPORTED<br> 1569 if no wide character functions for networking are avaialble. 1570 For all error codes - except DK4_E_SOCKET_TIMEOUT, DK4_E_NOT_SUPPORTED 1571 and DK4_E_BUG - the iDetails1 1572 field contains the errno or WSAGetLastError() value. 1573 */ 1574 dk4_socket_t 1575 dk4socket_wc_tcp_client_host_srv( 1576 const wchar_t *hostname, 1577 const wchar_t *svcname, 1578 const wchar_t *lsvcname, 1579 long secs, 1580 long usecs, 1581 dk4_er_t *erp 1582 ); 1583 1584 /** Connect to a specified host name and port number. 1585 @param hostname Host name to connect to. 1586 @param portno Port number in host byte order to connect to. 1587 @param lportno Local port number in host byte order (0 = any). 1588 @param secs Timeout seconds (may be 0). 1589 @param usecs Timeout microseconds (may be 0). 1590 @param erp Error report, may be NULL. 1591 @return Valid socket on success, INVALID_SOCKET on error. 1592 1593 Error codes: 1594 - DK4_E_INVALID_ARGUMENTS<br> 1595 if any argument is bad, 1596 - DK4_E_SOCKET_SOCKET<br> 1597 if the socket() function failed to create a new socket, 1598 - DK4_E_SOCKET_BIND<br> 1599 if the bind() function failed to bind the requested local address, 1600 - DK4_E_SOCKET_FCNTL<br> 1601 if the fcntl() function failed, 1602 - DK4_E_SOCKET_IOCTLSOCKET 1603 if the ioctlsocket() function failed. 1604 - DK4_E_SOCKET_GETHOSTBYNAME<br> 1605 if the gethostbyname() function failed to find the remote host. 1606 - DK4_E_SOCKET_GETSERVBYNAME<br> 1607 if the getservbyname() function failed to find the port 1608 number for the remote or local service. 1609 - DK4_E_SOCKET_GETADDRLOC<br> 1610 if the getaddrinfo() function failed to find local addresses. 1611 - DK4_E_SOCKET_GETADDRINFO<br> 1612 if the getaddrinfo() function failed to find the remote host, 1613 - DK4_E_SOCKET_CONNECT<br> 1614 if the connect() function failed, 1615 - DK4_E_SOCKET_TIMEOUT<br> 1616 if a timeout occured in the connect attempt, 1617 - DK4_E_SOCKET_SELECT<br> 1618 if the select() function failed, 1619 - DK4_E_SOCKET_GETSOCKOPT<br> 1620 if the getsockopt() function failed. 1621 - DK4_E_BUG<br> 1622 if the gethostbyname() function returned non-matching or 1623 otherwise illegal address lengths, 1624 - DK4_E_NOT_SUPPORTED<br> 1625 if no wide character functions for networking are available. 1626 For all error codes - except DK4_E_SOCKET_TIMEOUT and 1627 DK4_E_BUG - the iDetails1 1628 field contains the errno or WSAGetLastError() value. 1629 */ 1630 dk4_socket_t 1631 dk4socket_wc_tcp_client_host_port( 1632 const wchar_t *hostname, 1633 unsigned short portno, 1634 unsigned short lportno, 1635 long secs, 1636 long usecs, 1637 dk4_er_t *erp 1638 ); 1639 1640 /* 1641 Choose remote and optionaly local address and connect (dkChar). 1642 --------------------------------------------------------------- 1643 Module: dk4sock19 1644 */ 1645 1646 /** Connect to a specified host name and service name. 1647 @param hostname Host name to connect to. 1648 @param svcname Service name or port number as string. 1649 @param lsvcname Local service name or port number as string. 1650 @param secs Timeout seconds (may be 0). 1651 @param usecs Timeout microseconds (may be 0). 1652 @param nsrv Flag: svname and lsvcname are numeric strings. 1653 @param erp Error report, may be NULL. 1654 @return Valid socket on success, INVALID_SOCKET on error. 1655 1656 Error codes: 1657 - DK4_E_INVALID_ARGUMENTS<br> 1658 if any argument is bad, 1659 - DK4_E_SOCKET_SOCKET<br> 1660 if the socket() function failed to create a new socket, 1661 - DK4_E_SOCKET_BIND<br> 1662 if the bind() function failed to bind the requested local address, 1663 - DK4_E_SOCKET_FCNTL<br> 1664 if the fcntl() function failed, 1665 - DK4_E_SOCKET_IOCTLSOCKET 1666 if the ioctlsocket() function failed. 1667 - DK4_E_SOCKET_GETHOSTBYNAME<br> 1668 if the gethostbyname() function failed to find the remote host. 1669 - DK4_E_SOCKET_GETSERVBYNAME<br> 1670 if the getservbyname() function failed to find the port 1671 number for the remote or local service. 1672 - DK4_E_SOCKET_GETADDRLOC<br> 1673 if the getaddrinfo() function failed to find local addresses. 1674 - DK4_E_SOCKET_GETADDRINFO<br> 1675 if the getaddrinfo() function failed to find the remote host, 1676 - DK4_E_SOCKET_CONNECT<br> 1677 if the connect() function failed, 1678 - DK4_E_SOCKET_TIMEOUT<br> 1679 if a timeout occured in the connect attempt, 1680 - DK4_E_SOCKET_SELECT<br> 1681 if the select() function failed, 1682 - DK4_E_SOCKET_GETSOCKOPT<br> 1683 if the getsockopt() function failed. 1684 - DK4_E_BUG<br> 1685 if the gethostbyname() function returned non-matching or 1686 otherwise illegal address lengths, 1687 - DK4_E_NOT_SUPPORTED<br> 1688 if wide character functions for networking are not available. 1689 For all error codes - except DK4_E_SOCKET_TIMEOUT and 1690 DK4_E_BUG - the iDetails1 1691 field contains the errno or WSAGetLastError() value. 1692 */ 1693 dk4_socket_t 1694 dk4socket_tcp_client_host_num_srv( 1695 const dkChar *hostname, 1696 const dkChar *svcname, 1697 const dkChar *lsvcname, 1698 long secs, 1699 long usecs, 1700 int nsrv, 1701 dk4_er_t *erp 1702 ); 1703 1704 /** Connect to a specified host name and service name. 1705 @param hostname Host name to connect to. 1706 @param svcname Service name or port number as string. 1707 @param lsvcname Local service name or port number as string. 1708 @param secs Timeout seconds (may be 0). 1709 @param usecs Timeout microseconds (may be 0). 1710 @param erp Error report, may be NULL. 1711 @return Valid socket on success, INVALID_SOCKET on error. 1712 1713 Error codes: 1714 - DK4_E_INVALID_ARGUMENTS<br> 1715 if any argument is bad, 1716 - DK4_E_SOCKET_SOCKET<br> 1717 if the socket() function failed to create a new socket, 1718 - DK4_E_SOCKET_BIND<br> 1719 if the bind() function failed to bind the requested local address, 1720 - DK4_E_SOCKET_FCNTL<br> 1721 if the fcntl() function failed, 1722 - DK4_E_SOCKET_IOCTLSOCKET 1723 if the ioctlsocket() function failed. 1724 - DK4_E_SOCKET_GETHOSTBYNAME<br> 1725 if the gethostbyname() function failed to find the remote host. 1726 - DK4_E_SOCKET_GETSERVBYNAME<br> 1727 if the getservbyname() function failed to find the port 1728 number for the remote or local service. 1729 - DK4_E_SOCKET_GETADDRLOC<br> 1730 if the getaddrinfo() function failed to find local addresses. 1731 - DK4_E_SOCKET_GETADDRINFO<br> 1732 if the getaddrinfo() function failed to find the remote host, 1733 - DK4_E_SOCKET_CONNECT<br> 1734 if the connect() function failed, 1735 - DK4_E_SOCKET_TIMEOUT<br> 1736 if a timeout occured in the connect attempt, 1737 - DK4_E_SOCKET_SELECT<br> 1738 if the select() function failed, 1739 - DK4_E_SOCKET_GETSOCKOPT<br> 1740 if the getsockopt() function failed. 1741 - DK4_E_BUG<br> 1742 if the gethostbyname() function returned non-matching or 1743 otherwise illegal address lengths, 1744 - DK4_E_NOT_SUPPORTED<br> 1745 if no wide character functions for networking are avaialble. 1746 For all error codes - except DK4_E_SOCKET_TIMEOUT, DK4_E_NOT_SUPPORTED 1747 and DK4_E_BUG - the iDetails1 1748 field contains the errno or WSAGetLastError() value. 1749 */ 1750 dk4_socket_t 1751 dk4socket_tcp_client_host_srv( 1752 const dkChar *hostname, 1753 const dkChar *svcname, 1754 const dkChar *lsvcname, 1755 long secs, 1756 long usecs, 1757 dk4_er_t *erp 1758 ); 1759 1760 /** Connect to a specified host name and port number. 1761 @param hostname Host name to connect to. 1762 @param portno Port number in host byte order to connect to. 1763 @param lportno Local port number in host byte order (0 = any). 1764 @param secs Timeout seconds (may be 0). 1765 @param usecs Timeout microseconds (may be 0). 1766 @param erp Error report, may be NULL. 1767 @return Valid socket on success, INVALID_SOCKET on error. 1768 1769 Error codes: 1770 - DK4_E_INVALID_ARGUMENTS<br> 1771 if any argument is bad, 1772 - DK4_E_SOCKET_SOCKET<br> 1773 if the socket() function failed to create a new socket, 1774 - DK4_E_SOCKET_BIND<br> 1775 if the bind() function failed to bind the requested local address, 1776 - DK4_E_SOCKET_FCNTL<br> 1777 if the fcntl() function failed, 1778 - DK4_E_SOCKET_IOCTLSOCKET 1779 if the ioctlsocket() function failed. 1780 - DK4_E_SOCKET_GETHOSTBYNAME<br> 1781 if the gethostbyname() function failed to find the remote host. 1782 - DK4_E_SOCKET_GETSERVBYNAME<br> 1783 if the getservbyname() function failed to find the port 1784 number for the remote or local service. 1785 - DK4_E_SOCKET_GETADDRLOC<br> 1786 if the getaddrinfo() function failed to find local addresses. 1787 - DK4_E_SOCKET_GETADDRINFO<br> 1788 if the getaddrinfo() function failed to find the remote host, 1789 - DK4_E_SOCKET_CONNECT<br> 1790 if the connect() function failed, 1791 - DK4_E_SOCKET_TIMEOUT<br> 1792 if a timeout occured in the connect attempt, 1793 - DK4_E_SOCKET_SELECT<br> 1794 if the select() function failed, 1795 - DK4_E_SOCKET_GETSOCKOPT<br> 1796 if the getsockopt() function failed. 1797 - DK4_E_BUG<br> 1798 if the gethostbyname() function returned non-matching or 1799 otherwise illegal address lengths, 1800 - DK4_E_NOT_SUPPORTED<br> 1801 if no wide character functions for networking are available. 1802 For all error codes - except DK4_E_SOCKET_TIMEOUT and 1803 DK4_E_BUG - the iDetails1 1804 field contains the errno or WSAGetLastError() value. 1805 */ 1806 dk4_socket_t 1807 dk4socket_tcp_client_host_port( 1808 const dkChar *hostname, 1809 unsigned short portno, 1810 unsigned short lportno, 1811 long secs, 1812 long usecs, 1813 dk4_er_t *erp 1814 ); 1815 1816 /* 1817 Send and receive data over an established connection. 1818 ----------------------------------------------------- 1819 Module: dk4sock20 1820 */ 1821 1822 /** Send data. 1823 @param sock Socket to use. 1824 @param buf Start address of buffer. 1825 @param pszbuf Pointer to size variable 1826 (in: buffer size, out: bytes send). 1827 @param flags Flags for send() function. 1828 @param secs Seconds for timeout. 1829 @param usecs Microseconds for timeout. 1830 @param erp Error report, may be NULL. 1831 @return DK4_SOCKET_RESULT_SUCCESS on success, 1832 DK4_SOCKET_RESULT_FAILED on error (0 bytes send), 1833 DK4_SOCKET_RESULT_IN_PROGRESS on partial success. 1834 1835 Error codes: 1836 - DK4_E_INVALID_ARGUMENTS<br> 1837 if sock is an invalid socket, buf is NULL, pszbuf is NULL, 1838 *pszbuf is 0 or *pszbuf is too large to fit into an ssize_t 1839 or int, 1840 - DK4_E_SOCKET_TIMEOUT<br> 1841 if the timeout was reached without getting the socket writable, 1842 - DK4_E_SOCKET_SELECT<br> 1843 if the select() function failed (details in iDetails1), 1844 - DK4_E_SOCKET_SEND<br> 1845 if the send() function failed (details in iDetails1). 1846 */ 1847 int 1848 dk4socket_send( 1849 dk4_socket_t sock, 1850 const void *buf, 1851 size_t *pszbuf, 1852 int flags, 1853 long secs, 1854 long usecs, 1855 dk4_er_t *erp 1856 ); 1857 1858 /** Receive data. 1859 @param sock Socket to use. 1860 @param buf Start address of buffer. 1861 @param pszbuf Pointer to size variable 1862 (in: buffer size, out: bytes received). 1863 @param flags Flags for send() function. 1864 @param secs Seconds for timeout. 1865 @param usecs Microseconds for timeout. 1866 @param erp Error report, may be NULL. 1867 @return DK4_SOCKET_RESULT_SUCCESS on success, 1868 DK4_SOCKET_RESULT_FAILED on error. 1869 1870 Error codes: 1871 - DK4_E_INVALID_ARGUMENTS<br> 1872 if sock is an invalid socket, buf is NULL, pszbuf is NULL, 1873 *pszbuf is 0 or *pszbuf is too large to fit into an ssize_t 1874 or int, 1875 - DK4_E_SOCKET_TIMEOUT<br> 1876 if the timeout was reached without getting data on the socket, 1877 - DK4_E_SOCKET_SELECT<br> 1878 if the select() function failed (details in iDetails1), 1879 - DK4_E_SOCKET_RECV<br> 1880 if the send() function failed (details in iDetails1). 1881 */ 1882 int 1883 dk4socket_recv( 1884 dk4_socket_t sock, 1885 void *buf, 1886 size_t *pszbuf, 1887 int flags, 1888 long secs, 1889 long usecs, 1890 dk4_er_t *erp 1891 ); 1892 1893 /* 1894 Connectionless send and receive operations. 1895 ------------------------------------------- 1896 Module: dk4sock21 1897 */ 1898 1899 /** Send UDP datagram. 1900 @param sock Socket to use. 1901 @param buf Start address of buffer. 1902 @param pszbuf Pointer to size variable 1903 (in: buffer size, out: bytes send). 1904 @param flags Flags for sendto() function. 1905 @param saddr Pointer to destination address. 1906 @param addrlen Length of destination address. 1907 @param secs Seconds for timeout. 1908 @param usecs Microseconds for timeout. 1909 @param erp Error report, may be NULL. 1910 @return DK4_SOCKET_RESULT_SUCCESS on success, 1911 DK4_SOCKET_RESULT_IN_PROGRESS on partial success (not all bytes send), 1912 DK4_SOCKET_RESULT_FAILED on error. 1913 1914 Error codes: 1915 - DK4_E_INVALID_ARGUMENTS<br> 1916 if sock is an invalid socket, buf is NULL, pszbuf is NULL, 1917 *pszbuf is 0 or *pszbuf is too large to fit into an ssize_t 1918 or int, 1919 - DK4_E_SOCKET_TIMEOUT<br> 1920 if the timeout was reached without getting data on the socket, 1921 - DK4_E_SOCKET_SELECT<br> 1922 if the select() function failed (details in iDetails1), 1923 - DK4_E_SOCKET_RECV<br> 1924 if the send() function failed (details in iDetails1). 1925 */ 1926 int 1927 dk4socket_sendto( 1928 dk4_socket_t sock, 1929 const void *buf, 1930 size_t *pszbuf, 1931 int flags, 1932 const struct sockaddr *saddr, 1933 size_t addrlen, 1934 long secs, 1935 long usecs, 1936 dk4_er_t *erp 1937 ); 1938 1939 /** Receive UDP datagram. 1940 @param sock Socket to use. 1941 @param buf Start address of buffer. 1942 @param pszbuf Pointer to size variable 1943 (in: buffer size, out: bytes used). 1944 @param flags Flags for recvfrom() function. 1945 @param saddr Pointer to buffer for source address. 1946 @param paddrlen Source address buffer size. 1947 @param secs Seconds for timeout. 1948 @param usecs Microseconds for timeout. 1949 @param erp Error report, may be NULL. 1950 1951 @return DK4_SOCKET_RESULT_SUCCESS on success, 1952 DK4_SOCKET_RESULT_FAILED on error. 1953 1954 Error codes: 1955 - DK4_E_INVALID_ARGUMENTS<br> 1956 if sock is an invalid socket, buf is NULL, pszbuf is NULL, 1957 *pszbuf is 0 or *pszbuf is too large to fit into an ssize_t 1958 or int, 1959 - DK4_E_SOCKET_TIMEOUT<br> 1960 if the timeout was reached without getting data on the socket, 1961 - DK4_E_SOCKET_SELECT<br> 1962 if the select() function failed (details in iDetails1), 1963 - DK4_E_SOCKET_RECV<br> 1964 if the send() function failed (details in iDetails1). 1965 */ 1966 int 1967 dk4socket_recvfrom( 1968 dk4_socket_t sock, 1969 void *buf, 1970 size_t *pszbuf, 1971 int flags, 1972 struct sockaddr *saddr, 1973 size_t *paddrlen, 1974 long secs, 1975 long usecs, 1976 dk4_er_t *erp 1977 ); 1978 1979 /* 1980 Listener socket set (create and delete). 1981 ---------------------------------------- 1982 Module: dk4sock22 1983 */ 1984 1985 /** Allocate memory for a socket set but do not open any 1986 socket (set all to INVALID_SOCKET). 1987 @param max Number of sockets to plan for. 1988 @param erp Error report, may be NULL. 1989 @return Pointer to new socket set on success, NULL on error. 1990 1991 Error codes: 1992 - DK4_E_INVALID_ARGUMENTS<br> 1993 if max is 0, 1994 - DK4_E_MATH_OVERFLOW<br> 1995 on numeric overflow when calculating the number of bytes to 1996 allocate, 1997 - DK4_E_MEMORY_ALLOCATION_FAILED<br> 1998 with mem.elsize and mem.nelem set if there is not enough memory 1999 available. 2000 */ 2001 dk4_socket_set_t * 2002 dk4socket_set_new( 2003 size_t max, 2004 dk4_er_t *erp 2005 ); 2006 2007 /** Delete socket set (do not close anything, just release the memory). 2008 @param set Socket set to destroy. 2009 @param erp Error report, may be NULL. 2010 2011 Error codes: 2012 - DK4_E_INVALID_ARGUMENTS<br> 2013 if set is NULL. 2014 */ 2015 void 2016 dk4socket_set_delete( 2017 dk4_socket_set_t *set, 2018 dk4_er_t *erp 2019 ); 2020 2021 /** Close all sockets and delete the socket set (release memory). 2022 @param set Socket set to close. 2023 @param erp Error report, may be NULL. 2024 2025 Error codes: 2026 - DK4_E_INVALID_ARGUMENTS<br> 2027 if set is NULL. 2028 - DK4_E_SOCKET_CLOSE<br> 2029 with errno/WSAGetLastError() value in iDetails1 if 2030 the close()/closesocket() function failed. 2031 */ 2032 void 2033 dk4socket_set_close( 2034 dk4_socket_set_t *set, 2035 dk4_er_t *erp 2036 ); 2037 2038 /* 2039 Create listener socket set for local/remote connections. 2040 -------------------------------------------------------- 2041 Module: dk4sock23 2042 */ 2043 2044 /** Create listener socket set for a local port number, do 2045 not use getaddrinfo() to obtain local addresses, construct 2046 addresses. 2047 @param portno Local port number to listen on. 2048 @param local Flag: Allow local connections only. 2049 @param backlog Number of connection requests to queue. 2050 @param erp Error report, may be NULL. 2051 @return Socket set on success, NULL on error. 2052 2053 Error codes: 2054 - DK4_E_INVALID_ARGUMENTS<br> 2055 if an invalid argument was specified, 2056 - DK4_E_MATH_OVERFLOW<br> 2057 if there was a numeric overflow in memory size calculation 2058 (should not happen), 2059 - DK4_E_MEMORY_ALLOCATION_FAILED<br> 2060 if a memory allocation failed, 2061 - DK4_E_SOCKET_SOCKET<br> 2062 with errno/WSAGetLastError() value in iDetails1 if 2063 the socket() function failed. 2064 - DK4_E_SOCKET_BIND<br> 2065 with errno/WSAGetLastError() value in iDetails1 if the 2066 bind() function failed. 2067 - DK4_E_SOCKET_LISTEN<br> 2068 with errno/WSAGetLastError() value in iDetails1 if the 2069 listen() function failed. 2070 */ 2071 dk4_socket_set_t * 2072 dk4socket_set_server_directly( 2073 unsigned short portno, 2074 int backlog, 2075 int local, 2076 dk4_er_t *erp 2077 ); 2078 2079 /* 2080 Create listener socket set for local/remote connections. 2081 -------------------------------------------------------- 2082 Module: dk4sock24 2083 */ 2084 2085 /** Create listener socket set for a local port number, use 2086 getaddrinfo() if available to obtain a collection of local 2087 addresses. 2088 @param portno Local port number to listen on. 2089 @param local Flag: Allow local connections only. 2090 @param backlog Number of connection requests to queue. 2091 @param erp Error report, may be NULL. 2092 @return Socket set on success, NULL on error. 2093 2094 Error codes: 2095 - DK4_E_INVALID_ARGUMENTS<br> 2096 if an invalid argument was specified, 2097 - DK4_E_MATH_OVERFLOW<br> 2098 if there was a numeric overflow in memory size calculation 2099 (should not happen), 2100 - DK4_E_MEMORY_ALLOCATION_FAILED<br> 2101 if a memory allocation failed, 2102 - DK4_E_SOCKET_SOCKET<br> 2103 with errno/WSAGetLastError() value in iDetails1 if 2104 the socket() function failed. 2105 - DK4_E_SOCKET_BIND<br> 2106 with errno/WSAGetLastError() value in iDetails1 if the 2107 bind() function failed. 2108 - DK4_E_SOCKET_LISTEN<br> 2109 with errno/WSAGetLastError() value in iDetails1 if the 2110 listen() function failed. 2111 - DK4_E_SOCKET_GETADDRLOC<br> 2112 with errno/WSAGetLastError() value in iDetails1 if the 2113 getaddrinfo() function failed. 2114 */ 2115 dk4_socket_set_t * 2116 dk4socket_c8_set_server( 2117 unsigned short portno, 2118 int backlog, 2119 int local, 2120 dk4_er_t *erp 2121 ); 2122 2123 /** Create listener socket set for a local port number. 2124 @param servicename Local service name. 2125 @param backlog Number of connection requests to queue. 2126 @param local Flag: Allow local connections only. 2127 @param erp Error report, may be NULL. 2128 @return Socket set on success, NULL on error. 2129 2130 Error codes: 2131 - DK4_E_INVALID_ARGUMENTS<br> 2132 if an invalid argument was specified, 2133 - DK4_E_MATH_OVERFLOW<br> 2134 if there was a numeric overflow in memory size calculation 2135 (should not happen), 2136 - DK4_E_MEMORY_ALLOCATION_FAILED<br> 2137 if a memory allocation failed, 2138 - DK4_E_SOCKET_SOCKET<br> 2139 with errno/WSAGetLastError() value in iDetails1 if 2140 the socket() function failed. 2141 - DK4_E_SOCKET_BIND<br> 2142 with errno/WSAGetLastError() value in iDetails1 if the 2143 bind() function failed. 2144 - DK4_E_SOCKET_LISTEN<br> 2145 with errno/WSAGetLastError() value in iDetails1 if the 2146 listen() function failed. 2147 - DK4_E_SOCKET_GETADDRLOC<br> 2148 with errno/WSAGetLastError() value in iDetails1 if the 2149 getaddrinfo() function failed. 2150 - DK4_E_SYNTAX<br> 2151 if a non-digit was found in a port number, 2152 - DK4_E_SOCKET_GETSERVBYNAME<br> 2153 with errno/WSAGetLastError() value in iDetails1 if the 2154 getservbyname() function failed to find a port number of a service, 2155 */ 2156 dk4_socket_set_t * 2157 dk4socket_c8_set_service( 2158 const char *servicename, 2159 int backlog, 2160 int local, 2161 dk4_er_t *erp 2162 ); 2163 2164 /* 2165 dkChar variants of the functions above. 2166 --------------------------------------- 2167 Module: dk4sock25 2168 */ 2169 2170 /** Create listener socket set for a local port number. 2171 @param portno Local port number to listen on. 2172 @param local Flag: Allow local connections only. 2173 @param backlog Number of connection requests to queue. 2174 @param erp Error report, may be NULL. 2175 @return Socket set on success, NULL on error. 2176 2177 Error codes: 2178 - DK4_E_INVALID_ARGUMENTS<br> 2179 if an invalid argument was specified, 2180 - DK4_E_MATH_OVERFLOW<br> 2181 if there was a numeric overflow in memory size calculation 2182 (should not happen), 2183 - DK4_E_MEMORY_ALLOCATION_FAILED<br> 2184 if a memory allocation failed, 2185 - DK4_E_SOCKET_SOCKET<br> 2186 with errno/WSAGetLastError() value in iDetails1 if 2187 the socket() function failed. 2188 - DK4_E_SOCKET_BIND<br> 2189 with errno/WSAGetLastError() value in iDetails1 if the 2190 bind() function failed. 2191 - DK4_E_SOCKET_LISTEN<br> 2192 with errno/WSAGetLastError() value in iDetails1 if the 2193 listen() function failed. 2194 - DK4_E_SOCKET_GETADDRLOC<br> 2195 with errno/WSAGetLastError() value in iDetails1 if the 2196 getaddrinfo() function failed. 2197 */ 2198 dk4_socket_set_t * 2199 dk4socket_set_server( 2200 unsigned short portno, 2201 int backlog, 2202 int local, 2203 dk4_er_t *erp 2204 ); 2205 2206 /** Create listener socket set for a local port number. 2207 @param servicename Local service name. 2208 @param backlog Number of connection requests to queue. 2209 @param local Flag: Allow local connections only. 2210 @param erp Error report, may be NULL. 2211 @return Socket set on success, NULL on error. 2212 2213 Error codes: 2214 - DK4_E_INVALID_ARGUMENTS<br> 2215 if an invalid argument was specified, 2216 - DK4_E_MATH_OVERFLOW<br> 2217 if there was a numeric overflow in memory size calculation 2218 (should not happen), 2219 - DK4_E_MEMORY_ALLOCATION_FAILED<br> 2220 if a memory allocation failed, 2221 - DK4_E_SOCKET_SOCKET<br> 2222 with errno/WSAGetLastError() value in iDetails1 if 2223 the socket() function failed. 2224 - DK4_E_SOCKET_BIND<br> 2225 with errno/WSAGetLastError() value in iDetails1 if the 2226 bind() function failed. 2227 - DK4_E_SOCKET_LISTEN<br> 2228 with errno/WSAGetLastError() value in iDetails1 if the 2229 listen() function failed. 2230 - DK4_E_SOCKET_GETADDRLOC<br> 2231 with errno/WSAGetLastError() value in iDetails1 if the 2232 getaddrinfo() function failed. 2233 - DK4_E_SOCKET_GETSERVBYNAME<br> 2234 with errno/WSAGetLastError() value in iDetails1 if the 2235 getservbyname() function failed to find a port number of a service, 2236 */ 2237 dk4_socket_set_t * 2238 dk4socket_set_service( 2239 const dkChar *servicename, 2240 int backlog, 2241 int local, 2242 dk4_er_t *erp 2243 ); 2244 2245 /* 2246 Get allowed peer from char string. 2247 ---------------------------------- 2248 Module: dk4sock26 2249 */ 2250 2251 /** Get allowed peer from string. 2252 @param peerptr Data structure to save peer information. 2253 @param str Text containing the information. 2254 @param erp Error report, may be NULL. 2255 @return DK4_SOCKET_RESULT_SUCCESS on success, 2256 DK4_SOCKET_RESULT_FAILED on error. 2257 2258 Error codes: 2259 - DK4_E_INVALID_ARGUMENTS 2260 - DK4_E_BUFFER_TOO_SMALL 2261 - DK4_E_SYNTAX<br> 2262 if the IP address component in str is not a valid IPv4 or IPv6 2263 address, the mask component is not a valid IPv4 or IPv6 address 2264 or an unsigned bit number or the bit number is too large, 2265 - DK4_E_SOCKET_INET_PTON<br> 2266 if the inet_pton() function failed for some reason. 2267 */ 2268 int 2269 dk4socket_c8_get_allowed_peer( 2270 dk4_allowed_peer_t *peerptr, 2271 const char *str, 2272 dk4_er_t *erp 2273 ); 2274 2275 /* 2276 Get allowed peer from dkChar string. 2277 ------------------------------------ 2278 Module: dk4sock27 2279 */ 2280 2281 /** Get allowed peer from string. 2282 @param peerptr Data structure to save peer information. 2283 @param str Text containing the information. 2284 @param erp Error report, may be NULL. 2285 @return DK4_SOCKET_RESULT_SUCCESS on success, 2286 DK4_SOCKET_RESULT_FAILED on error. 2287 2288 Error codes: 2289 - DK4_E_INVALID_ARGUMENTS 2290 - DK4_E_BUFFER_TOO_SMALL 2291 - DK4_E_SYNTAX<br> 2292 if the IP address component in str is not a valid IPv4 or IPv6 2293 address, the mask component is not a valid IPv4 or IPv6 address 2294 or an unsigned bit number or the bit number is too large, 2295 - DK4_E_SOCKET_INET_PTON<br> 2296 if the inet_pton() function failed for some reason. 2297 */ 2298 int 2299 dk4socket_get_allowed_peer( 2300 dk4_allowed_peer_t *peerptr, 2301 const dkChar *str, 2302 dk4_er_t *erp 2303 ); 2304 2305 /* 2306 Comparison of allowed peers. 2307 ---------------------------- 2308 Module: dk4sock28 2309 */ 2310 2311 /** Compare allowed peers. 2312 @param pl Left pointer, always dk4_allowed_peer_t. 2313 @param pr Right pointer, dk4_allowed_peer_t or struct sockaddr. 2314 @param cr Comparison criteria: 2315 1: pr is struct sockaddr, else pr is dk4_allowed_peer_t. 2316 @return -1, 0 or 1 for pl<pr, pl==pr, pl>pr. 2317 */ 2318 int 2319 dk4socket_allowed_peer_compare( 2320 const void *pl, 2321 const void *pr, 2322 int cr 2323 ); 2324 2325 /* 2326 Create UDP socket set for local/remote connections. 2327 --------------------------------------------------- 2328 Module: dk4sock29 2329 */ 2330 2331 /** Create server UDP socket set for a local port number, do 2332 not use getaddrinfo() to obtain local addresses, construct 2333 addresses. 2334 @param portno Local port number to listen on. 2335 @param local Flag: Allow local connections only. 2336 @param broadcast Flag: Prepare for broadcast sending. 2337 @param erp Error report, may be NULL. 2338 @return Socket set on success, NULL on error. 2339 2340 Error codes: 2341 - DK4_E_INVALID_ARGUMENTS<br> 2342 if an invalid argument was specified, 2343 - DK4_E_MATH_OVERFLOW<br> 2344 if there was a numeric overflow in memory size calculation 2345 (should not happen), 2346 - DK4_E_MEMORY_ALLOCATION_FAILED<br> 2347 if a memory allocation failed, 2348 - DK4_E_SOCKET_SOCKET<br> 2349 with errno/WSAGetLastError() value in iDetails1 if 2350 the socket() function failed. 2351 - DK4_E_SOCKET_BIND<br> 2352 with errno/WSAGetLastError() value in iDetails1 if the 2353 bind() function failed. 2354 - DK4_E_SOCKET_LISTEN<br> 2355 with errno/WSAGetLastError() value in iDetails1 if the 2356 listen() function failed. 2357 */ 2358 dk4_socket_set_t * 2359 dk4socket_set_udp_directly( 2360 unsigned short portno, 2361 int local, 2362 int broadcast, 2363 dk4_er_t *erp 2364 ); 2365 2366 /* 2367 Create UDP socket set for local/remote connections. 2368 --------------------------------------------------- 2369 Module: dk4sock30 2370 */ 2371 2372 /** Create UDP socket set for a local port number, use 2373 getaddrinfo() if available to obtain a collection of local 2374 addresses. 2375 @param portno Local port number to listen on. 2376 @param local Flag: Allow local connections only. 2377 @param broadcast Flag: Prepare for broadcast send. 2378 @param erp Error report, may be NULL. 2379 @return Socket set on success, NULL on error. 2380 2381 Error codes: 2382 - DK4_E_INVALID_ARGUMENTS<br> 2383 if an invalid argument was specified, 2384 - DK4_E_MATH_OVERFLOW<br> 2385 if there was a numeric overflow in memory size calculation 2386 (should not happen), 2387 - DK4_E_MEMORY_ALLOCATION_FAILED<br> 2388 if a memory allocation failed, 2389 - DK4_E_SOCKET_SOCKET<br> 2390 with errno/WSAGetLastError() value in iDetails1 if 2391 the socket() function failed. 2392 - DK4_E_SOCKET_BIND<br> 2393 with errno/WSAGetLastError() value in iDetails1 if the 2394 bind() function failed. 2395 - DK4_E_SOCKET_LISTEN<br> 2396 with errno/WSAGetLastError() value in iDetails1 if the 2397 listen() function failed. 2398 - DK4_E_SOCKET_GETADDRLOC<br> 2399 with errno/WSAGetLastError() value in iDetails1 if the 2400 getaddrinfo() function failed. 2401 */ 2402 dk4_socket_set_t * 2403 dk4socket_c8_set_udp( 2404 unsigned short portno, 2405 int local, 2406 int broadcast, 2407 dk4_er_t *erp 2408 ); 2409 2410 /** Create UDP socket set for a local port number. 2411 @param servicename Local service name. 2412 @param local Flag: Allow local connections only. 2413 @param broadcast Flag: Prepare for broadcast transmission. 2414 @param erp Error report, may be NULL. 2415 @return Socket set on success, NULL on error. 2416 2417 Error codes: 2418 - DK4_E_INVALID_ARGUMENTS<br> 2419 if an invalid argument was specified, 2420 - DK4_E_MATH_OVERFLOW<br> 2421 if there was a numeric overflow in memory size calculation 2422 (should not happen), 2423 - DK4_E_MEMORY_ALLOCATION_FAILED<br> 2424 if a memory allocation failed, 2425 - DK4_E_SOCKET_SOCKET<br> 2426 with errno/WSAGetLastError() value in iDetails1 if 2427 the socket() function failed. 2428 - DK4_E_SOCKET_BIND<br> 2429 with errno/WSAGetLastError() value in iDetails1 if the 2430 bind() function failed. 2431 - DK4_E_SOCKET_LISTEN<br> 2432 with errno/WSAGetLastError() value in iDetails1 if the 2433 listen() function failed. 2434 - DK4_E_SOCKET_GETADDRLOC<br> 2435 with errno/WSAGetLastError() value in iDetails1 if the 2436 getaddrinfo() function failed. 2437 - DK4_E_SYNTAX<br> 2438 if a non-digit was found in a port number, 2439 - DK4_E_SOCKET_GETSERVBYNAME<br> 2440 with errno/WSAGetLastError() value in iDetails1 if the 2441 getservbyname() function failed to find a port number of a service, 2442 */ 2443 dk4_socket_set_t * 2444 dk4socket_c8_set_udp_service( 2445 const char *servicename, 2446 int local, 2447 int broadcast, 2448 dk4_er_t *erp 2449 ); 2450 2451 /* 2452 Create UDP socket set for local/remote connections. 2453 --------------------------------------------------- 2454 Module: dk4sock31 2455 */ 2456 2457 /** Create UDP socket set for a local port number, use 2458 getaddrinfo() if available to obtain a collection of local 2459 addresses. 2460 @param portno Local port number to listen on. 2461 @param local Flag: Allow local connections only. 2462 @param broadcast Flag: Prepare for broadcast send. 2463 @param erp Error report, may be NULL. 2464 @return Socket set on success, NULL on error. 2465 2466 Error codes: 2467 - DK4_E_INVALID_ARGUMENTS<br> 2468 if an invalid argument was specified, 2469 - DK4_E_MATH_OVERFLOW<br> 2470 if there was a numeric overflow in memory size calculation 2471 (should not happen), 2472 - DK4_E_MEMORY_ALLOCATION_FAILED<br> 2473 if a memory allocation failed, 2474 - DK4_E_SOCKET_SOCKET<br> 2475 with errno/WSAGetLastError() value in iDetails1 if 2476 the socket() function failed. 2477 - DK4_E_SOCKET_BIND<br> 2478 with errno/WSAGetLastError() value in iDetails1 if the 2479 bind() function failed. 2480 - DK4_E_SOCKET_LISTEN<br> 2481 with errno/WSAGetLastError() value in iDetails1 if the 2482 listen() function failed. 2483 - DK4_E_SOCKET_GETADDRLOC<br> 2484 with errno/WSAGetLastError() value in iDetails1 if the 2485 getaddrinfo() function failed. 2486 */ 2487 dk4_socket_set_t * 2488 dk4socket_set_udp( 2489 unsigned short portno, 2490 int local, 2491 int broadcast, 2492 dk4_er_t *erp 2493 ); 2494 2495 /** Create UDP socket set for a local port number. 2496 @param servicename Local service name. 2497 @param local Flag: Allow local connections only. 2498 @param broadcast Flag: Prepare for broadcast transmission. 2499 @param erp Error report, may be NULL. 2500 @return Socket set on success, NULL on error. 2501 2502 Error codes: 2503 - DK4_E_INVALID_ARGUMENTS<br> 2504 if an invalid argument was specified, 2505 - DK4_E_MATH_OVERFLOW<br> 2506 if there was a numeric overflow in memory size calculation 2507 (should not happen), 2508 - DK4_E_MEMORY_ALLOCATION_FAILED<br> 2509 if a memory allocation failed, 2510 - DK4_E_SOCKET_SOCKET<br> 2511 with errno/WSAGetLastError() value in iDetails1 if 2512 the socket() function failed. 2513 - DK4_E_SOCKET_BIND<br> 2514 with errno/WSAGetLastError() value in iDetails1 if the 2515 bind() function failed. 2516 - DK4_E_SOCKET_LISTEN<br> 2517 with errno/WSAGetLastError() value in iDetails1 if the 2518 listen() function failed. 2519 - DK4_E_SOCKET_GETADDRLOC<br> 2520 with errno/WSAGetLastError() value in iDetails1 if the 2521 getaddrinfo() function failed. 2522 - DK4_E_SYNTAX<br> 2523 if a non-digit was found in a port number, 2524 - DK4_E_SOCKET_GETSERVBYNAME<br> 2525 with errno/WSAGetLastError() value in iDetails1 if the 2526 getservbyname() function failed to find a port number of a service, 2527 */ 2528 dk4_socket_set_t * 2529 dk4socket_set_udp_service( 2530 const dkChar *servicename, 2531 int local, 2532 int broadcast, 2533 dk4_er_t *erp 2534 ); 2535 2536 /* 2537 Prepare addresses for UDP client socket. 2538 ---------------------------------------- 2539 Module: dk4sock32 2540 */ 2541 2542 /** Get address family for generic socket address structure. 2543 @param aptr Address of generic socket address structure. 2544 @return AF_INET or AF_INET6 on success, AF_UNSPEC on error. 2545 */ 2546 int 2547 dk4socket_address_family(dk4_sockaddr_storage_t *aptr); 2548 2549 /** Get used structure size for generic socket address structure. 2550 @param aptr Address of generic socket address structure. 2551 @return Size of sockaddr_in or sockaddr_in6 on success, 0 on error. 2552 */ 2553 size_t 2554 dk4socket_address_size(dk4_sockaddr_storage_t *aptr); 2555 2556 /** Complete address structures if IP address was found 2557 (add port numbers). 2558 @param array Address structures array (2 elements: 2559 0=remote, 1=local). 2560 @param remport Remote port number. 2561 @param locport Local port number. 2562 @return DK4_SOCKET_RESULT_SUCCESS on success, 2563 DK4_SOCKET_RESULT_FAILED on error. 2564 */ 2565 int 2566 dk4socket_complete_addresses( 2567 dk4_sockaddr_storage_t *array, 2568 unsigned short remport, 2569 unsigned short locport 2570 ); 2571 2572 /* 2573 Prepare addresses for UDP client socket. 2574 ---------------------------------------- 2575 Module: dk4sock33 2576 */ 2577 2578 /** Find addresses to send UDP packets to a remote host. 2579 @param array Destination array (2 elements), 2580 element 0 is the remote address to send to, 2581 element 1 is the local address to bind. 2582 @param remhost Remote host name or IP address. 2583 @param remport Remote port number in host representation. 2584 @param locport Local port number in host representation. 2585 @param ip4 Flag: Prefer IPv4 addresses. 2586 @param erp Error report, may be NULL. 2587 @return DK4_SOCKET_RESULT_SUCCESS on success, 2588 DK4_SOCKET_RESULT_FAILED on error. 2589 2590 Error codes: 2591 - DK4_E_INVALID_ARGUMENTS<br> 2592 for invalid arguments, 2593 - DK4_E_NOT_FOUND<br> 2594 if the requested host was not found. 2595 */ 2596 int 2597 dk4socket_c8_udp_addresses_numeric( 2598 dk4_sockaddr_storage_t *array, 2599 const char *remhost, 2600 unsigned short remport, 2601 unsigned short locport, 2602 int ip4, 2603 dk4_er_t *erp 2604 ); 2605 2606 /* 2607 Prepare addresses for UDP client socket. 2608 ---------------------------------------- 2609 Module: dk4sock34 2610 */ 2611 2612 /** Find addresses to send UDP packets to a remote host (wchar_t). 2613 @param array Destination array (2 elements), 2614 element 0 is the remote address to send to, 2615 element 1 is the local address to bind. 2616 @param remhost Remote host name or IP address. 2617 @param remport Remote port number in host representation. 2618 @param locport Local port number in host representation. 2619 @param ip4 Flag: Prefer IPv4 addresses. 2620 @param erp Error report, may be NULL. 2621 @return DK4_SOCKET_RESULT_SUCCESS on success, 2622 DK4_SOCKET_RESULT_FAILED on error. 2623 2624 Error codes: 2625 - DK4_E_INVALID_ARGUMENTS<br> 2626 for invalid arguments, 2627 - DK4_E_NOT_FOUND<br> 2628 if the requested host was not found. 2629 */ 2630 int 2631 dk4socket_wc_udp_addresses_numeric( 2632 dk4_sockaddr_storage_t *array, 2633 const wchar_t *remhost, 2634 unsigned short remport, 2635 unsigned short locport, 2636 int ip4, 2637 dk4_er_t *erp 2638 ); 2639 2640 2641 /** Find addresses to send UDP packets to a remote host (dkChar). 2642 @param array Destination array (2 elements), 2643 element 0 is the remote address to send to, 2644 element 1 is the local address to bind. 2645 @param remhost Remote host name or IP address. 2646 @param remport Remote port number in host representation. 2647 @param locport Local port number in host representation. 2648 @param ip4 Flag: Prefer IPv4 addresses. 2649 @param erp Error report, may be NULL. 2650 @return DK4_SOCKET_RESULT_SUCCESS on success, 2651 DK4_SOCKET_RESULT_FAILED on error. 2652 2653 Error codes: 2654 - DK4_E_INVALID_ARGUMENTS<br> 2655 for invalid arguments, 2656 - DK4_E_NOT_FOUND<br> 2657 if the requested host was not found. 2658 - DK4_E_NOT_SUPPORTED<br> 2659 if networking with wide characters is not supported. 2660 */ 2661 int 2662 dk4socket_udp_addresses_numeric( 2663 dk4_sockaddr_storage_t *array, 2664 const dkChar *remhost, 2665 unsigned short remport, 2666 unsigned short locport, 2667 int ip4, 2668 dk4_er_t *erp 2669 ); 2670 2671 2672 /* 2673 Create UDP socket and bind to local port. 2674 ----------------------------------------- 2675 Module: dk4sock35 2676 */ 2677 2678 /** Create UDP socket bound to local port. 2679 @param protfam Protocol family, PF_INET or PF_INET6. 2680 @param pLocalAddr Local address to bind. 2681 @param szLocalAddr Size of local address. 2682 @param erp Error report. may be NULL. 2683 @return Valid socket on success, INVALID_SOCKET on error. 2684 2685 Error codes: 2686 - DK4_E_INVALID_ARGUMENTS<br> 2687 if pLocalAddr is NULL or szLocalAddr is 0 or protfam is not 2688 a valid protocol family, 2689 - DK4_E_SOCKET_SOCKET<br> 2690 with errno/WSAGetLastError() value in iDetails1 if 2691 the socket() function failed, 2692 - DK4_E_SOCKET_BIND<br> 2693 with errno/WSAGetLastError() value in iDetails1 if the 2694 bind() function failed. 2695 */ 2696 dk4_socket_t 2697 dk4socket_udp_client_for_addr( 2698 int protfam, 2699 struct sockaddr *pLocalAddr, 2700 size_t szLocalAddr, 2701 dk4_er_t *erp 2702 ); 2703 2704 /* 2705 Create UDP socket and bind to local port. 2706 ----------------------------------------- 2707 Module: dk4sock36 2708 */ 2709 2710 /** Create UDP socket for communication to remote host (char). 2711 @param array Destination array (2 elements), 2712 element 0 is the remote address we want to send data to, 2713 element 1 is the local address to use. 2714 @param remhost Remote host name or address. 2715 @param remport Remote port number in host representation. 2716 @param locport Local port number in host representation. 2717 @param ip4 Flag: Prefer IPv4 over IPv6. 2718 @param erp Error report, may be NULL. 2719 @return Valid socket on success, INVALID_SOCKET on error. 2720 */ 2721 dk4_socket_t 2722 dk4socket_c8_udp_client_for_host( 2723 dk4_sockaddr_storage_t *array, 2724 const char *remhost, 2725 unsigned short remport, 2726 unsigned short locport, 2727 int ip4, 2728 dk4_er_t *erp 2729 ); 2730 2731 /* 2732 Create UDP socket and bind to local port. 2733 ----------------------------------------- 2734 Module: dk4sock37 2735 */ 2736 2737 /** Create UDP socket for communication to remote host (wchar_t). 2738 @param array Destination array (2 elements), 2739 element 0 is the remote address we want to send data to, 2740 element 1 is the local address to use. 2741 @param remhost Remote host name or address. 2742 @param remport Remote port number in host representation. 2743 @param locport Local port number in host representation. 2744 @param ip4 Flag: Prefer IPv4 over IPv6. 2745 @param erp Error report, may be NULL. 2746 @return Valid socket on success, INVALID_SOCKET on error. 2747 */ 2748 dk4_socket_t 2749 dk4socket_wc_udp_client_for_host( 2750 dk4_sockaddr_storage_t *array, 2751 const wchar_t *remhost, 2752 unsigned short remport, 2753 unsigned short locport, 2754 int ip4, 2755 dk4_er_t *erp 2756 ); 2757 2758 /** Create UDP socket for communication to remote host (dkChar). 2759 @param array Destination array (2 elements), 2760 element 0 is the remote address we want to send data to, 2761 element 1 is the local address to use. 2762 @param remhost Remote host name or address. 2763 @param remport Remote port number in host representation. 2764 @param locport Local port number in host representation. 2765 @param ip4 Flag: Prefer IPv4 over IPv6. 2766 @param erp Error report, may be NULL. 2767 @return Valid socket on success, INVALID_SOCKET on error. 2768 */ 2769 dk4_socket_t 2770 dk4socket_udp_client_for_host( 2771 dk4_sockaddr_storage_t *array, 2772 const dkChar *remhost, 2773 unsigned short remport, 2774 unsigned short locport, 2775 int ip4, 2776 dk4_er_t *erp 2777 ); 2778 2779 #ifdef __cplusplus 2780 } 2781 #endif 2782 2783 #endif 2784 /* ifndef DK4SOCK_H_INCLUDED */ 2785 2786