API updates

doc/api/dialogs.md

@@ -7,7 +7,7 @@ Most functions in the API allows two ways to refer to the dialogs:
 
     You can also get a full dialog object calling [get_dialog/2](#get_dialog2) using a request or subscription object and a call object (received in callback functions like [sip_invite/2](../reference/callback_functions.md#sip_invite2), [sip_options/2](../reference/callback_functions.md#sip_options2), etc.
 
-* From a *dialog handle* (`nksip:id()`). You can get a dialog handle from a dialog object, request or response objects or handles for dialogs, request, responses or subscriptions, calling [get_id/1](#get_id/1). You can then use the handle to call most functions in this API. 
+* From a *dialog handle* (`nksip:handle()`). You can get a dialog handle from a dialog object, request or response objects or handles for dialogs, request, responses or subscriptions, calling [get_handle/1](#get_handle/1). You can then use the handle to call most functions in this API. 
 
     In this case, the API function must contact with the corresponding call process to get the actual dialog, so you cannot use this method _inside_ the same call process (like in the callback functions). This method is useful to refer to the dialog from a _spawned_ process, avoiding the need to copy the full object. Please notice that the dialog object may not exists any longer at the moment that the handle is used. Most functions return `error` in this case.
 
@@ -17,11 +17,12 @@ Most functions in the API allows two ways to refer to the dialogs:
 
 Function|Description
 ---|---
-[get_id/1](#get_id1)|Grabs a dialog's handle
+[get_handle/1](#get_handle1)|Grabs a dialog's handle
 [app_id/1](#app_id1)|Gets then SipApp's _internal name_
 [app_name/1](#app_name1)|Gets the SipApp's _user name_
 [call_id/1](#call_id1)|Gets the Call-ID header of the dialog
 [meta/2](#meta2)|Gets specific metadata from the dialog
+[metas/2](#meta2)|Gets specific metadata from the dialog
 [get_dialog/2](#get_dialog2)|Gets a dialog object from a request and a call objects
 [get_all/0](#get_all0)|Get the handles of all started dialogs
 [get_all/2](#get_all2)|Gets all current started dialog handles belonging to App and having Call-ID
@@ -32,69 +33,78 @@ Function|Description
 
 ## Functions List
 
-### get_id/1
+### get_handle/1
 ```erlang
-nksip_dialog:get_id(nksip:dialog()|nksip:request()|nksip:response()|nksip:id()) ->
-    nksip:id().
+nksip_dialog:get_handle(nksip:dialog()|nksip:request()|nksip:response()|nksip:handle()) ->
+    {ok, nksip:handle()} | {error, term()}.
 ```
 Grabs a dialog's handle.
 
 
 ### app_id/1
 ```erlang
-nksip_dialog:app_id(nksip:dialog()|nksip:id()) -> 
-    nksip:app_id().
+nksip_dialog:app_id(nksip:dialog()|nksip:handle()) -> 
+    {ok, nksip:app_id()}.
 ```
 Gets then SipApp's _internal name_.
 
 
 ### app_name/1
 ```erlang
-nksip_dialog:app_name(nksip:dialog()|nksip:id()) -> 
-    term().
+nksip_dialog:app_name(nksip:dialog()|nksip:handle()) -> 
+    {ok, nksip:app_name()}.
 ```
 Gets the SipApp's _user name_
 
 
 ### call_id/1
 ```erlang
-nksip_dialog:call_id(nksip:dialog()|nksip:id()) ->
-    nksip:call_id().
+nksip_dialog:call_id(nksip:dialog()|nksip:handle()) ->
+    {ok, nksip:call_id()}.
 ```
 Gets the Call-ID header of the dialog.
 
 
 ### meta/2
 ```erlang
-nksip_dialog:meta(nksip_dialog:field()|[nksip_dialog:field()], nksip:dialog()|nksip:id()) -> 
-    term() | [{field(), term()}] | error.
+nksip_dialog:meta(nksip_dialog:field(), nksip:dialog()|nksip:handle()) -> 
+    {ok, term()} | {error, term()}.
+```
+Gets specific metadata from the dialog.
+
+See [Metadata Fields](../reference/metadata.md) for a description of available fields.
+
+
+### metas/2
+```erlang
+nksip_dialog:meta([nksip_dialog:field()], nksip:dialog()|nksip:handle()) -> 
+    {ok, [{field(), term()}]} | {error, term()}.
 ```
 Gets specific metadata from the dialog.
 
 See [Metadata Fields](../reference/metadata.md) for a description of available fields.
-If `Meta` is simple term, its value is returned. If it is a list, it will return a list of tuples, where the first element is the field name and the second is the value.
 
 
 ### get_dialog/2
 ```erlang
 nksip_dialog:get_dialog(nksip:request()|nksip:response()|nksip:subscription(), nksip:call()) ->
-    nksip:dialog()|error.
+    {ok, nksip:dialog()} | {error, term()}.
 ```
 Gets a dialog object from a _request_, _response_ or _subscription_ object and a _call object_.
 
 
 ### get_all/0
 ```erlang
 nksip_dialog:get_all() ->
-    [nksip:id()].
+    [nksip:handle()].
 ```
 Get the handles of all started dialogs.
 
 
 ### get_all/2
 ```erlang
 nksip_dialog:get_all(App::nksip:app_id(), CallId::nksip:call_id()) ->
-    [nksip:id()].
+    [nksip:handle()].
 ```
 Gets all current started dialog handles belonging to a SipApp and having a specific _Call-ID_.
 
@@ -109,7 +119,7 @@ Sends an in-dialog BYE to all existing dialogs.
 
 ### stop/1
 ```erlang
-nksip_dialog:stop(nksip:id()) ->
+nksip_dialog:stop(nksip:handle()) ->
     ok.
 ```
 Destroys an existing dialog from its handle (remove it from memory).

doc/api/requests.md

@@ -4,7 +4,7 @@ This document describes the API NkSIP makes available to extract information fro
 
 Most functions in the API allows two ways to refer to the requests:
 * From a full *request object* (`nksip:request()`). Most functions called in the SipApp's _callback module_ receive a full request object, and you can use these functions to get information from it.
-* From a *request handle* (`nksip:id()`). You can get a request handle from a request object using [get_id/1](#get_id1). You can then use the handle to call most functions in this API. 
+* From a *request handle* (`nksip:handle()`). You can get a request handle from a request object using [get_id/1](#get_id1). You can then use the handle to call most functions in this API. 
 
     In this case, the API function must contact with the corresponding call process to get the actual request, so you cannot use this method _inside_ the same call process (like in the callback functions). This method is useful to refer to the request from a _spawned_ process (specially for [reply/2](#reply2)), avoiding the need to copy the full object. Please notice that the request object may not exists any longer at the moment that the handle is used. Most functions return `error` in this case.
 
@@ -21,6 +21,7 @@ Function|Description
 [body/1](#body1)|Gets the body of the request
 [call_id/1](#call_id1)|Gets the Call-ID header of the request
 [meta/2](#meta2)|Gets specific metadata from the request
+[metas/2](#meta2)|Gets specific metadata from the request
 [header/2](#header2)|Gets the values for a header or headers in a request
 [reply/2](#reply2)|Sends a reply to a request using a handle
 [is_local_route/1](#is_local_route1)|Checks if this request would be sent to a local address in case of beeing proxied
@@ -30,80 +31,86 @@ Function|Description
 
 ### get_id/1
 ```erlang
-nksip_request:get_id(nksip:request()|nksip:id()) ->
-    nksip:id().
+nksip_request:get_handle(nksip:request()|nksip:handle()) ->
+    {ok, nksip:handle()} | {error, term()}.
 ```
 Grabs a request's handle.
 
 
 ### app_id/1
 ```erlang
-nksip_request:app_id(nksip:request()|nksip:id()) -> 
-    nksip:app_id().
+nksip_request:app_id(nksip:request()|nksip:handle()) -> 
+    {ok, nksip:app_id()} | {error, term()}.
 ```
 Gets then SipApp's _internal name_.
 
 
 ### app_name/1
 ```erlang
-nksip_request:app_name(nksip:request()|nksip:id()) -> 
-    term().
+nksip_request:app_name(nksip:request()|nksip:handle()) -> 
+    {ok, nksip:app_name()} | {error, term()}.
 ```
 Gets the SipApp's _user name_
 
 
 ### method/1
 ```erlang
-nksip_request:method(nksip:request()|nksip:id()) ->
-    nksip:method() | error.
+nksip_request:method(nksip:request()|nksip:handle()) ->
+    {ok, nksip:method()} | {error, term()}.
 ```
 Gets the method of the request.
 
 
 ### body/1
 ```erlang
-nksip_request:body(nksip:request()|nksip:id()) ->
-    nksip:body() | error.
+nksip_request:body(nksip:request()|nksip:handle()) ->
+    {ok, nksip:body()} | {error, term()}.
 ```
 Gets the body of the request.
 
 
 ### call_id/1
 ```erlang
-nksip_request:call_id(nksip:request()|nksip:id()) ->
-    nksip:call_id().
+nksip_request:call_id(nksip:request()|nksip:handle()) ->
+    {ok, nksip:call_id()} | {error, term()}.
 ```
 Gets the Call-ID header of the request.
 
 
 ### meta/2
 ```erlang
-nksip_request:meta(Meta::nksip_sipmsg:field()|[nksip_sipmsg:field()], nksip:request()|nksip:id()) ->
-    term() | [{nksip_sipmsg:field(), term()}] | error.
+nksip_request:meta(Meta::nksip_sipmsg:field(), nksip:request()|nksip:handle()) ->
+    {ok, term()} | {error, term()}.
 ```
 Gets specific metadata from the request.
 
 See [Metadata Fields](../reference/metadata.md) for a description of available fields.
-If `Meta` is simple term, its value is returned. If it is a list, it will return a list of tuples, where the first element is the field name and the second is the value.
 
 
-### header/2
+### metas/2
 ```erlang
-nksip_request:header(Name::string()|binary()|[string()|binary()], nksip:request()|nksip:id()) -> 
-    [binary()] | [{binary(), binary()}] | error.
+nksip_request:meta(Meta::[nksip_sipmsg:field()], nksip:request()|nksip:handle()) ->
+    {ok, [{nksip_sipmsg:field(), term()}]} | {error, term()}.
 ```
-Gets the values for a header or headers in a request.
+Gets specific metadata from the request.
+
+See [Metadata Fields](../reference/metadata.md) for a description of available fields.
 
-If `Name` is a single value, a list is returned with the values of all the headers having that name. If it is a list, a list of tuples is returned, where the first element is the header name and the second is the list of values.
+
+### header/2
+```erlang
+nksip_request:header(Name::string()|binary(), nksip:request()|nksip:handle()) -> 
+    {ok, [binary()]} | {error, term()}.
+```
+Gets the all the values for a header.
 
 NkSIP uses only lowercase for header names.
 
 
 ### reply/2
 ```erlang
-nksip_request:reply(nksip:sipreply(), nksip:id()) -> 
-    ok | {error, Error}
-    when Error :: invalid_call | invalid_request | nksip_call_router:sync_error().
+nksip_request:reply(nksip:sipreply(), nksip:handle()) -> 
+    ok | {error, term()}.
 ```
 Sends a reply to a request using a handle.
 

doc/api/responses.md

@@ -4,7 +4,7 @@ This document describes the API NkSIP makes available to extract information fro
 
 Most functions in the API allows two ways to refer to the responses:
 * From a full *response object* (`nksip:response()`). When you use the option `callback` when using the any [request sending function](../reference/sending_functions.md), it is called as `{reply, Code, Response, Call}`. You can use these API functions inside the function call.
-* From a *response handle* (`nksip:id()`). You can get a response handle from a response object using [get_id/1](#get_id1). You can then use the handle to call most functions in this API. 
+* From a *response handle* (`nksip:handle()`). You can get a response handle from a response object using [get_handle/1](#get_handle1). You can then use the handle to call most functions in this API. 
 
 In this case, the API function must contact with the corresponding call process to get the actual response, so you cannot use this method _inside_ the same call process (like in the callback function). This method is useful to refer to the response from a _spawned_ process, avoiding the need to copy the full object. Please notice that the response object may not exists any longer at the moment that the handle is used. Most functions return `error` in this case.
 
@@ -14,86 +14,94 @@ In this case, the API function must contact with the corresponding call process
 
 Function|Description
 ---|---
-[get_id/1](#get_id1)|Grabs a response's handle
+[get_handle/1](#get_handle1)|Grabs a response's handle
 [app_id/1](#app_id1)|Gets then SipApp's _internal name_
 [app_name/1](#app_name1)|Gets the SipApp's _user name_
 [code/1](#method1)|Gets the SIP code of the response
 [body/1](#body1)|Gets the body of the response
 [call_id/1](#call_id1)|Gets the Call-ID header of the response
 [meta/2](#meta2)|Gets specific metadata from the response
+[metas/2](#meta2)|Gets specific metadata from the response
 [header/2](#header2)|Gets the values for a header or headers in a response
 [wait_491/0](#wait_4910)|Sleeps a random time between 2.1 and 4 secs
 
 
 ## Functions List
 
-### get_id/1
+### get_handle/1
 ```erlang
-nksip_response:get_id(nksip:response()|nksip:id()) ->
-    nksip:id().
+nksip_response:get_handle(nksip:response()|nksip:handle()) ->
+    {ok, nksip:handle()} | {error, term()}.
 ```
 Grabs a response's handle.
 
 
 ### app_id/1
 ```erlang
-nksip_response:app_id(nksip:response()|nksip:id()) -> 
-    nksip:app_id().
+nksip_response:app_id(nksip:response()|nksip:handle()) -> 
+    {ok, nksip:app_id()} | {error, term()}.
 ```
 Gets then SipApp's _internal name_.
 
 
 ### app_name/1
 ```erlang
-nksip_response:app_name(nksip:response()|nksip:id()) -> 
-    term().
+nksip_response:app_name(nksip:response()|nksip:handle()) -> 
+    {ok, nksip:app_name()}  | {error, term()}.
 ```
 Gets the SipApp's _user name_
 
 
 ### code/1
 ```erlang
-nksip_response:code(nksip:response()|nksip:id()) ->
-    nksip:sip_code() | error.
+nksip_response:code(nksip:response()|nksip:handle()) ->
+    {ok, nksip:sip_code()} | {error, term()}.
 ```
 Gets the SIP code of the response.
 
 
 ### body/1
 ```erlang
-nksip_response:body(nksip:response()|nksip:id()) ->
-    nksip:body() | error.
+nksip_response:body(nksip:response()|nksip:handle()) ->
+    {ok, nksip:body()} | {error, term()}.
 ```
 Gets the body of the response.
 
 
 ### call_id/1
 ```erlang
-nksip_response:call_id(nksip:response()|nksip:id()) ->
-    nksip:call_id().
+nksip_response:call_id(nksip:response()|nksip:handle()) ->
+    {ok, nksip:call_id()} | {error, term()}.
 ```
 Gets the Call-ID header of the response.
 
 
 ### meta/2
 ```erlang
-nksip_response:meta(Meta::nksip_sipmsg:field()|[nksip_sipmsg:field()], nksip:response()|nksip:id()) ->
-    term() | [{nksip_sipmsg:field(), term()}] | error.
+nksip_response:meta(Meta::nksip_sipmsg:field(), nksip:response()|nksip:handle()) ->
+    {ok, term()} | {error, term()}.
 ```
 Gets specific metadata from the response.
 
 See [Metadata Fields](../reference/metadata.md) for a description of available fields.
-If `Meta` is simple term, its value is returned. If it is a list, it will return a list of tuples, where the first element is the field name and the second is the value.
 
 
-### header/2
+### metas/2
 ```erlang
-nksip_response:header(Name::string()|binary()|[string()|binary()], nksip:response()|nksip:id()) -> 
-    [binary()] | [{binary(), binary()}] | error.
+nksip_response:meta(Meta::[nksip_sipmsg:field()], nksip:response()|nksip:handle()) ->
+    {ok, [{nksip_sipmsg:field(), term()}]} | {error, term()}.
 ```
-Gets the values for a header or headers in a response.
+Gets specific metadata from the response.
+
+See [Metadata Fields](../reference/metadata.md) for a description of available fields.
 
-If `Name` is a single value, a list is returned with the values of all the headers having that name. If it is a list, a list of tuples is returned, where the first element is the header name and the second is the list of values.
+
+### header/2
+```erlang
+nksip_response:header(Name::string()|binary(), nksip:response()|nksip:handle()) -> 
+    {ok, [binary()]} | {error, term()}.
+```
+Gets all the values for a header.
 
 NkSIP uses only lowercase for header names.