You are here: CSP Developer’s Guide: Internet Protocol > 5 Session-Initiation Protocol (SIP) Software > Subject Header Field Access
Overview
This feature allows host application developers to provide read and write access to the Subject header field.
Read access allows the host application to receive the content of the Subject header-field if it is present in the inbound INVITE message. In the SIP stack on the CSP, you can configure whether you want to report the Subject header field.
Write access allows the host application to fill information into the Subject header field of the outbound INVITE message.
Important! Reading or writing the Subject header field works only if the subject field is less than 255 bytes.
Pertinent Specification
RFC 2543/3261
Description
Subject Header Field - Read Access
This section describes the Read Access portion of this feature.
The SIP software reports the Subject header field if it is present in the inbound INVITE message - in a raw, null-terminated ASCII format from the CSP to the host application.
The reporting provided with this feature is within the context of the SIP INVITE message and corresponding Request for Service with Data (0x002D) messages only.
The Subject header field is reported using NPDI TLV, the SIP Subject TLV (0x295B) in Request for Service with Data (0x002D) message or in Subsequent Data - PPL Event Indication message. The SIP Subject TLV will be used within the NPDI Universal ICB (0x0033).
Process
The following assumes that the Subject header-field reporting is turned on:
When the CSP receives a SIP INVITE that includes the Subject header-field, the CSP sends the SIP Subject TLV (0x295B) to the host application in Request for Service with Data message or in one of the subsequent PPL Event Indications (in case the Request for Service with Data exceeds 320 bytes).
The SIP Subject TLV, as any other TLVs except Subsequent Information Status TLV (0x2953), will be fully present in any one of the API messages.
The Request for Service with Data message and the PPL Event Indications message shown in the call flow below include the Subsequent Information Status TLV.
The SIP Subject TLV will be present in any one of the messages from the CSP to the host application provided the follows is in place:
• reporting is turned on
• the inbound INVITE message has a Subject header
Figure 5-5 Read Access
Subject Header Field - Write Access
This section describes the Write Access portion of this feature. Refer to the API Reference for the specific formats of the API changes to support this functionality.
The write access is within the context of SIP INVITE and corresponding Route Control (0x00E8) and Outseize Control (0x002C) messages as described below.
The SIP software allows the host application to fill the Subject header-field of the outbound INVITE message using the NPDI TLV, SIP Subject (0x295B).
This TLV can go in the following messages:
• Route Control message (0x00E8)
• Outseize Control (0x002C)
• Subsequent Data PPL Event Request message (0x0044) - if the Route Control or Outseize Control message exceed 512 bytes. Refer to Segmented Call Request.
The SIP Subject TLV is used within the NPDI Universal ICB (0x0033).
Process
If the host application is going to fill in the Subject header field, then the SIP Subject TLV should be present in either the Outseize or Route Control message or in any of the PPL Event Request messages for subsequent data (in the case where more data in the Outseize/Route Control message cannot be packed in a single message.) The PPL Event Request has component 0x00A7 with event 0x0023.
The SIP Subject TLV has to be present (not broken up) in any one of these API messages, as any other NPDI TLVs used with the Outseize/Route Control message except the Subsequent Information Status TLV. The Subsequent Information Status TLV must be present in the initial Outseize/Route Control message and subsequent PPL Event Request messages.
Call Flow
The SIP software allows the host application to send NPDI data that could not be packed into the Route Control or Outseize Control messages (due to 512 bytes message size limitation), in a PPL Event Request.
The Route Control and Outseize Control messages and the subsequent PPL Event Request message must contain the Subsequent Information Status TLV (0x2953).
The CSP uses this TLV to validate the message sequence and to identify the last message in the sequence. Any other TLVs have to fully contained in one of the API messages.
Call Flow
In the figure below, the Route Control or Outseize Control message and the PPL Event Request message include the Subsequent Information Status TLV. The call flow steps are described below.
Figure 5-6 Write Access
Call Flow Steps
1. The host application sends the Route Control or Outseize Control message with the Subsequent Information Status TLV filled in.
2. As soon as the SIP UA receives the Call Request from the L4_CH, it sends out a PPL Event Indication message of event type (0x0025). This indication is sent out only for the Route Control or Outseize Control message having the Subsequent Information Status TLV with correct data. This PPL Event Indication message will report the following to the host application:
• The channel AIB in the indication will have the local Span Channel used, so the host application could use this same addressing in the Subsequent Data PPL Event Requests.
• The channel reported in the indication will be in the Call Setup status.
• The sequence number of the Route Control or Outseize Control message that initiated this indication. This indication is reported using the Message Header Information TLV (0x0014) embedded in the Generic PPL Data ICB (0x1E).
This step is required for the host application to map the PPL Event Indication to the corresponding Route Control or Outseize Control message.
• The SIP UA is ready to accept more data.
3. The TLVs received from Route Control or Outseize Control messages (with Subsequent Information TLV) and the subsequent PPL Event Request messages are stored in a buffer in the call_info data structure. After the final message is received, the SIP UA sends out a PPL Event Indication message of event type (0x0026), informing the host application that all data have been received. The TLVs stored in the buffer are validated, extracted and stored in the call_info data structure, which is used to create the Invite message. The TLVs received from Route Control or Outseize Control message, without Subsequent Information TLV, are not buffered.
4. If any one of the TLVs received is has incorrect NPDI data (in the NPDI TLVs), then the Route Control or Outseize Control message is NACKed with the status 0x1304.
5. If the received subsequent PPL Event Request message does not have the Subsequent Information Status TLV, then the Route Control or Outseize Control message is NACKed with status 0x1314.
6. If the subsequent PPL Event Request message received has a wrong sequence number in the Subsequent Information Status TLV, then the Route Control or Outseize Control message is NACKed with status 0x1315.
7. The SIP UA PPL starts a timer with an interval of 10 seconds and waits for a subsequent PPL Event Request message. If the timer expires the Route Control/Outseize Control message is NACKed with status 0x1316.
8. When a Release Channel message is received when waiting for a subsequent PPL Event Request message, the channel is released immediately and the Route Control or Outseize Control message is NACKed with status 0x1304.
Response Status
The following Response Status support this feature.
Table 5-4 Response Status
Response Status |
Name |
Description |
---|---|---|
0x1303 |
Invalid PPL Event |
Used in Route Control and PPL Event Request messages. |
0x1304 |
Invalid Data |
Used in Route Control and PPL Event Request messages. |
0x130E
|
TLV missing |
Subsequent Information Status TLV is missing in the PPL Event Request message. |
0x130F
|
Incorrect sequence number |
The Subsequent Information Status TLV has incorrect sequence number in the Route Control / Outseize Control or subsequent PPL Event Request message. |
0x1310
|
Timed out |
Timed out waiting for subsequent PPL Event Request message from the host application. Reported by Route Control or Outseize Control message. |
API Messages
• Outseize Control (0x002C)
• Route Control (0x00E8)
• PPL Event Indication (0x0044)
• PPL Event Request (0x0043)
Configuring
You can configure the SIP software to report the Subject header field. By default it is turned off.
You enable this feature by setting a bit mask during the SIP configuration.
You use the existing SIP Message Information Mask TLV (0x027F) in the VoIP Protocol Configure (0x00EE) message to enable or disable this feature.
Refer to the API Reference.
Samples
The following samples include inbound and outbound SIP messages and the associated API messages.
Inbound Messages
Inbound SIP INVITE message and Request for Service with Data Message
INVITE sip:1000@135.119.55.40:5060 SIP/2.0
Via: SIP/2.0/UDP 135.119.55.37:5060
From: sipp <sip:7000@135.119.55.37:5060>;tag=1;epid=d825335aae
To: sut <sip:1000@135.119.55.40:5060>
Call-ID: 1-4180@135.119.55.37
CSeq: 1 INVITE
Contact: <sip:7000@135.119.55.37:5060>
Max-Forwards: 70
Subject: F-0624 Subject Header Now Supported
Remote-Party-ID: "John Doe" <sip:jdoe@foo.com>;party=calling;id-type=subscriber;privacy=full;screen=yes
RPID-Privacy: full
Content-Type: applicatoin/sdp
Content-Length: 136
v=0
s=-
c=IN IP4 127.0.0.1
t=0 0
m=audio 10000 RTP/AVP 0
a=rtpmap:0 PCMU/8000
X->H
[00 ee 00 2d 00 00 01 00 01 0d 03 00 64 0e 00 33 01 03 00 33
00 da 00 14 27 4e 00 02 00 05 27 7e 00 03 08 00 00 29
19 00 05 31 30 30 30 00 29 1b 00 0e 31 33 35 2e 31 31
39 2e 35 35 2e 34 30 00 29 1c 00 04 00 00 13 c4 29 23
00 05 37 30 30 30 00 29 25 00 0e 31 33 35 2e 31 31 39
2e 35 35 2e 33 37 00 29 26 00 04 00 00 13 c4 29 2d 00
05 37 30 30 30 00 29 2f 00 0e 31 33 35 2e 31 31 39 2e
35 35 2e 33 37 00 29 30 00 04 00 00 13 c4 29 33 00 01
01 27 18 00 07 02 00 00 00 04 70 00 27 17 00 05 02 00
04 10 00 27 94 00 04 7f 00 00 01 27 95 00 04 00 00 27
10 27 b0 00 02 00 02 27 b1 00 02 00 04 29 16 00 01 01
29 5b 00 24 46 2d 30 36 32 34 20 53 75 62 6a 65 63 74
20 48 65 61 64 65 72 20 4e 6f 77 20 53 75 70 70 6f 72
74 65 64 00
Inbound SIP INVITE and Request for Service message with Subsequent Information TLV
In the following sample, the Request for Service with Data message uses the Subsequent Information TLV and the PPL Event Indication message that carries the Subject Head Field with 250 Bytes of Data.
INVITE sip:1000@135.119.55.40:5060 SIP/2.0
Via: SIP/2.0/UDP 135.119.55.37:5060
From: sipp <sip:7000@135.119.55.37:5060>;tag=1;epid=d825335aae
To: sut <sip:1000@135.119.55.40:5060>
Call-ID: 1-3840@135.119.55.37
CSeq: 1 INVITE
Contact: <sip:7000@135.119.55.37:5060>
Max-Forwards: 70
Subject: F-0624 Subject Header Now Supported
But It Must Be A Longer To Enable Reported Within The PPL Event Indication. This is a test to find out how many if the CSP can handle 250 bytes.!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
Remote-Party-ID: "John Doe" <sip:jdoe@foo.com>;party=calling;id-type=subscriber;privacy=full;screen=yes
RPID-Privacy: full
Content-Type: applicatoin/sdp
Content-Length: 136
v=0
o=user1 53655765 2353687637 IN IP4 127.0.0.1
s=-
c=IN IP4 127.0.0.1
t=0 0
m=audio 10000 RTP/AVP 0
a=rtpmap:0 PCMU/8000]
X->H
[00 cc 00 2d 00 04 01 00 01 0d 03 00 64 10 00 33 01 03 00 33
00 b8 00 14 27 4e 00 02 00 05 27 7e 00 03 08 00 00 29
19 00 05 31 30 30 30 00 29 1b 00 0e 31 33 35 2e 31 31
39 2e 35 35 2e 34 30 00 29 1c 00 04 00 00 13 c4 29 23
00 05 37 30 30 30 00 29 25 00 0e 31 33 35 2e 31 31 39
2e 35 35 2e 33 37 00 29 26 00 04 00 00 13 c4 29 2d 00
05 37 30 30 30 00 29 2f 00 0e 31 33 35 2e 31 31 39 2e
35 35 2e 33 37 00 29 30 00 04 00 00 13 c4 29 33 00 01
01 27 18 00 07 02 00 00 00 04 70 00 27 17 00 05 02 00
04 10 00 27 94 00 04 7f 00 00 01 27 95 00 04 00 00 27
10 27 b0 00 02 00 02 27 b1 00 02 00 04 29 16 00 01 01
29 53 00 02 01 00]
X->H
[01 1d 00 43 00 31 01 00 01 0d 03 00 64 10 00 a7 00 23 01 03
00 33 01 07 00 02 29 53 00 02 02 01 29 5b 00 fb 46 2d
30 36 32 34 20 53 75 62 6a 65 63 74 20 48 65 61 64 65
72 20 4e 6f 77 20 53 75 70 70 6f 72 74 65 64 20 42 75
74 20 49 74 20 4d 75 73 74 20 42 65 20 41 6c 6c 6c 6c
6c 6c 6c 6c 6c 6c 6c 6c 6c 6c 6c 6c 6c 6c 6c 6c 6c 6c
6c 6c 6c 6f 74 20 4c 6f 6e 67 65 72 20 54 6f 20 45 6e
61 62 6c 65 20 52 65 70 6f 72 74 65 64 20 57 69 74 68
69 6e 20 54 68 65 20 50 50 4c 20 45 76 65 6e 74 20 49
6e 64 69 63 61 74 69 6f 6e 2e 20 54 68 69 73 20 69 73
20 61 20 74 65 73 74 20 74 6f 20 66 69 6e 64 20 6f 75
74 20 68 6f 77 20 6d 61 6e 79 20 69 66 20 74 68 65 20
43 53 50 20 63 61 6e 20 68 61 6e 64 6c 65 20 32 35 30
20 62 79 74 65 73 2e 21 21 21 21 21 21 21 21 21 21 21
21 21 21 21 21 21 21 21 21 21 21 21 21 21 21 21 21 21
21 21 21 21 21 21 21 21 21 21 21 21 21 21 00]
Outbound Messages
The following are several Outseize and Route Control messages followed by the SIP INVITE message.
Outseize Control Message with the Subject Header TLV
H->X
[01 4f 00 2c 00 00 ff 00 01 0d 03 00 64 00 01 03 00 33
01 3d 00 05 29 19 00 05 32 30 30 30 00 27 7e 00 03 08
01 00 29 ff 00 23 2a 0e 00 04 87 77 37 2b 2a 01 00 17
2a 03 00 01 00 2a 07 00 04 00 00 5b 90 2a 02 00 06 2a
08 00 02 00 12 29 16 00 01 01 29 5b 00 fb 46 2d 30 36
32 34 20 53 75 62 6a 65 63 74 20 48 65 61 64 65 72 20
4e 6f 77 20 53 75 70 70 6f 72 74 65 64 20 42 75 74 20
49 74 20 4d 75 73 74 20 42 65 20 41 6c 6c 6c 6c 6c 6c
6c 6c 6c 6c 6c 6c 6c 6c 6c 6c 6c 6c 6c 6c 6c 6c 6c 6c
6c 6f 74 20 4c 6f 6e 67 65 72 20 54 6f 20 45 6e 61 62
6c 65 20 52 65 70 6f 72 74 65 64 20 57 69 74 68 69 6e
20 54 68 65 20 50 50 4c 20 45 76 65 6e 74 20 49 6e 64
69 63 61 74 69 6f 6e 2e 20 54 68 69 73 20 69 73 20 61
20 74 65 73 74 20 74 6f 20 66 69 6e 64 20 6f 75 74 20
68 6f 77 20 6d 61 6e 79 20 69 66 20 74 68 65 20 43 53
50 20 63 61 6e 20 68 61 6e 64 6c 65 20 32 35 30 20 62
79 74 65 73 2e 21 21 21 21 21 21 21 21 21 21 21 21 21
21 21 21 21 21 21 21 21 21 21 21 21 21 21 21 21 21 21
21 21 21 21 21 21 21 21 21 21 21 21 00]
Route Control Message with the Subject Header TLV
H->X
[01 76 00 e8 00 00 ff 00 01 29 02 ff fe 02 03 00 1e 00
23 00 06 00 13 00 02 00 08 00 08 00 02 00 65 00 0f 00
01 0b 01 00 00 01 11 01 01 00 01 01 00 65 00 02 00 00
03 00 33 01 3d 00 05 29 19 00 05 32 30 30 30 00 27 7e
00 03 08 01 00 29 ff 00 23 2a 0e 00 04 87 77 37 2b 2a
01 00 17 2a 03 00 01 00 2a 07 00 04 00 00 5b 90 2a 02
00 06 2a 08 00 02 00 12 29 16 00 01 01
29 5b 00 fb 46
2d 30 36 32 34 20 53 75 62 6a 65 63 74 20 48 65 61 64
65 72 20 4e 6f 77 20 53 75 70 70 6f 72 74 65 64 20 42
75 74 20 49 74 20 4d 75 73 74 20 42 65 20 41 6c 6c 6c
6c 6c 6c 6c 6c 6c 6c 6c 6c 6c 6c 6c 6c 6c 6c 6c 6c 6c
6c 6c 6c 6c 6f 74 20 4c 6f 6e 67 65 72 20 54 6f 20 45
6e 61 62 6c 65 20 52 65 70 6f 72 74 65 64 20 57 69 74
68 69 6e 20 54 68 65 20 50 50 4c 20 45 76 65 6e 74 20
49 6e 64 69 63 61 74 69 6f 6e 2e 20 54 68 69 73 20 69
73 20 61 20 74 65 73 74 20 74 6f 20 66 69 6e 64 20 6f
75 74 20 68 6f 77 20 6d 61 6e 79 20 69 66 20 74 68 65
20 43 53 50 20 63 61 6e 20 68 61 6e 64 6c 65 20 32 35
30 20 62 79 74 65 73 2e 21 21 21 21 21 21 21 21 21 21
21 21 21 21 21 21 21 21 21 21 21 21 21 21 21 21 21 21
21 21 21 21 21 21 21 21 21 21 21 21 21 21 21 00]
Outseize Control Message that contains TLV 0x2953 (NPDI Subsequent Information Status)
H->X
[00 56 00 2c 00 00 ff 00 01 0d 03 00 64 00 01 03 00 33
00 44 00 05 29 19 00 05 32 30 30 30 00 27 7e 00 03 08
01 00 29 ff 00 23 2a 0e 00 04 87 77 37 2b 2a 01 00 17
2a 03 00 01 00 2a 07 00 04 00 00 5b 90 2a 02 00 06 2a
08 00 02 00 12 29 16 00 01 01 29 53 00 02 01 00]
PPL Event Indication that Is reported to the host application carrying the TLV 0x0014 (Message Header Information)
X->H
[00 1d 00 43 00 33 01 00 01 0d 03 00 64 00 00 a7 00 25 01 02
1e 0a 01 00 14 00 04 00 2c 00 00]
PPL Event Request Message that contains TLV 0x2953 and TLV 0x295B (SIP Subject Header) with 250 Bytes
H->X
[01 1d 00 44 00 00 ff 00 01 0d 03 00 64 00 00 a7 00 23
01 03 00 33 01 07 00 02 29 53 00 02 02 01 29 5b 00 fb
46 2d 30 36 32 34 20 53 75 62 6a 65 63 74 20 48 65 61
64 65 72 20 4e 6f 77 20 53 75 70 70 6f 72 74 65 64 20
42 75 74 20 49 74 20 4d 75 73 74 20 42 65 20 41 6c 6c
6c 6c 6c 6c 6c 6c 6c 6c 6c 6c 6c 6c 6c 6c 6c 6c 6c 6c
6c 6c 6c 6c 6c 6f 74 20 4c 6f 6e 67 65 72 20 54 6f 20
45 6e 61 62 6c 65 20 52 65 70 6f 72 74 65 64 20 57 69
74 68 69 6e 20 54 68 65 20 50 50 4c 20 45 76 65 6e 74
20 49 6e 64 69 63 61 74 69 6f 6e 2e 20 54 68 69 73 20
69 73 20 61 20 74 65 73 74 20 74 6f 20 66 69 6e 64 20
6f 75 74 20 68 6f 77 20 6d 61 6e 79 20 69 66 20 74 68
65 20 43 53 50 20 63 61 6e 20 68 61 6e 64 6c 65 20 32
35 30 20 62 79 74 65 73 2e 21 21 21 21 21 21 21 21 21
21 21 21 21 21 21 21 21 21 21 21 21 21 21 21 21 21 21
21 21 21 21 21 21 21 21 21 21 21 21 21 21 21 21 00]
Route Control Message that contains TLV 0x2953 (NPDI Subsequent Information Status)
H->X
[00 7d 00 e8 00 00 ff 00 01 29 02 ff fe 02 03 00 1e 00
23 00 06 00 13 00 02 00 08 00 08 00 02 00 65 00 0f 00
01 0b 01 00 00 01 11 01 01 00 01 01 00 65 00 02 00 00
03 00 33 00 44 00 05 29 19 00 05 32 30 30 30 00 27 7e
00 03 08 01 00 29 ff 00 23 2a 0e 00 04 87 77 37 2b 2a
01 00 17 2a 03 00 01 00 2a 07 00 04 00 00 5b 90 2a 02
00 06 2a 08 00 02 00 12 29 16 00 01 01 29 53 00 02 01
00]
PPL Event Indication that Is reported to the host application carrying the TLV 0x0014 (Message Header Information)
X->H
[00 1d 00 43 00 36 01 00 01 0d 03 00 64 13 00 a7 00 25 01 02
1e 0a 01 00 14 00 04 00 e8 00 00]
PPL Event Request Message that contains TLV 0x2953 and TLV 0x295B (SIP Subject Header) with 250 Bytes
H->X
[01 1d 00 44 00 00 ff 00 01 0d 03 00 64 13 00 a7 00 23
01 03 00 33 01 07 00 02 29 53 00 02 02 01 29 5b 00 fb
46 2d 30 36 32 34 20 53 75 62 6a 65 63 74 20 48 65 61
64 65 72 20 4e 6f 77 20 53 75 70 70 6f 72 74 65 64 20
42 75 74 20 49 74 20 4d 75 73 74 20 42 65 20 41 6c 6c
6c 6c 6c 6c 6c 6c 6c 6c 6c 6c 6c 6c 6c 6c 6c 6c 6c 6c
6c 6c 6c 6c 6c 6f 74 20 4c 6f 6e 67 65 72 20 54 6f 20
45 6e 61 62 6c 65 20 52 65 70 6f 72 74 65 64 20 57 69
74 68 69 6e 20 54 68 65 20 50 50 4c 20 45 76 65 6e 74
20 49 6e 64 69 63 61 74 69 6f 6e 2e 20 54 68 69 73 20
69 73 20 61 20 74 65 73 74 20 74 6f 20 66 69 6e 64 20
6f 75 74 20 68 6f 77 20 6d 61 6e 79 20 69 66 20 74 68
65 20 43 53 50 20 63 61 6e 20 68 61 6e 64 6c 65 20 32
35 30 20 62 79 74 65 73 2e 21 21 21 21 21 21 21 21 21
21 21 21 21 21 21 21 21 21 21 21 21 21 21 21 21 21 21
21 21 21 21 21 21 21 21 21 21 21 21 21 21 21 21 00
INVITE Message
The following INVITE message is generated with 250 bytes from the Route Control or Outseize Control message:
INVITE sip:2000@135.119.55.61:5060 SIP/2.0
Via: SIP/2.0/UDP 135.119.55.40
To: 2000<sip:2000@135.119.55.61:5060>
From: 00000000<sip:00000000@135.119.55.40:5060>;tag=39173412d3c
Call-ID: EXCEL-CSP1.27.77116.230@135.119.55.40
Contact: 00000000<sip:00000000@135.119.55.40:5060>
User-Agent: Excel_CSP/82.30.171
Supported: timer
Session-Expires: 1800
Min-SE: 300
CSeq: 1 INVITE
Subject: F-0624 Subject Header Now Supported But It Must Be Alllllllllllllllllllllllllot Longer To Enable Reported Within The PPL Event Indication. This is a test to find out if the CSP can handle 250 bytes.!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
Content-Type: application/sdp
Content-Length: 124
v=0
o=sip 1117807282 1117807282 IN IP4 135.119.55.40
s=SIP_Call
c=IN IP4 135.119.55.43
t=0 0
m=audio 23440 RTP/AVP 18