Приложения

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

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

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

А.5.6.13. rdsEnumConnectedBlocksByVar – перебрать все блоки, соединенные с заданной переменной

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

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

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

RDS_BhBhIDwCb1pV

Параметры

Block (RDS_BHANDLE)

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

VarNum (int)

Номер статической переменной блока, связи которой нужно отслеживать. Нумерация переменных начинается с нуля.

Flags (DWORD)

Набор битовых флагов, управляющих работой функции, объединенных битовым ИЛИ. На данный момент в этом параметре может использоваться только один флаг (он используются и в функции rdsEnumConnectedBlocks):

RDS_BEN_TRACELINKS

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

CallBack (RDS_BhPdPdpV)

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

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

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

Data (LPVOID)

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

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

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

Примечания

Функция rdsEnumConnectedBlocksByVar представляет собой более специализированную версию функции rdsEnumConnectedBlocks – в отличие от последней, она отслеживает не все связи, соединенные с блоком Block, а только связи, подходящие или отходящие от его переменной с номером VarNum. В параметре функции указывается именно номер переменной, а не ее имя: имена переменных часто изменяются пользователями, а их номера обычно жестко фиксированы и их изменение чаще всего приводит к неработоспособности блока (см. описание события RDS_BFM_VARCHECK и §2.5 руководства программиста).

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

Флаги RDS_BEN_INPUTS и RDS_BEN_OUTPUTS, использующиеся в функции rdsEnumConnectedBlocks для указания перебора входов или выходов блока, в этой функции не имеют смысла, так как переменная с номером VarNum уже является либо входом, либо выходом (если она внутренняя, к ней, очевидно, не подключено ни одной связи, и функция CallBack не будет вызвана ни разу). Их наличие или отсутствие в параметре Flags игнорируется.

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

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

См. также

rdsEnumBlocks, rdsEnumConnectedBlocks, rdsGetBlockLink, RDS_POINTDESCRIPTION.