8 Web Service interface definition

29.199-203GPPOpen Service Access (OSA)Parlay X web servicesPart 20: Multimedia multicast session managementTS

8.1 Interface: Multicast

This interface is used by the application to manage:

  • multicast sessions
  • user participation in sessions

8.1.1 Operation: createMulticastSession

The application invokes this operation to create a multicast session using the information it provides. If successful, the application receives the session address (i.e. the IP address) of a newly created session.

8.1.1.1 Input message: createMulticastSessionRequest

Part Name

Part Type

Optional

Description

sessionInformation

SessionInformation

No

Multicast session information

8.1.1.2 Output message: createMulticastSessionResponse

Part Name

Part Type

Optional

Description

result

xsd:string

No

Multicast session address: i.e. the IP address.

8.1.1.3 Referenced Faults

ServiceException from 3GPP TS 29.199-1 [6]:

  • SVC0001 – Service error.
  • SVC0002 – Invalid input value.

PolicyException from 3GPP TS 29.199-1 [6]:

  • POL0001 – Policy error.
  • POL0008 – Charging not supported.
  • POL0012 – Too many description entries specified.

8.1.2 Operation: deleteMulticastSession

The application invokes this operation to delete an existing multicast session.

8.1.2.1 Input message: deleteMulticastSessionRequest

Part Name

Part Type

Optional

Description

sessionAddress

xsd:string

No

Multicast Session Address, i.e. the IP address

8.1.2.2 Output message: deleteMulticastSessionResponse

Part Name

Part Type

Optional

Description

None

8.1.2.3 Referenced Faults

ServiceException from 3GPP TS 29.199-1 [6]:

  • SVC0001 – Service error.
  • SVC0002 – Invalid input value.

PolicyException from 3GPP TS 29.199-1 [6]:

  • POL0001 – Policy error.

8.1.3 Operation: getMulticastSessionInformation

The application invokes this operation to retrieve information for an existing multicast session.

8.1.3.1 Input message: getMulticastSessionInformationRequest

Part Name

Part Type

Optional

Description

sessionAddress

xsd:string

No

Multicast Session Address, i.e. the IP address

8.1.3.2 Output message: getMulticastSessionInformationResponse

Part Name

Part Type

Optional

Description

result

SessionInformation

No

Multicast session information

8.1.3.3 Referenced Faults

ServiceException from 3GPP TS 29.199-1 [6]:

  • SVC0001 – Service error.
  • SVC0002 – Invalid input value.

PolicyException from 3GPP TS 29.199-1 [6]:

  • POL0001 – Policy error.

8.1.4 Operation: inviteUsersToJoin

The application invokes this operation to invite users to join an existing multicast session.

8.1.4.1 Input message: inviteUsersToJoinRequest

Part Name

Part Type

Optional

Description

sessionAddress

xsd:string

No

Multicast Session Address, i.e. the IP address

users

xsd:anyURI
[1…unbounded]

No

The User(s) or user group(s) that are invited to join the multicast session.

8.1.4.2 Output message: inviteUsersToJoinResponse

Part Name

Part Type

Optional

Description

result

UserInformation
[1…unbounded]

No

The participation status of the user(s) who were invited to join the multicast session.

8.1.4.3 Referenced Faults

ServiceException from 3GPP TS 29.199-1 [6]:

  • SVC0001 – Service error.
  • SVC0002 – Invalid input value.

PolicyException from 3GPP TS 29.199-1 [6]:

  • POL0001 – Policy error.
  • POL0006 – Groups not allowed
  • POL0007 – Nested groups not allowed

8.1.5 Operation: requestUsersToLeave

The application invokes this operation to request users to leave an existing multicast session.

8.1.5.1 Input message: requestUsersToLeaveRequest

Part Name

Part Type

Optional

Description

sessionAddress

xsd:string

No

Multicast Session Address, i.e. the IP address

users

xsd:anyURI
[1…unbounded]

No

The User(s) or user group(s) that are requested to leave the multicast session.

8.1.5.2 Output message: requestUsersToLeaveResponse

Part Name

Part Type

Optional

Description

result

UserInformation
[1…unbounded]

No

The participation status of the user(s) who were requested to leave the multicast session.

8.1.5.3 Referenced Faults

ServiceException from 3GPP TS 29.199-1 [6]:

  • SVC0001 – Service error.
  • SVC0002 – Invalid input value.

PolicyException from 3GPP TS 29.199-1 [6]:

  • POL0001 – Policy error.
  • POL0006 – Groups not allowed
  • POL0007 – Nested groups not allowed

8.1.6 Operation: querySessionParticipants

The application invokes this operation to request the set of users who are currently participating in an existing multicast session.

8.1.6.1 Input message: querySessionParticipantsRequest

Part Name

Part Type

Optional

Description

sessionAddress

xsd:string

No

Multicast Session Address, i.e. the IP address

8.1.6.2 Output message: querySessionParticipantsResponse

Part Name

Part Type

Optional

Description

result

xsd:anyURI
[0…unbounded]

Yes

The users, if any, that are participating in the specified session i.e. with a UserStatus value of Joined or Requested ToLeave.

8.1.6.3 Referenced Faults

ServiceException from 3GPP TS 29.199-1 [6]:

  • SVC0001 – Service error.
  • SVC0002 – Invalid input value.

PolicyException from 3GPP TS 29.199-1 [6]:

  • POL0001 – Policy error.

8.1.7 Operation: querySessionForUser

The application invokes this operation to request the address of the multicast session in which the specified user is currently participating.

8.1.7.1 Input message: querySessionForUserRequest

Part Name

Part Type

Optional

