Deprecate string-based APIs in IPCore

[michalpasztamobica]

Description (required)

MBED_DEPRECATED macros are added to string-based APIs.
New, non-string-based APIs are added in their place.
Wiced binaries rebuilt.
Any existing stubs or mocks are adjusted to compile and run with the newly added non-string based functions.

Summary of change (What the change is for and why)

Quoting @SeppoTakalo :

Problem with string bases addresses are that they silently spawn DNS query which may fail. User should be aware that they require DNS query in order to covert addresses.
Second problem is that "host, port" combination is very much IP specific way, and Socket API should be abstract allowing same API to be used on non-IP cases.

The problem is being addressed by marking all string-based API functions with MBED_DEPRECATED macro and adding a new API, that uses SocketAddress instead. This is NOT a breaking change. This PR is to give everyone using deprecated APIs time to adjust. The breaking change will come with mbed-os-6.

Documentation (Details of any document updates required)

The documentation for all the modified functions has been adjusted.

---

Pull request type (required)

[] Patch update (Bug fix / Target update / Docs update / Test update / Refactor)
[x] Feature update (New feature / Functionality change / New API)
[] Major update (Breaking change E.g. Return code change / API behaviour change)

---

Test results (required)

[] No Tests required for this change (E.g docs only update)
[] Covered by existing mbed-os tests (Greentea or Unittest)
[x] Tests / results supplied as part of this PR

---

Reviewers (optional)

@SeppoTakalo
@AnttiKauppila

---

Release Notes (required for feature/major PRs)

This is NOT a breaking changes, but it is worth notifying all API users, that the string-based APIs are going to be removed soon.

Summary of changes

The following API functions are being deprecated and will be removed in mbed-os-6:

TCPServer (whole class is deprecated already)
TCPSocket::connect(const char *host, uint16_t port);
TLSSocket::connect(const char *host, uint16_t port);
DTLSSocket::connect(const char *host, uint16_t port)
InternetDatagramSocket::sendto(const char *host, uint16_t port, data, size);
InternetSocket::bind(const char *address, uint16_t port);
L3IP:add_ipv4_multicast_group(const char *address);
L3IP:add_ipv6_multicast_group(const char *address)
L3IP:remove_ipv4_multicast_group(const char *address);
L3IP:remove_ipv6_multicast_group(const char *address)
NetworkInterface::get_ip_address()
NetworkInterface::get_netmask()
NetworkInterface::get_gateway()
NetworkInterface::set_network(const char *ip_address, const char *netmask, const char *gateway)
NetworkStack::get_ip_address()
NetworkStack::get_ip_address_if()

Impact of changes

Code gives deprecated warnings whenever old API is used.

Migration actions required

Switch to the new SocketAddress based API.

[michalpasztamobica]

@0xc0170 , This PR and #11653 depend on each other, because they both need the wiced binaries rebuilt. Whichever of them gets merged second will have to rebuild the binaries again on top of the other (unless we have a binary merge tool?). I submitted this PR anyway and would be grateful if you can run CI after review, because I might have missed some required modifications. I tried building all net-* tests for K64F+wifi and UBLOX+eth as well as unittests, but there may be some more dependencies which neither static analysis nor the current compilations noticed.

[michalpasztamobica]

@AnttiKauppila , @SeppoTakalo , initially I modified the type of internal addresses in EMACInterface to SocketAddress, otherwise we are effectively loosing some information and encouraging usage of string-based interfaces from lower level APIs and EMAC implementations. They are however used during bringup() and the bringup() looks subtly different for every EMAC target implementation (including Wiced interface kept in a different repo...).
Do you agree that this change makes sense? If so, can we do it in a separate lower priority task, not to hinder these important changes.

[ciarmcom]

@michalpasztamobica, thank you for your changes.
@AnttiKauppila @SeppoTakalo @ARMmbed/mbed-os-test @ARMmbed/mbed-os-ipcore @ARMmbed/mbed-os-wan @ARMmbed/mbed-os-maintainers please review.

[bulislaw]

Overview looks good, someone needs to do a proper review.

[0xc0170]

CI started

[mbed-ci]

Test run: FAILED

Summary: 1 of 4 test jobs failed
Build number : 1
Build artifacts

Failed test jobs:

• jenkins-ci/mbed-os-ci_build-ARM

[michalpasztamobica]

Just pushed a fix to the CI's failure. The problem was that I did not always return value in a non-void function, but it only threw an error in a particular configuration, which I haven't tested.
Thank you, Mr. Jenkins.
@0xc0170 , would you please restart the CI?

[michalpasztamobica]

I now forced-pushed another tiny overlooked bug: in EMACInterface::get_gateway I made a copy&paste error and set _netmask instead of gateway. That variable get overriden with every function call, so it didn't really matter, until some subclass would start making use of it without refreshing - hence our CI missed it.

[mbed-ci]

Test run: FAILED

Summary: 1 of 12 test jobs failed
Build number : 2
Build artifacts

Failed test jobs:

• jenkins-ci/mbed-os-ci_wisun-mesh-test

[0xc0170]

CI restarted

[michalpasztamobica]

This time Jenkins found an issue in Nanostack interface. We don't have unittests for LWIP and Nanostack Interface wrapper classes (perhaps we should?) . When adding a new API I also switched the wrapper class to make use of it. When doing this I forgot, that we now return NSAPI_ERROR_OK, which evaluates to 0, so this should fix it:

 const char *InterfaceNanostack::get_ip_address()
 {
-    if (_interface->get_ip_address(&ip_addr)) {
+    if (_interface->get_ip_address(&ip_addr) == NSAPI_ERROR_OK) {

Thanks for restarting CI, @0xc0170 .

[mbed-ci]

Test run: SUCCESS

Summary: 12 of 12 test jobs passed
Build number : 3
Build artifacts