Copyright © 2003 - 2004 Enrique Marcote Peña
Version: 0.2, {09 Feb 2003} 11:56:47.
Authors: Enrique Marcote Peña (mpquique_at_users.sourceforge.net) [web site: http://oserl.sourceforge.net/].
Functions for the SMPP base syntax manipulation.
As a guideline, some comments include references to the specific section numbers on [SMPP 5.0].
| decode/2 | Decodes a Value from the head of a Binary using a Type specifier. |
| encode/2 | Encodes a Value using a Type specifier. |
| fit/2 | Fits a type specifier to a given Size. |
decode(Binary, Type) -> {ok, Value, Rest} | {error, Reason}
Decodes a Value from the head of a Binary using a Type specifier. As the Value is decoded a type checking operation is performed, if successful the term {ok, Value, Rest} is returned (where Rest is the remainder of the unused binary), otherwise {error, {type_mismatch, Type, Details}} is returned.
where
Every type is decoded according to [SMPP 5.0].
Binaries, strings and integers are valid constants.
If the binary representation of the Constant is at the head of Binary, the Constant is returned as Value. Otherwise an error is reported.
Checks if Value is a valid Size octets integer. Must be an integer between 0 and math:pow(256, Size) - 1.
An integer of Size octets is taken from the head of the Binary, if not enough bytes an error is reported.
Checks if Value is a valid C-Octet String. A C-Octet String must be NULL_CHARACTER ($\0) terminated.
When a fixed size is given and the Size-th octet on the Binary is the NULL_CHARACTER, a Size - 1 long binary is taken an translated into string using the binary_to_list BIF.
On variable length strings, every octet until the NULL_CHARACTER is taken using the function binary:take_until/3 (common_lib). The result is translated to a list with the BIF binary_to_list. Notice that the resulting Value is always smaller than Size characters long.
Important (Since version 0.2). The base syntax takes care of trailing NULL_CHARACTERs for you so, even you have to count this character when setting the Size field, do not add a trailing NULL_CHARACTER in your c_octet_string values, base_syntax:decode/2 handles NULLs on its own.
As a rule of thumb. Set the Size of your c_octet_string accordingly to SMPP specs. Do not expect decoded c_octet_string values to have a trailing NULL_CHARACTER. This character is automatically removed at decode time.
When a fixed size is given the Value must be exactly 0 or Size characters long. For variable lengths any range between 0 and Size octets is considered to be correct.
Fixed size Octet Strings are decoded pretty much like a C-Octet String, but no terminating NULL_CHARACTER is required.
It's not easy to guess where a variable Octet String ends, in fact this data-type makes sense only if encapsulated inside a TLV. In order to let a TLV recursively decode an inner variable Octet String the following rule applies; if size(Binary) less than Size, the hole Binary is translated to a list (string), otherwise the first Size octets of the Binary are taken.
Every Value in the list must conform the given Type.
To decode a list, a (Size / 256) + 1 octets integer indicating the total number (Num) of values is extracted from the head of the Binary, then a list with Num elements is decoded using the base Type of the list. This list of Values is returned, Num is discarded.
In a composite every field is checked against the corresponding field in the tuple with the types.
Every field in the composite is decoded, one at a time, using the corresponding field in the type descriptor. On anonymous composites (Name = undefined) the returning Value is a tuple built from the individual fields, named composites tuples are translated to a record of type Name.
The Value must conform at least one of the given types.
An union value is decoded using the first type descriptor conformed by the value.
See also: decode_iter/3, decode_list/2, decode_try/2, encode/2, binary:take_until/3.
encode(Value, Type) -> {ok, Binary} | {error, Reason}
Encodes a Value using a Type specifier. Before encoding the value a type checking operation is done, if unsuccessful the term {error, {type_mismatch, Type, Details}} is returned.
where
Every type is encoded according to [SMPP 5.0].
Value must be identical to given constant. Binaries, strings and integers are valid constants.
The Value is directly encoded into a binary.
Checks if Value is a valid Size octets integer. Must be an integer between 0 and math:pow(256, Size) - 1.
The integer is translated into binary using Size octets.
Checks if Value is a valid C-Octet String: Just a string with Size - 1 characters. Notice that C-Octet Strings (erlang) Values should not include the terminating NULL_CHARACTER ($\0), it is automatically included by the encode function.
When a fixed size is given, the Value (having no terminating NULL_CHARACTER) must be exactly 0 or Size - 1 characters long. For variable lengths any range between 0 and Size - 1 octets is considered to be correct.
The string is translated into binary using the BIF list_to_binary , thus one octet per character.
Important (Since version 0.2). The base syntax takes care of trailing NULL_CHARACTERs for you so, even you have to count this character when setting the Size field, do not add a trailing NULL_CHARACTER in your c_octet_string values, base_syntax:encode/2 handles NULLs on its own.
As a rule of thumb. Set the Size of your c_octet_string accordingly to SMPP specs. Do not add the trailing NULL_CHARACTER to the values of the c_octet_string parameters. The NULL_CHARACTER is automatically included at encode time.
When a fixed size is given the Value must be exactly 0 or Size characters long. For variable lengths any range between 0 and Size octets is considered to be correct.
An string is translated into binary using the BIF list_to_binary , thus one octet per character.
Every Value in the list must conform the given Type.
To encode a list, a (Size / 256) + 1 octets integer indicating the total number of values is prepended to the list of encoded values. Every element on the list is encoded (and appended) according to the given type.
In a composite every field is checked against the corresponding field in the tuple with the types.
Every field in the composite is encoded using the corresponding field in the type descriptor. The global result is obtained concatenating every encoded field in the same order of appearance in the composite. On named composites the identifier of the record is discarded (not encoded).
The Value must conform at least one of the given types.
An union value is encoded using the first type descriptor conformed by the value.
See also: decode/2, encode_iter/2, encode_list/2, encode_try/2.
fit(Type, NewSize::Size) -> NewType
Fits a type specifier to a given Size.
where
This function was mainly conceived to adapt the type specification to a TLV parameter definition.