xcall GETMAC, addr {,maxcount, adapters(1)}

GETMAC.SBR returns the hardware MAC ("Media Access Control") address of the Ethernet controller. Depending on how the addr parameter is mapped, it either returns it as a set of six decimal numbers in an array, or as a string of the format xx:xx:xx:xx:xx:xx (where each ‘xx’ is a hex octet). Under Windows, it can also return a list of all the available adapters.

Parameters

addr [out]

The returned MAC address, mapped either as:

MAP1 ADDR

   MAP2 ADDRB(6),B,1

Or

MAP1 ADDR,S,18

In the first case, the MAC address is returned as a sequence of 6 decimal values, one byte each. In the second, it is returned as a string in the format "xx:xx:xx:xx:xx:xx" (where each 'xx' is a hex octet).

maxcount  (optional, Windows only)  [in]

This optional parameter may be used under Windows, in conjunction with the following adapters parameter, to retrieve a list of all the available Ethernet adapters on the local PC. The value of maxcount must be the same or less than the mapped size of the adapters array and serves to set a limit on the number of adapters about which information will be returned.

adapters  (optional, Windows only)  [out]

If specified, this array will return details about all of the available adapters, and must be mapped as follows:

map1 adapters(#)              ! # must be >= value of maxcount

   map2 adap'mac(8),b,1       ! MAC address (decimal bytes)

   map2 adap'mac$,s,24        ! MAC address (hex format)

   map2 adap'name$,s,128      ! Adapter name

   map2 adap'descr$,s,128     ! Adapter description

   map2 adap'ip$,s,16         ! IP address

Comments

The main purpose of this subroutine would probably be as a security mechanism to prevent unauthorized use of an application, since every Ethernet controller ever produced has a unique MAC address, and there is no practical way to duplicate them. However, before you get too excited about this as a replacement for SSD chips, be aware that there are a number of potential or real pitfalls with MAC addresses:

•   A computer may have multiple Ethernet cards. Under UNIX variants, GETMAC.SBR only returns the first one. Under Windows, the addr parameter will return the one which appears to be the one currently connecting the PC to the network, but this determination can be confused, and it can obviously change over time. (For example, a laptop user might connect with a wired adapter sometimes, and with a wireless adapter other times.)

•   In the PC environment, an adapter could be portable (such as a PCMCIA or USB adapter).

•   With virtualization software (like VMware or Parallels), you might have virtualized adapters, in effect allowing two machines to have the same MAC address. (Such adapters would most likely have the word "Virtual" in their description, so if this is a concern, you might want to check the descriptions via the adapters list and disallow licensing to such a Virtual adapter.

•   Adapters that are disabled will not show up in the list. (So, for example, if you attach your license to a particular adapter, and later the user disables it in favor of another adapter, you might have to re-license it.)

Most of the potential problems listed above apply only to PCs (since a UNIX server is unlikely to suffer from such changes to the adapter hardware list). One strategy for dealing with the variability of adapters on a PC would be to scan the list of available adapters in order to choose one (or two) that appear to be permanent (i.e. not virtual, not USB, etc.) for licensing purposes. At runtime, as long as it (or one of them) is present in the current list, you could be reasonably sure that the software hadn't been moved from the licensed machine.

Note that the first two fields of the adapters array are mapped to accommodate up to eight bytes of MAC address, which is a nod to some future possibility not currently applicable.

See CONDEV and MX_GETIP (Get IP address) for information on getting the IP address.