NAME

rpc_cs_get_tags- retrieves code set tags from a binding handle

SYNOPSIS

#include <dce/codesets_stub.h>

void rpc_cs_get_tags(
	rpc_binding_handle_t binding,
	boolean32 server_side,
	unsigned32 *sending_tag,
	unsigned32 *desired_receiving_tag,
	unsigned32 *receiving_tag,
	error_status_t *status);

PARAMETERS

Input

binding

Specifies the binding handle from which to obtain the code set tag information. When called from the client stub, this value is the binding handle of a compatible server returned by the rpc_ns_binding_import_next() or rpc_ns_binding_select() routines.

server_side

Indicates whether a client stub (FALSE) or server stub (TRUE) is calling the routine.

desired_receiving_tag

(Server stub only) Specifies the code set value for the code set in which the client prefers data to be encoded when sent back to it from the server. The client stub passes this value in the call. If the routine is retrieving code set tags for an operation that does not specify a desired receiving tag argument-that is, the cs_drtag ACS attribute has not been applied to one of the operation's arguments-this value is NULL.

Output

sending_tag

(Client stub only) Specifies the code set value for the code set in which client data to be sent to the server is to be encoded. If the routine is retrieving code set tags for an operation that does not specify a sending tag argument-that is, the cs_stag ACS attribute has not been applied to one of the operation's arguments-this value is NULL.

desired_receving_tag

(Client stub only) Specifies the code set value for the code set in which the client prefers data to be encoded when sent back to it from the server. The client stub passes this value in the call. If the routine is retrieving code set tags for an operation that does not specify a desired receiving tag argument-that is, the cs_drtag ACS attribute has not been applied to one of the operation's arguments-this value is NULL.

receiving_tag

(Server stub only) Specifies the code set value for the code set in which the server is to encode data to be sent back to the client. If the routine is retrieving code set tags for an operation that does not specify a receiving tag argument-that is, the cs_rtag ACS attribute has not been applied to one of the operation's arguments-this value is NULL.

status

Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not.

Possible status codes and their meanings include:

rpc_s_ok

Success.

rpc_s_ss_invalid_codeset_tag

Code set tag structure not valid.

If code set compatibility evaluation is performed, the routine can also return status codes generated by the rpc_rgy_get_codesets(), rpc_ns_binding_inq_entry_name(), and rpc_ns_mgmt_read_codesets() routines.

DESCRIPTION

The rpc_cs_get_tags() routine is used by client and server stubs to retrieve the code set values used to tag international character data for encoding before it is transmitted over the network. The routine is one of those used for character and code set interoperability, which permits clients and servers to transfer international character data in a heterogeneous character set and code sets environment.

Client and server stubs call the rpc_cs_get_tags() routine before calling the appropriate buffer sizing routine, which calculates the size of the buffer required to hold converted international character data, and code set conversion routine, which performs the conversion (if necessary). In general, the code set tag values to be used as tags are determined by a character and code sets evaluation routine invoked by the client application code. However, there are other methods by which values for code set tags can be established.

When called by the client, the rpc_cs_get_tags() routine may not be required to perform the character and code sets evluation; if the client has added a code sets evaluation routine to the binding import procedure by calling the routine rpc_ns_import_ctx_add_eval(), the binding handle contains the conversion method and the code set values to set for the client's sending tag and desired receiving tag. If the binding handle does not contain the results of an evaluation, the rpc_cs_get_tags() routine performs the character and code sets evaluation within the client stub and sets the client code set tag values itself. If the conversion method is "client makes it right" (CMIR), the client's sending tag and desired receiving tags are be set to the code set value of the server's local code set. If the conversion method is "server makes it right" (SMIR), the sending tag and desired receiving tag will be set to the client's local code set value. If the conversion method is "receiver makes it right" (RMIR), the sending tag is the client's code set, and the desired receiving tag is the server's code set.

When called from the server stub, the rpc_cs_get_tags() routine sets the code set value in desired_receiving_tag to receiving_tag and returns this value as output to the server stub, where it determines the code set used to encode data sent back to the client.

The cs_tag_rtn attribute allows applications to specify the rpc_cs_get_tags() routine as part of an automatic code set conversion process. Alternatively, further code set tag retrieval implementations may be specified to this attriubute. Code set tags can also be set explicitly in the application instead of in the stubs.

Permissions Required

None.

RETURN VALUE

None.

SEE ALSO

cs_byte_from_netcs()
cs_byte_local_size()
cs_byte_net_size()
cs_byte_to_netcs()
rpc_cs_char_set_compat_check()
rpc_cs_eval_without_universal()
rpc_ns_binding_import_next()
rpc_ns_binding_inq_entry_name()
rpc_ns_binding_select()
rpc_ns_import_ctx_add_eval()
rpc_ns_mgmt_read_codesets()
rpc_rgy_get_codesets()
wchar_t_from_netcs()
wchar_t_local_size()
wchar_t_net_size()
wchar_t_to_netcs().

Please note that the html version of this specification may contain formatting aberrations. The definitive version is available as an electronic publication on CD-ROM from The Open Group.