Description

user

xsd:anyURI

No

The user participating in a multicast session.

8.1.7.2 Output message: querySessionForUserResponse

Part Name

Part Type

Optional

Description

result

xsd:string

Yes

The (IP) address of the Multicast Session, if any, in which the specified user is participating: i.e. with a UserStatus value of Joined or Requested ToLeave

8.1.7.3 Referenced Faults

ServiceException from 3GPP TS 29.199-1 [6]:

  • SVC0001 – Service error.
  • SVC0002 – Invalid input value.

PolicyException from 3GPP TS 29.199-1 [6]:

  • POL0001 – Policy error.

8.2 Interface: MulticastNotificationManager

8.2.1 Operation: startNotification

The notification pattern with correlation is used in order to correlate the notification events with the request.

The application sets a notification trigger on changes associated with the specified user(s) participation in a multicast session. If the specified user address is a group address, the application will receive an individual notification for each member of the group whose session participation changes.

Note that the SimpleReference structure contains the correlator string used in subsequence messages to the MulticastNotification interface.

8.2.1.1 Input message: startNotificationRequest

Part Name

Part Type

Optional

Description

sessionAddress

xsd:string

No

Multicast Session Address, i.e. the IP address

users

xsd:anyURI
[1…unbounded]

No

The user(s) or group(s) that the application wants to monitor for joining or leaving events

reference

common:
SimpleReference

No

Defines the MulticastNotification interface

frequency

common:
TimeMetric

No

Maximum frequency of notifications (can also be considered minimum time between notifications)

duration

common:
TimeMetric

Yes

Length of time notifications occur for; do not specify to use default notification time defined by service policy

count

xsd:int

Yes

Maximum number of notifications. For no maximum, either do not specify this part or specify a value of zero.

8.2.1.2 Output message: startNotificationResponse

Part Name

Part Type

Optional

Description

None

8.2.1.3 Referenced Faults

ServiceException from 3GPP TS 29.199-1 [6]:

  • SVC0001 – Service error.
  • SVC0002 – Invalid input value.
  • SVC0004 – No valid addresses.
  • SVC0005 – Duplicate correlator.
  • SVC0006 – Invalid group.

PolicyException from 3GPP TS 29.199-1 [6]:

  • POL0001 – Policy error.
  • POL0003 – Too many addresses.
  • POL0004 – Unlimited notifications not supported.
  • POL0005 – Too many notifications requested.
  • POL0006 – Groups not allowed
  • POL0007 – Nested groups not allowed.
  • POL0009 – Invalid frequency requested.

8.2.2 Operation: endNotification

The application may end a notification using this operation.

Until this operation returns, notifications may continue to be received by the application.

An end of notification (notifyEndRequest) message will not be delivered to the application for a notification ended using this operation.

8.2.2.1 Input message: endNotificationRequest

Part Name

Part Type

Optional

Description

correlator

xsd:string

No

The notification the application wants to end.

8.2.2.2 Output message: endNotificationResponse

Part Name

Part Type

Optional

Description

None

8.2.2.3 Referenced Faults

ServiceException from 3GPP TS 29.199-1 [6]:

  • SVC0001 – Service error.
  • SVC0002 – Invalid input value.

PolicyException from 3GPP TS 29.199-1 [6]:

  • POL0001 – Policy error.

8.3 Interface: MulticastNotification

Notification interface to which notifications relating to changes in channel presence information are delivered.

8.3.1 Operation: notifyJoinMulticastSession

This asynchronous operation is invoked to notify the application that the end user has joined the multicast session.

8.3.1.1 Input message: notifyJoinMulticastSessionRequest

Part Name

Part Type

Optional

Description

correlator

xsd:string

No

Identifies the notification request

user

xsd:anyURI

No

The User who has joined the multicast session.

8.3.1.2 Output message: notifyJoinMulticastSessionResponse

Part Name

Part Type

Optional

Description

None

8.3.1.3 Referenced Faults

None

8.3.2 Operation: notifyLeaveMulticastSession

This asynchronous operation is invoked to notify the application that the end user has left the multicast session.

8.3.2.1 Input message: notifyLeaveMulticastSessionRequest

Part Name

Part Type

Optional

Description

correlator

xsd:string

No

Identifies the notification request

user

xsd:anyURI

No

The User who has left the multicast session.

8.3.2.2 Output message: notifyLeaveMulticastSessionResponse

Part Name

Part Type

Optional

Description

None

8.3.2.3 Referenced Faults

None

8.3.3 Operation: notifyError

The error message is sent to the application to indicate that the notification for a user, or for the whole notification, is being cancelled by the Web Service.

8.3.3.1 Input message: notifyErrorRequest

Part name

Part type

Optional

Description

correlator

xsd:string

No

Correlator provided in request to set up this notification.

user

xsd:anyURI

Yes

The user to which the error applies. If not specified the error applies to all users associated with this notification.

reason

common:ServiceError

No

The reason the notification is being discontinued.

8.3.3.2 Output message: notifyErrorResponse

Part name

Part type

Optional

Description

None

8.3.3.3 Referenced faults

None.

8.3.4 Operation: notifyEnd

The notifications have ended for this correlator. This operation will be invoked when the duration or count of notifications has been attained. This operation will not be invoked in the case of an error ending the notifications or deliberate ending of the notification (using endNotification).

8.3.4.1 Input message: notifyEndRequest

Part Name

Part Type

Optional

Description

correlator

xsd:string

No

Identifies the notification request

8.3.4.2 Output message: notifyEndResponse

Part Name

Part Type

Optional

Description

None

8.3.4.3 Referenced Faults

None