netResolveHostname function net

Pointer<NetAddress> netResolveHostname(String? host)

Resolve a human-readable hostname.

SDL_net doesn't operate on human-readable hostnames (like www.libsdl.org but on computer-readable addresses. This function converts from one to the other. This process is known as "resolving" an address.

You can also use this to turn IP address strings (like "159.203.69.7") into NET_Address objects.

Note that resolving an address is an asynchronous operation, since the library will need to ask a server on the internet to get the information it needs, and this can take time (and possibly fail later). This function will not block. It either returns NULL (catastrophic failure) or an unresolved NET_Address. Until the address resolves, it can't be used.

If you want to block until the resolution is finished, you can call NET_WaitUntilResolved(). Otherwise, you can do a non-blocking check with NET_GetAddressStatus().

When you are done with the returned NET_Address, call NET_UnrefAddress() to dispose of it. You need to do this even if resolution later fails asynchronously.

\param host The hostname to resolve. \returns A new NET_Address on success, NULL on error; call SDL_GetError() for details.

\threadsafety It is safe to call this function from any thread.

\since This function is available since SDL_net 3.0.0.

\sa NET_WaitUntilResolved \sa NET_GetAddressStatus \sa NET_RefAddress \sa NET_UnrefAddress

extern SDL_DECLSPEC NET_Address * SDLCALL NET_ResolveHostname(const char *host)

Implementation

Pointer<NetAddress> netResolveHostname(String? host) {
  final netResolveHostnameLookupFunction = _libNet
      .lookupFunction<
        Pointer<NetAddress> Function(Pointer<Utf8> host),
        Pointer<NetAddress> Function(Pointer<Utf8> host)
      >('NET_ResolveHostname');
  final hostPointer = host != null ? host.toNativeUtf8() : nullptr;
  final result = netResolveHostnameLookupFunction(hostPointer);
  calloc.free(hostPointer);
  return result;
}