Access folder contents

After a container is populated with the folders you want to find, you can read the contents of each folder in the container and the scalars within each folder.

For top-level folders in containers, your application can retrieve folders only in sequence. (Note that subfolders within folders, such as program item folders within a package folder, can be retrieved by identifier with the SmsGetFolderByID function.) After a container has been populated, the order of the folders within that particular container is fixed. Using the SmsGetNextFolder function, your application can access the folders in the container sequentially. SmsGetNextFolder returns the handle to the next folder in the list of folders within a container. To start at the beginning of the list, use the SmsRewind function.

Example:

// Get the handles to all top-level folders in the container.
DWORD numFolders;
SmsGetFolderCount( hContainer, F_ANY, &numFolders);
printf("Container has %d folders\n\n", numFolders );

// Allocate memory for the top-level folders.
HANDLE *phFolders = (HANDLE *)malloc(numFolders * sizeof(HANDLE));

HANDLE hFolder;
// Loop to get handles to all top-level folders 
// and write them to the allocated array.
  for (DWORD dwI = 0; dwI < numFolders; dwI++) {
    stat = SmsGetNextFolder( hContainer,
                             F_ANY,  // For all folder types.
                             &hFolder
                           );
      if (stat != SMS_OK) {
          printf("Error in retrieving a folder: %d\n", stat);
          break;
      }

      phFolders[dwI] = hFolder; //Assign the folder handle to 
                                //next handle in the array.
  }
 

If a folder has subfolders, your application can use these same methods to access those folders. Note that SmsEnumFolderTypes returns a list of the types of subfolders that a folder can contain. SmsGetFolderCount returns the count of the subfolders of a specified type within a folder.

After your application gets the handle to a folder, your application can retrieve the scalars for that folder. The scalars can be retrieved in sequence or by the scalar name:

• To retrieve scalars in sequence, use the SmsGetNextScalar function. SmsGetNextScalar retrieves the next scalar in the list of scalars within the folder and writes the scalar's information into a SCALAR structure.

  Example:

  // Get the next scalar in the folder and print it on the screen.
  SCALAR scalar;
  
  char szName[50];   //Buffer for scalar name.
  char szValue[100]; //Buffer for string or time value.
  char *pszTime;     //Buffer for conversion of time scalars.
  
  scalar.pszName  = szName;
  scalar.pszValue = szValue;
  scalar.dwLen = sizeof(szValue)-1;
  
  stat = SmsGetNextScalar(hFolder,  // Handle to folder.
                          &scalar   // Pointer to SCALAR struct
                          );
  
  // Check the scalar type, display accordingly.
          switch (scalar.scType) {
          case SCALAR_STRING:
              printf("\t%20s: %s\n", 
                     scalar.pszName, 
                     scalar.pszValue);
              break;
  
          case SCALAR_INT:
              printf("\t%20s: %ld\n", 
                     scalar.pszName, 
                     scalar.dwValue);
              break;
  
          case SCALAR_TIME:
              // If there is a string equivalence use it.
              if (scalar.bStringEquivalence) {
                  printf("\t%20s: %s\n", 
                         scalar.pszName, 
                         scalar.pszValue);
              } else {
                  pszTime = ctime( &scalar.tValue );
                  printf("\t%20s: %s", 
                         scalar.pszName, 
                         pszTime);
              }
              break;
  
          case SCALAR_BINARY:
              printf("\t%20s: Length of binary data is %d\n", 
                     scalar.pszName, 
                     scalar.dwLen);
              break;
          }
      }
   

• To retrieve scalars by scalar name, use the SmsGetScalarByName function, which retrieves the scalar with the specified scalar name from the folder and writes the scalar's information into a SCALAR structure.

  Example:

  // Get the scalar named "Package ID" from the job folder
  // specified by hFolder and print it on the screen.
  
  SCALAR scalar;
  
  //Buffer for string value. Package ID is 8 char.
  char szValue[9]; 
  scalar.pszValue = szValue;
  scalar.dwLen = sizeof(szValue)-1;
  
  stat = SmsGetScalarByName(hFolder,      // Handle to folder.
                            "Package ID", // Name of scalar to 
                                          // retrieve.
                            &scalar       // Pointer to SCALAR to 
                                          // place scalar data.
                            );
  
  printf("\t%20s: %s\n", scalar.pszName, scalar.pszValue);
   

Note that the SmsGetScalarCount function returns the count of scalars within a folder.

If a folder no longer needs to be accessed, use the SmsCloseFolder function to close the folder and deallocate the memory used by the folder.