AIMCC Technote 8
Custom Session
Q: What is a custom session?
A: A custom session is a type of secondary session for sending arbitrary data. Applications/plugins choose the mode of communication and the data format.
Q: What custom session modes are available?
A:
- Offer-Answer mode allows two participants to exchange data via AOL servers.
- Streams mode gives two participants an authenticated, direct peer-to-peer TCP stream.
- Message mode supports two or more participants, and allows messages to be sent peer-to-peer to a specific participant or to all participants. The participant list, message framing, and keep-alives are handled by AIMCC.
Q: How do I configure a custom session?
A: Call IAccSession's AddCapabilities() to announce your custom session's capability. The custom session's UUID is of your own choosing. Generally, versioning should be done with custom session data, not by creating a new capability UUID for each new version.
Q: How do I initiate a custom session?
A:
- Call IAccSession's CreateCustomSession() to create an IAccCustomSession*.
- Call IAccCustomSession's put_Property(AccCustomSessionProp_Mode) to specify a mode.
- Call IAccCustomSession's Invite() to invite participants.
- OnInviteResult, OnParticipantJoined, OnParticipantLeft and OnSecondarySessionStateChange events fire just as in other secondary sessions.
Q: How do I handle an incoming custom session proposal?
A:
- Handle the OnNewSecondarySession and OnSecondarySessionStateChange(AccSecondarySessionState_ReceivedProposal, S_OK) events as you would for any secondary session.
- Call IAccCustomSession's get_Property(AccCustomSessionProp_Uuid) to see whether it's your custom session.
- Call IAccCustomSession's Accept() or Reject().
- OnSecondarySessionStateChange(AccSecondarySessionState_Online) fires when the custom session is online.
Q: How do I send data in Offer-Answer and Message modes?
A:
- Call IAccCustomSession's SendData(), passing 0 for the streamId. In Message mode, a specific recipient can also be specified.
- OnCustomSendResult fires.
Q: What is the maximum data size that can be sent in Message mode?
A: 64 KB.
Q: How do I receive data in Offer-Answer and Message modes?
A: OnCustomDataReceived fires.
Q: How do I send and receive data in Streams mode?
A:
- Call IAccCustomSession's GetStream(), passing NULL for the reserved parameter and 0 for the streamId, to get the IAccStream*. IAccStream objects implement IStream. C++ developers can QueryInterface() for IStream and ISequentialStream. For non-Windows platforms, IStream and ISequentialStream protocols are declared in AccBase.h.
- Call IAccStream's SetAsyncListener(), passing an IAccStreamListener. "AccSupport.h" contains a minimal C++ sample IAccStreamListener.
- Call the stream object's Write() and Read() to send and receive data, and listen for events in your IAccStreamListener.
Q: Which IAccCustomSession properties are applicable in which modes?
A:
- AccSecondarySessionProp_Name - Message.
- All other properties are applicable in all modes.
Q: Which IAccCustomSession methods are applicable in which modes?
A:
- CancelProposal() - Message.
- Eject() - Message.
- GetStream() - Streams.
- SendData() - Offer-Answer and Message.
- All other methods are applicable in all modes.
rev. 2007/07/23