Developer

API Reference

INetwork_GenerateIPv6PrivAddr()

Brew Release
Brew MP 1.0.2
See Also
Error Codes IBearerTechnology INetwork INetwork_GetIPv6PrivAddrInfo
Description
This function requests to generate a private IPv6 address. This API is part of functionality based on RFC 3041 - "Privacy Extensions for Stateless Address Autoconfiguration in IPv6".
Note that each INetwork instance can hold a single private address at a given moment. Each call to INetwork_GenerateIPv6PrivAddr() overwrites any information regarding the address associated with a previous INetwork_GenerateIPv6PrivAddr() request. Namely, the previous address will not be handled anymore, and no events regarding it will be forwarded to the application. The state of the address is always associated with the newest generation request.
* Shared vs. Unique Address: The user can generate two types of private addresses: unique or shared. - With a shared address, it is possible that several applications will receive
the same address upon generate() request. This might even be true for applications that have selected different network types. - With a unique address, each generate() request will produce a different private address.

* Address Generation Sequence: An application wishing to generate a private IPv6 address, should do the following: - Call INetwork_OnEvent(pMe->pINetwork, NETWORK_EVENT_IPV6_PRIVACY_ADDR, pfn, pUser, TRUE),
to register for IPv6 Private Addresses events.
- Call INetwork_GenerateIPv6PrivAddr() to generate the address.
The address may be synchronously or asynchronously generated.
- Check the return value of the function:
a. If the function returned AEE_NET_SUCCESS, a valid address was generated. The application should call INetwork_GetIPv6PrivAddrInfo() to retrieve the newly generated address. Address state would now be VALID.
b. If the function returned AEE_NET_EWOULDBLOCK: the address was not synchronously generated. The application should wait for a NETWORK_EVENT_IPV6_PRIVACY_ADDR event and then call INetwork_GetIPv6PrivAddrInfo() to get the information regarding the address. Until the address is generated, its state would be GEN_PENDING.
c. If the function returned another error code, address generation failed. Address state would now be GEN_FAILED.
- As soon as the address is in valid state, the application should bind a socket to it.
If no socket binds to the address within a certain time, the address will be deleted.
* Address Deprecation: Private address may become deprecated. On deprecation, the application should cease using sockets bound to the deprecated address as soon as possible. If the application can not close the sockets immediately, it is allowed to continue using them for a while. However, as soon as possible, the application should close the sockets and generate a new address. Binding a new socket to the address after it became deprecated will fail. A deprecated address will be deleted when no socket is still bound to it.
* Address Deletion: A private address will be deleted in the following cases: - No socket is being bound to the address within a certain time from its generation.
- The address becomes deprecated and no socket is bound to it anymore.
- The network goes down or an IPv6 prefix expiration occurs.

* IPv6 Private Address States: A private IPv6 address may be in one of the following states:
- AEE_IPV6_PRIV_ADDR_STATE_VALID: the address is valid, and sockets
can be bound to it.
- AEE_IPV6_PRIV_ADDR_STATE_DEPRECATED: the address has been deprecated.
The application should close the sockets bound to the address, but can technically still keep using them. However, the application will fail to bind new sockets to the deprecated address. Once no sockets are bound to the deprecated address, it will be deleted.
- AEE_IPV6_PRIV_ADDR_STATE_DELETED: the address was deleted.
Any attempt to bind to a deleted address will fail.
- AEE_IPV6_PRIV_ADDR_STATE_GEN_PENDING: An application has requested to generate
an address, but the generation was not yet completed. When generation successfully completes, the application will receive a NETWORK_EVENT_IPV6_PRIVACY_ADDR event, and the state of the address will be AEE_IPV6_PRIV_ADDR_STATE_VALID.
- AEE_IPV6_PRIV_ADDR_STATE_GEN_FAILED: Address generation was failed.

* Consecutive generation requests: Since each INetwork instance can hold a single private address at a given moment, generation request performed while the previous address is still valid, will overwrite any information regarding the address associated with a previous generate() request. Namely, the previous address will not be handled anymore, and no events regarding it will be forwarded to the application. The state of the address is always associated with the newest generation request.
Parameters
  • me
    []:
    The interface pointer.
  • bIsUnique
    []:
    TRUE if the user wishes to generate a unique address, FALSE if the user wishes to generate a shared address.
Interface
Prototype
  static int INetwork_GenerateIPv6PrivAddr(INetwork* me,
                                           boolean   bIsUnique);
        
Return
AEE_NET_SUCCESS: An IPv6 private address was successfully generated. AEE_NET_EOPNOTSUPP: The operation is not supported. AEE_NET_ENETNONET: The network subsystem is unavailable. AEE_NET_EWOULDBLOCK: The address was not synchronously generated, the current state of the address is AEE_IPV6_PRIV_ADDR_STATE_GEN_PENDING. The user should wait for an event and then get the information regarding the address. EALREADY: An INetwork_GenerateIPv6PrivAddr() request is already in process. This error code will be returned if the user calls INetwork_GenerateIPv6PrivAddr() while the state of the address is AEE_IPV6_PRIV_ADDR_STATE_GEN_PENDING. Other AEE error code : As appropriate.
Side Effect
None.
Comment
None.
  • Follow