ct_con_props

Description

Set or retrieve connection structure properties.

Syntax

CS_RETCODE ct_con_props(connection, action, property,
                buffer, buflen, outlen)
 
 CS_CONNECTION    *connection;
 CS_INT                       action;
 CS_INT                       property;
 CS_VOID                    *buffer;
 CS_INT                       buflen;
 CS_INT                        *outlen;

Parameters

connection

A pointer to a CS_CONNECTION structure. A CS_CONNECTION structure contains information about a particular client/server connection.

action

One of the following symbolic values:

Value of action

Result

CS_SET

Sets the value of the property.

CS_GET

Retrieves the value of the property.

CS_CLEAR

Resets the property to its default value.

CS_SUPPORTED

Checks whether a distributed-service driver supports the property. Use only with properties that affect the behavior of a directory or security driver. See “Checking whether a property is supported”.

property

The symbolic name of the property whose value is being set or retrieved. Table 3-12 lists the properties that can be set with ct_con_props. “Properties” lists all Client-Library properties.

buffer

If a property value is being set, buffer points to the value to use in setting the property.

buflen

Generally, buflen is the length, in bytes, of *buffer.

If *buffer is a fixed-length or symbolic value, pass buflen as CS_UNUSED.

outlen

A pointer to an integer variable.

outlen is not used if a property value is being set and should be passed as NULL.

If a property value is being retrieved and outlen is supplied, ct_con_props sets *outlen to the length, in bytes, of the requested information.

If the information is larger than buflen bytes, an application can use the value of *outlen to determine how many bytes are needed to hold the information.

Returns

ct_con_props returns the following values:

Return value

Meaning

CS_SUCCEED

The routine completed successfully.

CS_FAIL

The routine failed.

CS_BUSY

An asynchronous operation is already pending for this connection. See “Asynchronous programming”.

Examples

Example 1

This code excerpt is from the blktxt.c sample program.

        /*

         ** EstablishConnection()
         **
         ** Purpose:
         ** This routine establishes a connection to the server 
         ** identified in example.h and sets the CS_USER,
         ** CS_PASSWORD, and CS_APPNAME properties for the 
         ** connection.
         **
         ** NOTE: The user name, password, and server are defined
         ** in the example header file.
         */
        CS_STATIC CS_RETCODE
         EstablishConnection(context, connection)
         CS_CONTEXT      *context;
         CS_CONNECTION   *connection;
         {
             CS_INT      len;
             CS_RETCODE  retcode;
             CS_BOOL     bool;
            /* Allocate a connection structure */
             ...CODE DELETED.....
            /*    
             ** If a user name is defined in example.h, set the 
             ** CS_USERNAME property.
             */
             if (retcode == CS_SUCCEED && Ex_username != NULL)
             {
                 if ((retcode = ct_con_props(*connection, CS_SET,
                     CS_USERNAME, Ex_username, CS_NULLTERM, NULL))
                     != CS_SUCCEED)
                 {
                     ex_error("ct_con_props(username) failed");
                 }
             }
            /*    
             ** If a password is defined in example.h, set the 
             ** CS_PASSWORD property.
             */
             if (retcode == CS_SUCCEED && Ex_password != NULL)
             {
                 if ((retcode = ct_con_props(*connection, CS_SET,
                     CS_PASSWORD, Ex_password, CS_NULLTERM, NULL))
                     != CS_SUCCEED)
                 {
                     ex_error("ct_con_props(passwd) failed");
                 }
             }
            /* Set the CS_APPNAME property */
             ...CODE DELETED.....
            /* Enable the bulk login property */
             if (retcode == CS_SUCCEED)
             {
                 bool = CS_TRUE;
                 retcode = ct_con_props(*connection, CS_SET,
                     CS_BULK_LOGIN, &bool, CS_UNUSED, NULL);
                 if (retcode != CS_SUCCEED)
                 {
                      ex_error("ct_con_props(bulk_login) failed");
                 }
             }
            /* Open a server connection */
             ...CODE DELETED.....
        }

Example 2

In the following example, CS_SEC_EXTENDED_ENCRYPTION is disabled:

...
CS_INT Ex_encryption = CS_FALSE;
CS_INT Ex_nonencryptionretry = CS_FALSE;
...
main()
{
    ...
    /*
    
    ** This needs to be called before calling ct_connect()
    */
     ret = ct_con_props(connection, CS_SET, CS_SEC_EXTENDED_ENCRYPTION,
           &Ex_encryption, CS_UNUSED, NULL);
    EXIT_ON_FAIL(context, ret, "Could not set extended encryption");
    ret = ct_con_props(connection, CS_SET, CS_SEC_NON_ENCRYPTION_RETRY,
          &Ex_nonencryptionretry, CS_UNUSED, NULL);
    EXIT_ON_FAIL(context, ret, "Could not set non encryption retry");
    ...
}

Usage

For information about action, buffer, buflen, and outlen, see Chapter 2, “Understanding Structures, Constants, and Conventions,” in the Open Client Client-Library/C Programmers Guide.

See also

ct_capability, ct_cmd_props, ct_connect, ct_config, ct_init, “Properties”