SmsCreateFolder

The SmsCreateFolder creates a new folder of the specified type.

SMS_STATUS SmsCreateFolder(
  HANDLE hParent,  // Handle to parent folder or container.
  DWORD fType,     // Type of folder to create.
  const char *pszFolderID,
                   // Identifier to assign to the new folder.
  HANDLE *phFolder // Pointer to handle to receive the folder handle.
);
 

Parameters

hParent

Specifies the container or folder in which the new folder will be created.

fType

Specifies the type of folder to create. The following folder types support creation and deletion:

F_PACKAGE
F_WCL
F_PROGITEM
F_INSTALLJOB
F_SRVINSTALLJOB
F_REMPKGJOB
F_INVENTORY

pszFolderID

Specifies the identifier to assign to the folder. SMS itself will assign the identifier. This parameter is not used. Your application can set this parameter to NULL.

phFolder

Receives a handle to the new folder.

Return Values

The SmsCreateFolder 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_INVALID_HANDLE

The specified parent handle is not a valid folder handle or container handle.

SMS_NO_CREATE

The specified folder type does not support creation. The folder type is read-only.

SMS_PARENT_ALREADY_COMMITTED

Your application attempted to create a subfolder for a parent folder that has already been committed. After a folder is committed, modification is not allowed.

SMS_INVALID_FOLDER_TYPE

The specified folder type is not a valid subfolder type for the specified parent folder or container.

Remarks

Folders are created in the context of a parent, that is, folders are always created within a container or a parent folder. In addition, some folder types support creation and others do not (see the preceding list). Your application can create a new folder only if the folder's type supports creation.

After a new folder has been created, the folder is empty, that is, it has no scalars set within it. Your application must set the scalars for the new folder. Using the SmsDescribeFolder function, your application can retrieve the list of scalars for a folder. Using the SmsSetScalar function, your application can set the value for each scalar in the new folder. A new folder also does not contain any subfolders. Your application can use the SmsCreateFolder function to add subfolders to the new folder.

In addition, a new folder created by SmsCreateFolder is not linked to its parent folder (your application must use the SmsLinkFolder function to link a new folder to its parent). Linking associates the new folder to its parent within your application's memory—the folder is not written to the site database.

To add the new folder to the site database, your application must use the SmsCommitFolder function to write the folder to the database.

Note that when your application creates a folder, it has created an instance of a new folder. To deallocate the memory for the new folder, your application must use SmsCloseFolder to close the folder.

See Also

SmsCloseFolder, SmsCommitFolder, SmsDescribeFolder, SmsLinkFolder, SmsSetScalar