This is a near accurate description but there are 2 things i noticed:


1) the reply is allowed to contain any headers not just the ones listed, the unicast command for instance has Socket-Mode and Control headers in addition to the Content-Type: command/reply.  The change was just for the sake of the guy who wanted to see the job uuid as a header and it should not violate that rule.

2) There cannot actually be more than one Content-Length, what you are actually seeing is an event inside the packet that in turn has it's own payload.


What I do when I make a parser for the protocol is read 1 packet by reading all the headers until i see 2 CR then i make a hash out of all of the headers and see if any of them was "Content-Type".  If so I read that many bytes of body being sure to do careful code to actually make sure I read the whole body.  So if I was told the content-length was 356 bytes and my read of 356 only yielded 300 bytes i would continue to try to read 56 bytes untill I had accumulated exactly 356. 

This should be the only main rule about the protocol, what you describe about the possible replies is all accurate but it should not be considered in the parsing of the packet apart from Content-Length.

In the case of an event, then the payload will be an entire serialized event, xml or plain text depending on preference.

Thanks for putting this together it's looking good.



On Fri, Jun 6, 2008 at 1:55 PM, UV <uv@talknet.com.au> wrote:

Before this last change, the event_socket responses were structured in a manner that could have been generalized as follows:

1.       Command responses will always have the following structure:

Content-Type: <auth/request | command/reply | api/response | text/event-xml | log/data><LF>

[Reply-Text: <+OK | -ERR> <info payload><LF>]

[Content-Length: <info payload length><LF>]

<LF>

[<info payload><LF>]

2.       If Content-Length is defined, then there's an additional info payload after the terminating <LF> at the byte length of <info payload length>. There can be more than one Content-Length in a single event meaning there's additional payload for this event.

3.       Command response structure will be determined by the Content-Type:

    1. auth/request

                                                               i.      This response is self initiated upon creation of an event_socket connection and will expect only an auth command to follow.

                                                              ii.      Will only have Content-Type field and will be waiting for authentication for 1 (?) minute

    1. command/reply

                                                               i.      This response will follow the bgapi command.

                                                              ii.      The Content-Type field will be before a Reply-Text field that will appear with +OK or –ERR response

                                                            iii.      When that job ended (in a request), a "Job-UUID:" label will appear in the BACKGROUND_JOB event. That event's +OK <uuid> will correspond with all session's events Unique-ID: <uuid>.

                                                            iv.      All following events concerning this session will have that same Unique-ID

    1. api/response

                                                               i.      All Event_socket commands (except bgapi) will be immediately answered by this response before any other response.

                                                              ii.      A Content-Type first

                                                            iii.      Content-Length second

                                                            iv.      The info-payload will include the information

    1. text/event-xml

                                                               i.      This response is for system-initiated events.

                                                              ii.      The Content-Length field will appear first, then the Content-Type field.

                                                            iii.      The XML/Text will appear in the info-payload data.

    1. log/data

                                                               i.      Once an Event_socket is subscribed for log information, this response will be it.

                                                              ii.      The Content-Type field will appear first, then the Content-Length field.

                                                            iii.      The log info will appear in the info-payload data as plain text

 

This last change invites an exception for the [Reply-Text: <+OK | -ERR> <info payload><LF>] policy in a way that requires more parsing rules.

