Приложения

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

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

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

А.5.6.12. rdsEnumConnectedBlocks – перебрать все соединенные блоки

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

  RDS_BHANDLE RDSCALL rdsEnumConnectedBlocks(
    RDS_BHANDLE Block,        // Заданный блок
    DWORD Flags,              // Флаги (RDS_BEN_*)
    RDS_BhPdPdpV CallBack,    // Функция пользователя
    LPVOID Data               // Параметр функции пользователя
  );

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

RDS_BhBhDwCb1pV

Параметры

Block (RDS_BHANDLE)

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

Flags (DWORD)

Набор битовых флагов, управляющих работой функции, объединенных битовым ИЛИ:

RDS_BEN_INPUTS	Вызывать функцию CallBack для блоков, соединенных связями с входами блока Block.
RDS_BEN_OUTPUTS	Вызывать функцию CallBack для блоков, соединенных связями с выходами блока Block.
RDS_BEN_TRACELINKS	Если этот флаг не установлен, функция CallBack будет вызываться для всех блоков, непосредственно соединенных связями с блоком Block. Если флаг установлен, RDS будет прослеживать связи до простых блоков и вызывать функцию только для них (см. ниже).

CallBack (RDS_BhPdPdpV)

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

  BOOL RDSCALL имя_функции(
      RDS_PPOINTDESCRIPTION pNearPoint,
      RDS_PPOINTDESCRIPTION pFarPoint,
      LPVOID param)

В параметре pNearPoint пользовательской функции передается указатель на структуру RDS_POINTDESCRIPTION, описывающую точку связи, соединяющую эту связь с блоком Block. В параметре pFarPoint передается указатель на структуру описания точки связи, соединяющей ее с найденным блоком на другом конце этой связи (идентификатор этого блока содержится в структуре описания точки). Следует помнить, что при взведенном флаге RDS_BEN_TRACELINKS эти точки могут принадлежать разным связям. В параметре param передается параметр Data функции rdsEnumConnectedBlocks (см. ниже) без какой-либо обработки. Функция пользователя должна вернуть TRUE, если перебор блоков необходимо продолжить, и FALSE, если его нужно немедленно остановить.

Data (LPVOID)

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

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

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

Примечания

Функция rdsEnumConnectedBlocks обычно используется для выполнения каких-либо однотипных действий над блоками, соединенными с заданным. Например, с ее помощью можно информировать блоки, соединенные с выходами данного, об изменении значения выхода (обычно так осуществляется принудительная передача данных по связям вне режима расчета, см. §1.6 руководства программиста).

Работой функции управляют битовые флаги, передаваемые в параметре Flags. Флаги RDS_BEN_INPUTS и RDS_BEN_OUTPUTS позволяют вызывать пользовательскую функцию только для блоков, соединенных с выходами данного или только для блоков, соединенных с входами (для вызова функции у всех соединенных блоков независимо от направления связи следует указать оба флага). Флаг RDS_BEN_TRACELINKS управляет прослеживанием связей внутрь и наружу подсистем. Если он сброшен, функция CallBack будет вызываться только у блоков, непосредственно соединенных с блоком Block в его родительской подсистеме, при этом вложенные подсистемы и внешние входы и выходы будут считаться конечными точками связи – RDS не будет отслеживать эту связь дальше внутрь вложенной подсистемы или наружу родительской. Если же флаг RDS_BEN_TRACELINKS взведен, функция будет отслеживать каждую связь внутрь и наружу подсистем через внешние входы и выходы и вызывать функцию CallBack только для простых блоков, находящихся в конце такой цепочки связей.

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

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

Пример

Пример использования функции rdsEnumConnectedBlocks приведен в §2.13.2 и §2.13.4 руководства программиста.

См. также

rdsEnumBlocks, rdsEnumConnectedBlocksByVar, rdsGetBlockLink, RDS_POINTDESCRIPTION.