This page describes the liblinphone API implementation to support the reason header usage as defined in the RFC3326 The Reason Header Field for the Session Initiation Protocol (SIP).
Reason: SIP ;cause=200 ;text="Call completed elsewhere"
Reason: Q.850; cause=18; text= "no user responding"
Throughout this document, we will call a frequent error or usual error , an error that is already defined by this enum and whose value is different from the LinphoneReasonUnknown value.
Internally, the mapping of these errors with the associated protocol code error_code_reason_map_t error_code_reason_map, and the mapping with the associated description sentence const char *linphone_reason_to_string(LinphoneReason err) enables the functions const char *linphone_reason_to_string(LinphoneReason err), and int linphone_reason_to_error_code(LinphoneReason reason) respectively to find the error explanation sentence and the error protocol code based on the LinphoneReason enumerated above.
On the other hand, the function LinphoneReason linphone_error_code_to_reason(int err) returns the LinphoneReason based on the protocol error code, if this error is a frequent error.
Every objects inherit from belle_sip_object_t to allow memory usage tracking. It is used by linphone_error_info_ref and linphone_error_info_unref.
An error and reason enum of the most frequent errors for the SIP protocol. To specify a reason different from the predefined ones, this field must be set to LinphoneReasonUnknown.
the procotol name used, usually SIP.
the error code associated. This can be easily inferred from the LinphoneReason, provided that it is not LinphoneReasonUnknown nor an unusual error, using a call to linphone_reason_to_error_code.
The error text describing it. If it is a frequent error, it has already been defined : as a consequence, it can be easily retrieved with linphone_reason_to_string.
The warning header fied as defined by the RFC3261, if it exists. This is not a mandatory field and can be set to NULL.
This holds the concatenation of all the reason header information available in order to make a valid reason header. This field is used internally and is not supposed to be used elsewhere.
A pointer to another LinphoneErrorInfo structure it there is several errors to notify in one message. There is usually at most 2 errors notified. Unless it is explicitely given another value with a call to inphone_error_info_set_sub_error_info, this field is set to NULL by linphone_error_info_set.
In order to terminate or decline a call with a reason header, a LinphoneErrorInfo object has to be instanciated and all the necessary fields must be defined beforehand. The memory used by this object must be freed when the object is no longer used.
To defined all the fields of a LinphoneErrorInfo object (except the pointer sub_ei): void linphone_error_info_set(LinphoneErrorInfo *ei, const char *protocol, LinphoneReason reason, int code, const char *status_string, const char *warning); Before defining the appropriate fields, this functions sets to NULL all the structure's pointers.
In order to use a reason header, a LinphoneErrorInfo object has to be instanciated with a call to linphone_factory_create_error_info and the fields must be defined with linphone_error_info_set. The warning pointer can be set to NULL if not used.
The LinphoneErrorInfo ei is then mapped to the SIP response code and status phrase. In order to specify a Reason header in the response, the LinphoneErrorInfo must contain a "sub" error info object describing the Reason header content (set by linphone_error_info_set_sub_error_info()).
For each LinphoneErrorInfo created, a call to oid linphone_error_info_unref(LinphoneErrorInfo *ei) allows to free the allocated memory.
The function const LinphoneErrorInfo *linphone_call_get_error_info(const LinphoneCall *call) returns a pointer on the reason header of call which allows to get the error information on a call declined or terminated. If an outgoing call is declined by the remote party, and the decline response contains a Reason header, a sub LinphoneErrorInfo will be attached to the returned LinphoneErrorInfo.
If knowing the cause is enough, and the other fields are not needed, one can simply use : LinphoneReason linphone_call_get_reason(const LinphoneCall *call).