To preserve consistency, I would recommend these alternatives:

  1. Not make that change (I think it's too late for that)
  2. Make that change for all Reply-Text responses in a way that after the <+OK | -ERR> there's always a <LF>
  3. Keep it as an exception and live with it

 

Although this change breaks our implementation, we'd be happy to change it once there's a decision regardless of what it is.

 

Disclaimer:

The info here is an extract from our _*INTERNAL*_DOCUMENTATION_ representing our limited knowledge, experience and understanding of the complex FS internals. Once this documentation proves not to be a total BS and of some true substance, it shall be wikified for the general good.

 

"If there are two ways to take something I've said and one of them hurts your feelings.....I meant the other one." J

 

 

From: freeswitch-dev-bounces@lists.freeswitch.org [mailto:freeswitch-dev-bounces@lists.freeswitch.org] On Behalf Of Anthony Minessale
Sent: Saturday, June 07, 2008 2:58 AM


To: freeswitch-dev@lists.freeswitch.org
Subject: Re: [Freeswitch-dev] Could we have Job-UUID in a separate line?

 

it's already done.

On Fri, Jun 6, 2008 at 11:22 AM, Michael Collins <mcollins@fcnetwork.com> wrote:

Sounds reasonable to me.  Also, since I don't hear anyone yelling and screaming about how this change will break their software I think you're safe to make the change w/o pissing off anyone.

 

-MC

 

From: freeswitch-dev-bounces@lists.freeswitch.org [mailto:freeswitch-dev-bounces@lists.freeswitch.org] On Behalf Of Anthony Minessale
Sent: Friday, June 06, 2008 9:14 AM

Subject: Re: [Freeswitch-dev] Could we have Job-UUID in a separate line?

 

i'll let both work
it's own header and part of the text

On Thu, Jun 5, 2008 at 4:46 PM, Michael Collins <mcollins@fcnetwork.com> wrote:

This might qualify as an "interface change" so before making the switch you should probably ask around and see if anyone has software that would break if this change were implemented.

 

Johny: also, since it is open source you could always add the "\n" yourself and recompile.  If you haven't already tried that you might want to take it for a test drive and see if it really does what you want it to do.

-MC

 

From: freeswitch-dev-bounces@lists.freeswitch.org [mailto:freeswitch-dev-bounces@lists.freeswitch.org] On Behalf Of Johny Kadarisman
Sent: Thursday, June 05, 2008 2:38 PM
To: freeswitch-dev@lists.freeswitch.org
Subject: [Freeswitch-dev] Could we have Job-UUID in a separate line?

 

Could we have Job-UUID as a separate fields. It can be parse easily, but its event easier to have it just like others response fields.

so in bgapi reply, we will get:

Content-Type: command/reply
Reply-Text: +OK
Job-UUID: e0d64b14-3327-11dd-96f6-6fa9e94f364f


Johny K.


_______________________________________________
Freeswitch-dev mailing list
Freeswitch-dev@lists.freeswitch.org
http://lists.freeswitch.org/mailman/listinfo/freeswitch-dev
UNSUBSCRIBE:http://lists.freeswitch.org/mailman/options/freeswitch-dev
http://www.freeswitch.org




--
Anthony Minessale II

FreeSWITCH http://www.freeswitch.org/
ClueCon http://www.cluecon.com/

AIM: anthm
MSN:anthony_minessale@hotmail.com
GTALK/JABBER/PAYPAL:anthony.minessale@gmail.com
IRC: irc.freenode.net #freeswitch

FreeSWITCH Developer Conference
sip:888@conference.freeswitch.org
iax:guest@conference.freeswitch.org/888
googletalk:conf+888@conference.freeswitch.org
pstn:213-799-1400


_______________________________________________
Freeswitch-dev mailing list
Freeswitch-dev@lists.freeswitch.org
http://lists.freeswitch.org/mailman/listinfo/freeswitch-dev
UNSUBSCRIBE:http://lists.freeswitch.org/mailman/options/freeswitch-dev
http://www.freeswitch.org




--
Anthony Minessale II

FreeSWITCH http://www.freeswitch.org/
ClueCon http://www.cluecon.com/

AIM: anthm
MSN:anthony_minessale@hotmail.com
GTALK/JABBER/PAYPAL:anthony.minessale@gmail.com
IRC: irc.freenode.net #freeswitch

FreeSWITCH Developer Conference
sip:888@conference.freeswitch.org
iax:guest@conference.freeswitch.org/888
googletalk:conf+888@conference.freeswitch.org
pstn:213-799-1400


_______________________________________________
Freeswitch-dev mailing list
Freeswitch-dev@lists.freeswitch.org
http://lists.freeswitch.org/mailman/listinfo/freeswitch-dev
UNSUBSCRIBE:http://lists.freeswitch.org/mailman/options/freeswitch-dev
http://www.freeswitch.org




--
Anthony Minessale II

FreeSWITCH http://www.freeswitch.org/
ClueCon http://www.cluecon.com/

AIM: anthm
MSN:anthony_minessale@hotmail.com
GTALK/JABBER/PAYPAL:anthony.minessale@gmail.com
IRC: irc.freenode.net #freeswitch

FreeSWITCH Developer Conference
sip:888@conference.freeswitch.org
iax:guest@conference.freeswitch.org/888
googletalk:conf+888@conference.freeswitch.org
pstn:213-799-1400