Buffers

A number of arguments used in Client-Library functions affect the contents of buffers: action, buffer, buf_len, outlen.

• action describes what is done to the data. For most functions, action can take the following symbolic values:

  CS_SET	Assigns a value
  CS_GET	Retrieves a value
  CS_CLEAR	Clears the buffer, or, resets to the default property value

• buffer is a program variable, called a “buffer.”

  When action is CS_SET	buffer is the data being read by the function.
  When action is CS_GET	buffer is the information retrieved by the function.
  When action is CS_CLEAR	buffer remains unchanged.

• buf_len is the length, in bytes, of the buffer argument.

  When the value in the buffer is a fixed-length or symbolic value:	Assign buf_len the actual length of the value, or CS_UNUSED.
  When the value in the buffer is of variable length:	Assign buf_len the maximum number of bytes that the buffer can contain.

  If buf_len is set to CS_GET and the buffer is too small to hold the returned value, the function returns CS_FAIL. When this happens, you can query the length of the incoming data by setting CS_SET to 0 and executing the function. The actual length of the data is returned to the outlen argument. Enlarge the buffer, assign the value in outlen to buf_len, and execute the function again.

• outlen is an integer variable where the function returns the actual length, in bytes, of the data being retrieved during a CS_GET operation. For all other operations, outlen is ignored.When the retrieved data is longer than buf_len bytes, an application can use the value of outlen to determine how many bytes are needed to hold the information. To do this:

  • Set the value of outlen to 0 and call the function

  • Set the value of buf_len to the length returned in outlen

  • Call the function again