NET_Address* NET_RefAddress(NET_Address *address);
| NET_Address * | address | 参照を追加するNET_Address |
1つのNET_Addressは, 解決の処理を行う背後のスレッドなどのライブラリの様々な箇所で共有しているため, このオブジェクトは参照カウントしている. そのため, どこでも必要ならば使用するために宣言することができ, 不要になればアドレスへの参照をどこでも切り離すことができる. オブジェクトの資源は参照の最後の切り離しで解放される.
この関数はNET_Addressの参照を追加し, 参照カウンタを1加算する.
ドキュメントには, いつアプリケーションが明示的にアドレスへの参照を切り離さなければならないかが記述されている. 例えば, NET_ResolveHostname()は既に参照されているアドレスを生成するため, 呼び出し側は不要になれば参照を切り離す必要がある.
一般的には, アドレスへの明示的な参照が必要なのはアプリケーションの異なる箇所でアドレスを共有する場合のみである.
通常の使用では, アドレスを生成して切り離す(free()のように)だけだが, 必要ならば参照を追加することもできる.
この関数の戻り値は引数と同じアドレスで, 参照と割り当てを1行で行えるようになっている:
myAddr = NET_RefAddress(yourAddr);
この関数はどのスレッドからも安全に呼べる.