HP BL680c XenEnterprise Management API - Page 8

1.3. WIRE PROTOCOL FOR REMOTE API CALLS CHAPTER 1. INTRODUCTION John 1.2 • our Void type is transmitted as an empty string. 1.3.1 Note on References vs UUIDs References are opaque types - encoded as XML-RPC strings on the wire - understood only by the particular server which generated them. Servers are free to choose any concrete representation they find convenient; clients should not make any assumptions or attempt to parse the string contents. References are not guaranteed to be permanent identifiers for objects; clients should not assume that references generated during one session are valid for any future session. References do not allow objects to be compared for equality. Two references to the same object are not guaranteed to be textually identical. UUIDs are intended to be permanent names for objects. They are guaranteed to be in the OSF DCE UUID presentation format (as output by uuidgen. Clients may store UUIDs on disk and use them to lookup objects in subsequent sessions with the server. Clients may also test equality on objects by comparing UUID strings. The API provides mechanisms for translating between UUIDs and opaque references. Each class that contains a UUID field provides: • A "get by uuid" method that takes a UUID, u, and returns an opaque reference to the server-side object that has UUID=u; • A get uuid function (a regular "field getter" RPC) that takes an opaque reference, r, and returns the UUID of the server-side object that is referenced by r. 1.3.2 Return Values/Status Codes The return value of an RPC call is an XML-RPC Struct. • The first element of the struct is named Status; it contains a string value indicating whether the result of the call was a "Success" or a "Failure". If Status was set to Success then the Struct contains a second element named Value: • The element of the struct named Value contains the function's return value. In the case where Status is set to Failure then the struct contains a second element named ErrorDescription: • The element of the struct named ErrorDescription contains an array of string values. The first element of the array is an error code; the remainder of the array are strings representing error parameters relating to that code. For example, an XML-RPC return value from the host.get resident VMs function above may look like this: Status Success 8