Приложения

Приложение А. Функции, константы и структуры RDS

А.5. Сервисные функции и макросы RDS

А.5.6. Операции с блоками и связями

А.5.6.11. rdsEnumBlocks – перебрать все блоки подсистемы

Функция rdsEnumBlocks вызывает пользовательскую функцию, указатель на которую передается в параметрах, для каждого блока указанной подсистемы.

  RDS_BHANDLE RDSCALL rdsEnumBlocks(
    RDS_BHANDLE Parent,    // Подсистема
    int Type,              // Маска типов блоков
    BOOL Recurse,          // Вызывать во вложенных подсистемах
    RDS_BBhpV CallBack,    // Функция пользователя
    LPVOID Data            // Параметр функции пользователя
  );

Тип указателя на эту функцию

RDS_BhBhIBCbpV

Параметры

Parent (RDS_BHANDLE)

Идентификатор подсистемы, для блоков которой нужно вызвать функцию пользователя CallBack.

Type (int)

Маска типов блоков, для которых нужно вызывать функцию – стандартные константы типов блоков RDS_BT*, объединенные битовым ИЛИ. Если нужно вызвать функцию для каждого блока подсистемы независимо от его типа, в этом параметре можно передать 0.

Recurse (BOOL)

TRUE, если нужно вызывать функцию CallBack не только для блоков, непосредственно находящихся в подсистеме Parent, но для блоков во всех ее вложенных подсистемах. FALSE, если нужно вызывать функцию только для блоков, непосредственно находящихся в Parent.

CallBack (RDS_BBhpV)

Указатель на пользовательскую функцию, которую нужно вызвать для каждого блока, удовлетворяющего параметрам Type и Recurse. Пользовательская функция должна иметь следующий вид:

  BOOL RDSCALL имя_функции(RDS_BHANDLE block,LPVOID param);

В параметре block пользовательской функции передается идентификатор блока, для которого вызвана функция, в параметре param – параметр Data (см. ниже) без какой-либо обработки. Функция пользователя должна вернуть TRUE, если перебор блоков необходимо продолжить, и FALSE, если его нужно немедленно остановить.

Data (LPVOID)

Параметр типа void*, передаваемый в параметре param пользовательской функции при каждом ее вызове.

Возвращаемое значение

Идентификатор блока (RDS_BHANDLE), для которого функция пользователя вернула FALSE. Если функция пользователя всегда возвращала TRUE (перебраны все блоки), вместо идентификатора блока возвращается NULL.

Примечания

Функция rdsEnumBlocks обычно используется для выполнения каких- либо однотипных действий над блоками подсистемы. Ее также можно использовать для поиска блока по какому-либо критерию: если написать пользовательскую функцию, которая будет вызываться для каждого блока таким образом, чтобы она возвращала FALSE, если блок, переданный в ее параметре block, удовлетворяет заданному критерию, то результатом возврата rdsEnumBlocks будет искомый блок.

Функция перебирает блоки в порядке, определяемом внутренней логикой RDS, программист никак не может изменить этот порядок.

Параметр Data, имеющий тип LPVOID (произвольный указатель), передается в вызываемую функцию пользователя без изменений. Это единственный способ передать ей какие-либо данные: например, можно передать указатель на какую-либо структуру, а внутри пользовательской функции привести его к нужному типу и обращаться к полям этой структуры.

Для перебора всех блоков заданного типа в какой-либо подсистеме вместо rdsEnumBlocks можно использовать функции rdsGetFirstBlock и rdsGetNextBlock.

Пример

В этом примере rdsEnumBlocks используется для поиска первого попавшегося блока схемы, комментарий которого содержит заданный текст.

  // Функция пользователя
  BOOL RDSCALL MyEnumCallback(RDS_BHANDLE block,LPVOID param)
  { char *text=(char*)param; // Приводим тип к char*
    // Получаем описание блока block с комментарием
    RDS_BLOCKDESCRIPTION Descr;
    Descr.servSize=sizeof(Descr);
    rdsGetBlockDescription(block,&Descr);
    // Возвращаем FALSE, если в комментарии есть текст param
    if(strstr(Descr.BlockComment,text))
      return FALSE;
    return TRUE;
  }
      ...
  // Поиск во всей схеме простого блока, в комментарии которого
  // содержится текст "тест"
  RDS_BHANDLE found=rdsEnumBlocks(
    rdsGetRootSystem(NULL),  // Корневая подсистема
    RDS_BTSIMPLEBLOCK,       // Только простые блоки
    TRUE,                    // С вложенными подсистемами
    MyEnumCallback,          // Вызываемая функция
    "тест");                 // Текст для поиска
  // В found находится идентификатор найденного блока или NULL

См. также

rdsEnumConnectedBlocks, rdsEnumConnectedBlocksByVar, rdsBroadcastFunctionCallsEx, rdsBCLCreateList, rdsGetFirstBlock, rdsGetNextBlock.