The UMSNegotiatorSink and UMSNegotiatorSource objects are an Ultimedia Services Version 2 feature and do not apply to Ultimedia Services Version 1.2.1.
The UMSNegotiatorSink and UMSNegotiatorSource classes define a consistent interface for negotiating a common data format between two objects. Doing so enables the two objects to communicate using the same data format.
Note: The UMSNegotiatorSink and UMSNegotiatorSource interfaces can actually be used to negotiate anything whose choices can be encoded as a list of strings.
By definition, UMSNegotiatorSink objects consume data and are therefore called sink objects. Likewise, UMSNegotiatorSource objects provide data and are therefore called source objects.
For introductory information, see Image Window and Negotiator Objects.
By deriving the interface of an object from either UMSNegotiatorSink or UMSNegotiatorSource (or both), you provide the ability to:
A typical negotiation between a UMSNegotiatorSink object and a UMSNegotiatorSource object occurs as follows (assuming the negotiation is over the image format the source object produces and the sink object consumes):
set_input_decision(sink, ev, "IMAGE_FORMAT"); set_output_decision(source, ev, "IMAGE_FORMAT"); get_input_choices_list(sink, ev, &list_of_sink_image_formats); get_output_choices_list(source, ev, &list_of_source_image_formats);
common_image_format = ...; /* find a common image format in
* list_of_sink_image_formats and
* list_of_source_image_formats */
set_input_choice(sink, ev, common_image_format); set_output_choice(source, ev, common_image_format);
To define a class as either a source or a sink (or both), you should derive the class from UMSNegotiatorSource or UMSNegotiatorSink (or both) and then override and implement the corresponding UMSNegotiatorSource and UMSNegotiatorSink methods.
To learn more about the UMSNegotiatorSink and UMSNegotiatorSource, see:
enum ReturnCode {
Success,
Failure,
InvalidArgument,
Failure,
NotSupported,
UnsupportedFormat,
NullPointer
};
This method can be used to set and verify the category of decision to which the remaining methods refer. Most often this relates to the general category of media that is given. A return of Success means that the object recognizes the decision alias and use of the other methods now relate to that question. A return of InvalidArgument means that the object is not able to participate in that way. Use of the other methods in this interface is inappropriate until a successful return from this method.
| in string decision_alias | Use the decision_alias parameter to define the topic of the negotiation. For example, if you'd like to negotiate image formats, set the decision_alias to IMAGE_FORMAT. |
This method provides a list of acceptable choices for the decision. When the decision alias was IMAGE_FORMAT, then this is a list of image format strings. When more than one item appears in the list, the choice needs to be set as a way of specifying the desired input.
This method sets the choice for the decision. When the decision alias was IMAGE_FORMAT, then this sets the format of the image that is given to the object. A return of InvalidArgument means that the choice is not valid for this object; the choice should be one of those in the list returned by get_input_choices_list.
| in string choice | Specifies the desired selection. |
This method can be used to retrieve the choice set by set_input_choice, or to get the value of the default if no choice has been made.
| out string choice | Provides the desired selection. Software provided with the string is responsible for freeing this memory. |
Some choices allow further parametric specification of details. UMSNegociatorSource objects can provide additional interfaces to query or set these details. See UMSDataFormatControl for a discussion of these interfaces.
This method can be used to set and verify the category of decision to which the remaining methods refer. Most often this relates to the general category of media to be supplied. A return of Success means that the object recognizes the decision alias and use of the other methods now relate to that question. A return of InvalidArgument means that the object is not able to participate in that way. Use of the other methods in this interface is inappropriate until a successful return from this method.
| in string decision_alias | Use the decision_alias parameter to define the topic of the negotiation. For example, if you'd like to negotiate image formats, set the decision_alias to IMAGE_FORMAT. |
This method provides a list of acceptable choices for the decision. When the decision alias was IMAGE_FORMAT, then this is a list of image format strings. When more than one item appears in the list, the choice needs to be set as a way of specifying the desired output.
This method sets the choice for the decision. When the decision alias was IMAGE_FORMAT, then this sets the format of the image to be provided by the object. A return of InvalidArgument means that the choice is not valid for this object; the choice should be one of those in the list returned by get_output_choices_list.
| in string choice | Specifies the desired selection |
This method can be used to retrieve the choice set by set_output_choice, or to get the value of the default if no choice has been made.
| out string choice | Provides the desired selection. Software provided with the string is responsible for freeing this memory. |
Some choices allow further parametric specification of details. UMSNegociatorSource objects can provide additional interfaces to query or set these details. See UMSDataFormatControl for a discussion of these interfaces.
For introductory information, see Image Window and Negotiator Objects.