WebKitIDLWebKit.docx
《WebKitIDLWebKit.docx》由会员分享，可在线阅读，更多相关《WebKitIDLWebKit.docx（21页珍藏版）》请在冰点文库上搜索。
WebKitIDLWebKit
WebKitIDL–WebKit
Overview
TheWebIDLisalanguagethatdefineshowWebCoreinterfacesareboundtoexternallanguagessuchasJavaScriptCore,
ObjC,GObjectandCPP.YouneedtowriteIDLfiles（e.g.
XMLHttpRequest.idl,Element.idl,etc）toexposeWebCoreinterfacesto
thoseexternallanguages.WhenWebKitisbuilt,theIDLfilesare
parsed,andthecodetobindWebCoreimplementationsandJavaScriptCore,ObjC,GObjectandCPPinterfacesisautomaticallygenerated.
ThisdocumentdescribespracticalinformationabouthowtheIDLbindings
workandhowyoucanwriteIDLfilesinWebKit.ThesyntaxofIDLfiles
isfairlywelldocumentedintheWebIDLspec,
butitistooformaltoread:
-）andthereareseveraldifferences
betweentheWebIDLspecandtheWebKitIDLduetoimplementation
issues.
BasicsofIDL
HereisanexampleofIDLfiles:
modulecore{
[
CustomToJSObject
]interfaceNode{
constunsignedshortELEMENT_NODE=1;
attributeNodeparentNode;
[TreatReturnedNullStringAs=Null]attributeDOMStringnodeName;
[Custom]NodeappendChild（[CustomReturn]NodenewChild）;
voidaddEventListener（DOMStringtype,EventListenerlistener,optionalbooleanuseCapture）;
};
}
Letusintroducesometerminologies:
TheaboveIDLfiledescribestheNodeinterface.
ELEMENT_NODEisaconstantoftheNodeinterface.
parentNodeandnodeNameareattributesoftheNodeinterface.
appendChild（...）andaddEventListener（...）aremethodsoftheNodeinterface.
type,listeneranduseCaptureareparametersoftheNodeinterface.
[CustomToJSObject],[TreatReturnedNullStringAs=Null],[Custom]and[CustomReturn]areIDLattributes.
Note:
TheseterminologiesarenotalignedwiththeWebIDLspec.
IntheWebIDLspec,a'method'iscalledan'operation'.
Thereisnodistinctionbetweenan'attribute'anda'parameter'（a'parameter'istreatedasan'attribute'）.
Thekeypointsareasfollows:
AnIDLfilecontrolshowthebindingscodebetweenJavaScript
engine（orObjC,GObject,CPP）andtheWebKitimplementationis
generated.
IDLattributesenableyoutocontrolthebindingscodemoreindetail.
Thereare90~IDLattributesandtheirrolesareexplainedinthesubsequentsections.
IDLattributescanbespecifiedoninterfaces,methods,attributesandparameters.
WhereeachIDLattributecanbespecifiedonisdefinedpereachIDLattribute.
Thisisalsoexplainedinthesubsequentsections.
AtemplateofanIDLfileisasfollows:
moduleMODULE_NAME{
[
IDL_ATTRIBUTE_ON_INTERFACE1,
IDL_ATTRIBUTE_ON_INTERFACE2,
...
]interfaceINTERFACE_NAME{
constunsignedlongvalue=12345;
[IDL_ATTRIBUTE_ON_ATTRIBUTE1,IDL_ATTRIBUTE_ON_ATTRIBUTE2,...]attributeNodenode;
[IDL_ATTRIBUTE_ON_METHOD1,IDL_ATTRIBUTE_ON_METHOD2,...]voidfunc（[IDL_ATTRIBUTE_ON_PARAMETER1,IDL_ATTRIBUTE_ON_PARAMETER2,...]intparam,...）;
};
}
IfthereisnoIDLattributesoninterfaces,theIDLfilejustlookslikethis:
moduleMODULE_NAME{
interfaceINTERFACE_NAME{
constunsignedlongvalue=12345;
[IDL_ATTRIBUTE_ON_ATTRIBUTE1,IDL_ATTRIBUTE_ON_ATTRIBUTE2,...]attributeNodenode;
[IDL_ATTRIBUTE_ON_METHOD1,IDL_ATTRIBUTE_ON_METHOD2,...]voidfunc（[IDL_ATTRIBUTE_ON_PARAMETER1,IDL_ATTRIBUTE_ON_PARAMETER2,...]intparam,...）;
};
}
IDLattributechecker
PreviouslytherehadbeenmanybugscausedbytyposofIDLattributesinIDLfiles.
Toavoidsuchbugs,theIDLattributecheckerisintroducedtotheWebKitbuildflow
tocheckifalltheIDLattributesusedinIDLfilesareimplementedincodegenerators.
IfyouuseanIDLattributenotimplementedincodegenerators,theIDLattributecheckerfails,andtheWebKitbuildfails.
AlistofIDLattributesimplementedincodegeneratorsisdescribedinWebCore/bindings/scripts/IDLAttributes.txt.
IfyouwanttoaddanewIDLattribute,youneedto
addtheIDLattributetoWebCore/bindings/scripts/IDLAttributes.txt.
addtheexplanationtothisdocument.
addtestcasestorun-bindings-tests（explainedbelow）.
run-bindings-tests
Tools/Scripts/run-bindings-teststestsIDLattributes.
Specifically,run-bindings-testsreads
WebCore/bindings/scripts/test/*.idl,
andthengeneratesbindingscodeto
WebCore/bindings/scripts/test/{JS,ObjC,GObject,CPP}/*.
Forexample,run-bindings-testsreads
WebCore/bindings/scripts/test/TestObj.idl,
andthengeneratesbindingscodeto
WebCore/bindings/scripts/test/JS/JSTestObj.h,
WebCore/bindings/scripts/test/JS/JSTestObj.cpp,etc.
IfyouchangethebehaviorofcodegeneratorsoraddanewIDLattribute,
pleaseaddtestcasestoWebCore/bindings/scripts/test/*.idl.
Youcanresettherun-bindings-testsresultsusingthe--reset-resultsoption:
$./Tools/Scripts/run-bindings-tests--reset-results
Theobjectiveofrun-bindings-testsistoshowyouandreviewershowthecodegenerationischangedbyyourpatch.
Ifyouchangethebehaviorofcodegenerators,pleaseupdatetheresultsofrun-bindings-tests.
Thatbeingsaid,run-bindings-testsisjustforshowingthechangetoyouandreviewers,
andthetestfailureisnotcriticalfortheWebKitbuild.
Peoplehavebeenlikelytoforgettoupdatetherun-bindings-testsresultsinfact.
Therefore,buildbotsdonottreatthetestfailureasafailure.
Inthisway,therun-bindings-testsresultsintheWebKitrepositoryaresometimeswrong.
Ifyoufindit,pleaserebaselinetherun-bindings-testsbeforemakingyourpatch.
Ifyoumakeyourpatchwithoutrebaseliningthetestresults,
therun-bindings-testsresultswillincludethechangesthathadbeencausedbypreviouspatches,
whichwouldbeunreadableforyouandreviewers.
Anyway,ideallyallpeopleshouldupdatetherun-bindings-testsresultsiftheirpatchchangesthebehaviorofcodegenerators.
Whereisthebindingscodegenerated?
ByreadingthisdocumentyoucanlearnhowIDLattributeswork.
However,thebestpracticetounderstandIDLattributesistotrytouse
someIDLattributesandwatchwhatkindofbindingscodeisgenerated.
IfyoutouchanyIDLfile,allIDLfilesarerebuilt.
Thecodegenerationisdoneattheveryearlystepofthe./webkit-buildcommand,
soyoucanobtainthegeneratedcodein1minute.
IncaseofXXX.idlintheReleasebuild,thebindingscodeisgenerated
inthefollowingfiles（"Release"becomes"Debug"intheDebugbuild）.
JavaScriptCore:
WebKitBuild/Release/DerivedSources/WebCore/JSXXX.h
WebKitBuild/Release/DerivedSources/WebCore/JSXXX.cpp
ObjC:
WebKitBuild/Release/DerivedSources/WebCore/DOMXXX.h
WebKitBuild/Release/DerivedSources/WebCore/DOMXXX.mm
GObject:
WebKitBuild/Release/DerivedSources/webkit/WebKitDOMXXX.h
WebKitBuild/Release/DerivedSources/webkit/WebKitDOMXXX.cpp
CPP:
WebKitBuild/Release/DerivedSources/WebCore/WebDOMXXX.h
WebKitBuild/Release/DerivedSources/WebCore/WebDOMXXX.cpp
BasicnamingrulesofIDLattributes
ThereareafewrulesinnamingIDLattributes:
AnameshouldbealignedwiththeWebIDLspecasmuchaspossible.
JavaScriptCore-specificIDLattributesareprefixedby"JS".
ObjC-specificIDLattributesareprefixedby"ObjC".
GObject-specificIDLattributesareprefixedby"GObject".
CPP-specificIDLattributesareprefixedby"CPP".
IDLattributesforcustombindingsareprefixedby"Custom".
Forexample,[JSNoStaticTables],[CustomGetter],etc.
IDLattributes
Inthefollowingexplanations,（i）,（m）,（a）or（p）meansthatagiven
IDLattributecanbespecifiedoninterfaces,methods,attributesand
parameters,respectively.Forexample,（a,p）meansthattheIDL
attributecanbespecifiedonattributesandparameters.
[TreatNullAs]（a,p）,[TreatUndefinedAs]（a,p）
ThespecofTreatNullAs（Note:
TheWebKitbehaviorexplainedbelowisdifferentfromthespec）
ThespecofTreatUndefinedAs（Note:
TheWebKitbehaviorexplainedbelowisdifferentfromthespec）
Summary:
TheycontrolthebehaviorwhenaJavaScriptnullorundefinedispassedtoaDOMStringattributeorparameter.
Usage:
Thepossibleusageis[TreatNullAs=NullString]or[TreatUndefinedAs=NullString].
TheycanbespecifiedonDOMStringattributesorDOMStringparametersonly:
[TreatNullAs=NullString]attributeDOMStringstr;
voidfunc（[TreatNullAs=NullString,TreatUndefinedAs=NullString]DOMStringstr）;
[TreatNullAs=NullString]indicatesthatifaJavaScriptnullispassedtotheattributeorparameter,
thenitisconvertedtoaWebKitnullstring,forwhichbothString:
:
IsEmpty（）andString:
:
IsNull（）willreturntrue.
Without[TreatNullAs=NullString],aJavaScriptnullisconvertedtoaWebKitstring"null".
[TreatNullAs=NullString]inWebKitcorrespondsto[TreatNullAs=EmptyString]intheWebIDLspec.
Unlessthespecspecifies[TreatNullAs=EmptyString],youshouldnotspecify[TreatNullAs=NullString]inWebKit.
[TreatUndefinedAs=NullString]indicatesthatifaJavaScriptundefinedispassedtotheattributeorparameter,
thenitisconvertedtoaWebKitnullstring,forwhichbothString:
:
IsEmpty（）andString:
:
IsNull（）willreturntrue.
Without[TreatUndefinedAs=NullString],aJavaScriptundefinedisconvertedtoaWebKitstring"undefined".
[TreatUndefinedAs=NullString]inWebKitcorrespondsto[TreatUndefinedAs=EmptyString]intheWebIDLspec.
Unlessthespecspecifies[TreatUndefinedAs=EmptyString],youshouldnotspecify[TreatUndefinedAs=NullString]inWebKit.
Note:
Fornowthesoleusageof[TreatUndefinedAs=NullString]isnotallowed.
[TreatUndefinedAs=NullString]mustbeusedwith[TreatNullAs=NullString],i.e.[TreatNullAs=NullString,TreatUndefinedAs=NullString].
[TreatReturnedNullStringAs]（m,a）
Summary:
[TreatReturnedNullStringAs]controlsthebehaviorwhenaWebKitnullstringisreturnedfromtheWebCoreimplementation.
Usage:
Thepossibleusageis[TreatReturnedNullStringAs=Null],[TreatReturnedNullStringAs=Und
升级会员 