SmsDataSourceConnect

The SmsDataSourceConnect function connects to the site database that your application will access.

SMS_STATUS SmsDataSourceConnect(
  DATASOURCE *pd, // Pointer to DATASOURCE union containing the 
                  // connection information.
  HANDLE *phConn  // Pointer to handle to receive connection handle.
);
 

Parameters

pd

Specifies a DATASOURCE union that specifies the site database to which your application needs to connect. (DATASOURCE is a union of structures.) Before calling SmsDataSourceConnect, your application must set the appropriate values for the members in this structure. For Microsoft SQL Server, your application must set the server name, login identifier, password, database, public encryption key, and a pointer to a decryption function for the sqlParams structure within the DATASOURCE union. (The decryption function is a callback function that SmsDataSourceConnect uses to decrypt the pszUserName and pszPasswd members so that they can be used as the login identifier and password for connecting to the site database.) If the pointer to the decryption function is set to NULL or the encryption key is NULL, no decryption function is called.

For an example of encryption and decryption functions and how they are used with SmsDataSourceConnect, see Sample Decryption and Encryption Functions.

phConn

Specifies the handle that will receive the handle to the specified database connection. You use the handle to open, access, and close containers for that site database.

Return Values

The SmsDataSourceConnect function returns a status code SMS_STATUS. If successful, the function returns a status of SMS_OK. Otherwise, it returns one of the following manifest constants:

SMS_SQL_ERROR

The connect failed because of a SQL Server error.

SMS_INVALID_DATASOURCE

The connect failed because the datasource type could not be registered.

SMS_INVALID_HANDLE

The database connection could not be made because of a memory allocation failure.

SMS_ALREADY_CONNECTED

Your application has an existing connection to the site database. An application can have only one connection to a site database at one time.

Remarks

SmsDataSourceConnect assigns a connection handle to the specified handle. Your application uses the handle to open, access, and close containers for that site database.

Currently, SMS supports one database type: Microsoft SQL Server. However, the SMS API is designed to allow support of other types of databases in the future.

Note that your application can connect to one site database at a time. In addition, your application can have only one connection to that site database.

After your application has finished accessing the site database, it should free the connection by calling the SmsDataSourceDisconnect function.

Example

The following example connects to a SQL Server JS1 with a site database SMSBritain using login identifier jonathan and password hermes.

HANDLE hConnect;
DATASOURCE dsParams;

    dsParams.sqlParams.ds          = DB_SQL;
    dsParams.sqlParams.pszServer   = "JS1";
    dsParams.sqlParams.pszUserName = "jonathan";
    dsParams.sqlParams.pszPasswd   = "hermes";
    dsParams.sqlParams.pszDbName   = "SMSBritain";
    dsParams.sqlParams.pFunc       = NULL;
    dsParams.sqlParams.pszKey      = "";

stat = SmsDataSourceConnect( &dsParams, &hConnect );

See Also

SmsDataSourceDisconnect